DocsEdge StackTracing Service
Tracing Service
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.
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 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:
Field | Description | values |
---|---|---|
service | gives the URL of the external HTTP trace service. | ex. example-zipkin:9411 |
driver | provides the driver information that handles communicating with the service | enum:zipkin datadog opentelemetry |
config | provides additional configuration options for the selected driver . Supported configuration for each driver is found below. | |
tag_headers | Deprecated - it is recommend that you switch to using custom_tags | |
custom_tags | configure tags to attach to traces. See section below for more details. | |
propagation_modes | (optional) if present, specifies a list of the propogation modes to be used | enum: ENVOY B3 TRACE_CONTEXT |
sampling | (optional) if present, specifies some target percentages of requests that will be traced. |
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.
Supported Tracing Drivers
The TracingService
currently supports the following drivers:
zipkin
datadog
opentelemetry
Sampling
Configuring sampling
will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields:
client
: percentage of requests that will be force traced if thex-client-trace-id
header is set. Defaults to 100.random
: percentage of requests that will be randomly traced. Defaults to 100.overall
: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). This field functions as an upper limit on the total configured sampling rate. For instance, settingclient
to100%
butoverall
to1%
will result in only1%
of client requests with the appropriate headers to be force traced. Defaults to 100.
Custom Tags and Tag Headers
When collecting traces, Ambassador Edge Stack will attach tags to the span
's that are generated which are useful for observability. See the Envoy Tracing Docs for the default list of data collected.
Previous versions of Ambassador Edge Stack only supported adding additional tags through the use of the tag_headers
field. This field is now deprecated and it is recommended to use custom_tags
which supports a more powerful set of features for adding additional tags to a span.
custom_tags
provides support for configuring additional tags based on Envoy Custom Tags. The following custom tag kinds supported are:
request_header
- set tag from header in the requestenvironment
- set tag from an environment variableliteral
- set tag based on a configured literal value
Each custom_tag supports setting oneOf request_header
, literal
or environment
. Each tag should have its own entry in custom_tags
.
For example:
Zipkin Driver Configurations
collector_endpoint
gives the API endpoint of the Zipkin service where the spans will be sent. The default value is/api/v2/spans
collector_endpoint_version
gives the transport version used when sending data to your Zipkin collector. The default value isHTTP_JSON
and it must be one ofHTTP_JSON
orHTTP_PROTO
.collector_endpoint_hostname
sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster.trace_id_128bit
whether a 128-bittrace id
will be used when creating a new trace instance. Defaults totrue
. Setting tofalse
will result in a 64-bit trace id being used.shared_span_context
whether client and server spans will share the samespan id
. The default value istrue
.
Datadog Driver Configurations
service_name
the name of the service which is attached to the traces. The default value isambassador
.
OpenTelemetry Driver Configurations
service_name
the name of the service which is attached to traces. The default value isambassador
.