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 Emissary-ingress 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. Emissary-ingress 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.
TracingService manifest configures Emissary-ingress to use an external trace visualization service:
|gives the URL of the external HTTP trace service.||ex. |
|provides the driver information that handles communicating with the service||enum:|
|provides additional configuration options for the selected |
|Deprecated - it is recommend that you switch to using |
|configure tags to attach to traces. See section below for more details.|
|(optional) if present, specifies a list of the propogation modes to be used||enum: |
|(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:
hostheader should be specified as the
methodheader should be specified as the
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 the
x-client-trace-idheader 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, setting
1%will result in only
1%of client requests with the appropriate headers to be force traced. Defaults to 100.
When collecting traces, Emissary-ingress 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 Emissary-ingress 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 request
environment- set tag from an environment variable
literal- set tag based on a configured literal value
Each custom_tag supports setting oneOf
environment. Each tag should have its own entry in
access_token_fileprovides the location of the file containing the access token to the LightStep API.
collector_endpointgives the API endpoint of the Zipkin service where the spans will be sent. The default value is
collector_endpoint_versiongives the transport version used when sending data to your Zipkin collector. The default value is
HTTP_JSONand it must be one of
collector_endpoint_hostnamesets 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_128bitwhether a 128-bit
trace idwill be used when creating a new trace instance. Defaults to
true. Setting to
falsewill result in a 64-bit trace id being used.
shared_span_contextwhether client and server spans will share the same
span id. The default value is
service_namethe name of the service which is attached to the traces. The default value is
You may only use a single
TracingService manifest per Emissary-ingress deployment. Ensure ambassador_id is set correctly in the