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
- Create a CR Telemetry to enable tracing.
- Attach this CR Telemetry to a Gateway using a CR GatewayParameters.
- 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
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,
serviceNamedefaults to<gateway-name>.<gateway-namespace>.
sampling
The sampling strategy controls how many traces are recorded and exported.
- Tail sampling (collector decides):
Set
sampling.strategytoalways: {}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.,
randomorinheritParentDecisionif 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
gRPCorHTTP - 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.
Configure the Gateway
Reference the previously created CR GatewayParameters from the CR Gateway.