Skip to main content

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

Version: 26.1

Tracing

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

ADS tracing is based on OpenTelemetry (OT)Opens in a new tab and uses the OpenTelemetry Java agent. Any agent compatible with OpenTelemetry API version 1.3 can be used.

Tracing data from ADS can be published to visualization and monitoring tools such as Jaeger or Prometheus.

note

Users of Azure Monitoring should use the Application Insights Java agent for both tracing and metrics. See Application Insights integration for details

Furthermore, when the OpenTelemetry Java agent is in use, log entries emitted by ADS can be enhanced with trace and span identifiers as attributes in the Mapped Diagnostic Context (MDC). See Enhance logging with tracing information in MDC for more information.

Spans and traces​

A span is a unit of work within a trace, and a trace is a tree of spans. For ADS, this means that for each request, the following spans are defined in the trace:

  • A span for the whole request.

  • A span per call to an attribute connector.

    The span is initialized when a request is sent to an attribute connector from the engine and concludes once the attribute connector returns a response. Τhe spans contain a set of attributes as an identifier that can correlate to each attribute connector. Spans are also created 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, all spans are created within that context.

Correlation information​

If the access request contains a header with correlation information, that information is attached to the span associated with the single request. For more information, see Correlation in tracing.

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

    Configuration parameters for the agent are typically passed 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​

Log entries from ADS can be enhanced with trace and span identifiers by including these as attributes within the Mapped Diagnostic Context (MDC). This enhancement, however, is dependent on the activation of an OTel-compatible Java agent, which ADS utilizes for tracing capabilities, and your Logback configuration (read the Logback section for details).

No code changes are required, just ensure the application is started with the following system property:

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

Once enabled, the OTel-compatible Java agent integrates 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.