Search the Docs

TracingService Plugin

Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics.

The TracingService

When enabled, the TracingService will instruct Ambassador Edge Stack to initiate a trace on requests by generating and populating an x-request-id HTTP header. Services can make use of this x-request-id header in logging and forward it in downstream requests for tracing. Ambassador Edge Stack also integrates with external trace visualization services, including LightStep and Zipkin-compatible APIs such as Zipkin and Jaeger to allow you to store and visualize traces. You can read further on Envoy's Tracing capabilities.

A TracingService manifest configures Ambassador Edge Stack to use an external trace visualization service:

kind: TracingService
name: tracing
service: "example-zipkin:9411"
driver: zipkin
config: {}
- ":authority"
- ":path"
  • service gives the URL of the external HTTP trace service.
  • driver provides the driver information that handles communicating with the service. Supported values are lightstep, zipkin, and datadog.
  • config provides additional configuration options for the selected driver.
  • tag_headers (optional) if present, specifies a list of other HTTP request headers which will be used as tags in the trace's span.

Please note that you must use the HTTP/2 pseudo-header names. For example:

  • the host header should be specified as the :authority header; and
  • the method header should be specified as the :method header.

lightstep Driver Configurations

  • access_token_file provides the location of the file containing the access token to the LightStep API.

zipkin Driver Configurations

  • collector_endpoint gives the API endpoint of the Zipkin service where the spans will be sent. The default value is /api/v1/spans
  • trace_id_128bit whether a 128-bit trace id will be used when creating a new trace instance. Defaults to true. Setting to false will result in a 64-bit trace id being used.
  • shared_span_context whether client and server spans will share the same span id. The default value is true.

datadog Driver Configurations

  • service_name the name of the service which is attached to the traces. The default value is ambassador.

You may only use a single TracingService manifest per Ambassador deployment. Ensure ambassador_id is set correctly in the TracingService manifest.


Check out the DataDog and Zipkin HOWTOs.


We’re here to help. If you have questions, join our Slack or contact us.