The most recent patch for this version is 26.2.1.  Learn more

Skip to main content
Version: 26.2

Distributed tracing

Enable tracing to track key access request events beyond standard logging.

ADS tracing is based on OpenTelemetry (OTel)Opens in a new tab and uses the OpenTelemetry Java agent. You can use any agent compatible with OpenTelemetry API version 1.3 or later.

Tracing data from ADS can be published to any OpenTelemetry-compatible tracing backend, such as Jaeger or Zipkin.

note

If you use Azure Monitoring, use the Application Insights Java agent for both tracing and metrics. See Application Insights integration for details.

When you run ADS with an OTel-compatible Java agent, you can also enhance log entries with trace and span identifiers as attributes in the Mapped Diagnostic Context (MDC). See Enhance logging with tracing information in MDC below and Route log output with Logback for Logback configuration details.

Spans and traces​

A span is a unit of work within a trace, and a trace is a tree of spans. For each request, ADS defines the following spans in the trace:

  • A span for the whole request.

  • A span per call to an attribute connector.

    The span starts when ADS sends a request to an attribute connector and ends when the attribute connector returns a response. Each span contains a set of attributes that serve as an identifier correlating to a specific attribute connector. ADS also creates spans when an attribute request results in a cache hit instead of calling the attribute connector.

W3C context​

If ADS receives an access request that includes a W3C trace contextOpens in a new tab, it does not define a new trace. Instead, ADS creates all spans within that existing context.

Correlation information​

If the access request contains a header with correlation information, ADS attaches that information to the span associated with the single request. For more information, see Authorization decisions.

Run ADS with an OTel-compatible Java agent​

To run ADS with any OpenTelemetry (OTel)-compatible Java agent, follow the steps below:

  1. Download an OTel-compatible Java agent of your choice (such as the official OpenTelemetry Java agent) as described in the provider's documentation.

  2. Enable the agent's auto-instrumentation by adding the -javaagent flag to the Java command, along with any specifications needed for your specific agent or other options.

    java -javaagent:<path_to_agent>/<opentelemetry-compatible-agent>.jar -jar <path_to_ads_jar>/access-decision-service-<version>.jar
    note

    Pass configuration parameters for the agent as Java system properties (-D flags) or as environment variables, depending on the specific agent you choose.

Further resources​

Enhance logging with tracing information in MDC​

You can enhance log entries from ADS with trace and span identifiers by including these as attributes within the Mapped Diagnostic Context (MDC). This requires an active OTel-compatible Java agent and a compatible Logback configuration. Read the Route log output with Logback section for details.

No code changes are required. Start the application with the following system property:

-Dotel.instrumentation.logging.mdc.injection.enabled=true

Once enabled, the OTel-compatible Java agent injects trace and span information (specifically trace_id, span_id, and trace_flags) for each log event. For more details on the types of information injected into the MDC, refer to the OpenTelemetry MDC documentationOpens in a new tab.

Within the JSON logging format, MDC values are included by default. A typical log entry looks like the following:

{
  ...
  "trace_id": "1af7651916cd43dd8448eb211c80319c",
  "trace_flags": "01",
  "span_id": "e8a9037cfbc10a3a"
  ...
}

MDC included in log output (excerpt)

tip

To customize which MDC fields appear in the logs, consult your Logback encoder configuration.