Skip to content

Latest commit

 

History

History
71 lines (59 loc) · 4.19 KB

tracing.md

File metadata and controls

71 lines (59 loc) · 4.19 KB
description
Tracing and instrumentation based on OpenTracing.

Tracing

RecallGraph supports distributed tracing in its HTTP API, based on the OpenTracing standard.

A suite of libraries, services and plugins has been created specifically to allow Foxx microservices to be traced using the OpenTracing specification. These include a client library, a trace collector and a number of reporter plugins to push traces from the collector to different destinations.

These projects are well documented, and should be sufficient to help you get started with tracing RecallGraph (or any other trace-enabled foxx microservice). To get started, you can begin with the foxx-tracer documentation. Some of those instructions are repeated here for quick reference.

Runtime Setup

  1. Install the collector service and follow its setup instructions. Add any reporter plugins that you need.
  2. In RecallGraph's settings, there is a param named sampling-probability. You can set this to a value between 0 and 1 (both inclusive) to tell the tracer how often to record a trace for incoming requests. For example, if sampling-probability = 0.1, then roughly 1 out of 10 requests will be traced. Regardless of this param's value, a trace can be force-recorded or force-suppressed using the x-force-sample header parameter. See Recording Traces for details.

Recording Traces

For all HTTP endpoints, there are 4 trace-specific headers available that can be used for the following:

  1. Propagate a running trace from the client to your application.
  2. Force the application to record or suppress a trace for the request, regardless of the sampling-probability setting.

The headers (all optional) are as follows:

Header Description
x-baggage A JSON object containing key-value pairs that will set as the baggage for all spans recorded for this request.
x-force-sample An optional boolean that control whether the decision to record a trace should be forced, suppressed or be left to the application to decide. If true a sample is forced. If false no sample is taken. If left blank, the application decides based on the sampling-probability configuration parameter.
x-parent-span-id A span ID (belonging to an ongoing trace) under which to create the top level span of the traced request. This header must be accompanied by a non-emtpy TRACE_ID header. All spans generated with the application will now have this span ID as an ancestor.
x-trace-id

The trace ID under which to record all new spans. If unspecified, a new trace is started and is assigned a randomly generated UUID.

Note that if a new trace is started by foxx-tracer, the subsequent root span's span ID will not be same as the generated trace ID.