Skip to main content
Version: 2.2

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 the OpenTelemetry Java agent​

To run ADS with the OpenTelemetry Java agent (OT agent), follow the steps below:

  1. First download the OpenTelemetry Java agent as described in Download OpenTelemetry Java agentOpens in a new tab.

To enable the auto-instrumentation of the OT agent, add the -javaagent flag to the classpath along with the specifications needed for other options, such as the exporter. By default, the OTLP exporter is set.

Configuration parameters are passed as Java system properties (-D flags) or as environment variables.

important

In the sample below replace any <placeholders> with your specific setup values.

OTEL_SERVICE_NAME=<service-name> \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
java -javaagent:<path_to_javaagent>/opentelemetry-javaagent.jar -jar <path_to_ads_jar>/access-decision-service-<version>.jar

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 the OpenTelemetry Java agent, which ADS utilizes for tracing capabilities.

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 OpenTelemetry Java agent integrates trace and span information, specifically trace_id, span_id, and trace_flags, into the MDC for each log event. For more details on the types of information injected into the MDC, refer to theOpenTelemetry 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:

{
  "sequenceNumber": 0,
  "timestamp": 1746001522964,
  "level": "INFO",
  "threadName": "http-nio-8080-exec-3",
  "loggerName": "com.axiomatics.audit.ads.eval",
  "mdc": {
    "trace_id": "1af7651916cd43dd8448eb211c80319c",
    "trace_flags": "01",
    "span_id": "e8a9037cfbc10a3a"
  },
  "message": "<EvaluationEvent>...</EvaluationEvent>",
  "throwable": null
}

MDC included in log output (excerpt)

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