Tracing

Tracing records the end-to-end path of a request as a set of timed operations (spans). It helps identify latency hotspots and locate failures, especially in distributed systems.

Airlock Microgateway can add gateway-specific attributes to spans, for example routing decisions and upstream/backend interactions. This provides visibility into how requests are handled at the gateway.

By default, Microgateway does not export traces to a tracing backend. This guide describes how to enable tracing export and configure sampling and the exporter endpoint.

Prerequisite

  • OpenTelemetry-compatible backend or collector able to receive trace telemetry.

Configuration

  1. Create a CR Telemetry to enable tracing.
  2. Attach this CR Telemetry to a Gateway using a CR GatewayParameters.
  3. Attaching the CR Telemetry to a Gateway determines which Gateways the tracing configuration applies to.

In the CR Telemetry, you define:

  • The sampling strategy (e.g., probabilistic, parent decision)
  • The OpenTelemetry-compatible backend/exporter endpoint where trace data is sent.

Configure the Telemetry

 
Example
apiVersion: microgateway.airlock.com/v1alpha1
kind: Telemetry
metadata:
  name: telemetry-example
  namespace: example-backend-gw
spec:
  tracing:
    provider:
      openTelemetry:
        serviceName: "telemetry-example"
        sampling:
          strategy:
            always: {}
        exporter:
          grpcEndpoint:
            uri: "http://<opentelemetry-collector.observability>:4317"

provider

This configuration enables the OpenTelemetry tracing provider. OpenTelemetry propagates trace context using W3C Trace Context headers (e.g., traceparent and tracestate).

serviceName

The serviceName is sent to the backend/collector to identify the source of trace data.

  • If set, the exporter uses the provided value.
  • If omitted, serviceName defaults to <gateway-name>.<gateway-namespace>.

sampling

The sampling strategy controls how many traces are recorded and exported.

  • Tail sampling (collector decides):
  • Set sampling.strategy to always: {} so that the Gateway forwards all traces and the collector applies tail-sampling policies.

  • Head sampling (gateway decides):
  • Use a head-sampling strategy (e.g., random or inheritParentDecision if you want sampling decisions to be made at the Gateway.

  • For more information about sampling, see Sampling Concept.

exporter

The exporter defines where trace data is sent. Supported options include:

  • Exporting via gRPC or HTTP
  • Encrypting the traffic with TLS.

In the example above, traces are exported via gRPC to an OpenTelemetry Collector in the observability namespace.

Configure the GatewayParameters

Reference the previously created CR Telemetry from the CR GatewayParameters.

 
Example
apiVersion: microgateway.airlock.com/v1alpha1
kind: GatewayParameters
metadata:
  name: gateway-parameters-example
  namespace: example-backend-gw
spec:
  ...
  defaults:
    telemetryRef:
      name: telemetry-example

Configure the Gateway

Reference the previously created CR GatewayParameters from the CR Gateway.

 
Example
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway-example
  namespace: example-backend-gw
spec:
  gatewayClassName: airlock-microgateway
  infrastructure:
    parametersRef:
      group: microgateway.airlock.com
      kind: GatewayParameters
      name: gateway-parameters-example
  ...