Tracing

For monitoring needs that go beyond logging, tracing can be enabled. Tracing makes it possible to track key events that relate to access requests.

The tracing functionality in ADS is based on OpenTelemetry (OT), relying on the OpenTelemetry Java agent to orchestrate the feature, but any agent that conforms to or implements the OpenTelemetry API version 1.3 could be used.

For visualization and monitoring assistance, the tracing information produced by ADS can be published to other tools, for example, Jaeger or Prometheus.

note

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

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 Logging enhanced with tracing information 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 produced when a call to fetch an attribute can result in a cache hit instead of the attribute connector itself.

note

In this implementation, spans are created for requests served from the REST endpoint of ADS. No extra features are implemented for the legacy SOAP endpoint. Any tracing shown for the SOAP endpoint would be information produced by default by the OpenTelemetry agent.

Handling of W3C context

If ADS receives an access request that includes a W3C trace context, it does not define a new trace. Instead, all spans are created within that context.

Handling of correlation information

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

Running ADS with the OpenTelemetry Java agent

The first step is to download the OpenTelemetry Java agent:

https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent-all.jar

note

The implementation has been tested with OpenTelemetry Java agent version 1.3.

To enable the auto-instrumentation of the OT agent, the -javaagent flag is added to the classpath together with the specifications needed for other options, such as the exporter. In the example below that is the Jaeger exporter (which assumes access to a Jaeger instance).

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

java -javaagent:<path_to_file>/opentelemetry-javaagent-all.jar \ 
  -Dotel.resource.attributes=service.name=<service-name-in-telemetry-ui> \
  -Dotel.traces.exporter=jaeger \
  -Dotel.exporter.jaeger.endpoint=http://<jaeger-instance:port> -cp \
   <path_to_file>/access-decision-service-<version>.jar com.axiomatics.ads.App server \
   <path_to_file>/deployment.yaml       

Further resources

• See OpenTelemetry Instrumentation for Java - Getting Started for more information about setting up the OpenTelemetry Java agent
• See OpenTelemetry SDK Autoconfigure - Exporters for more information on exporters.

Running ADS with the Application Insights Java agent

note

For this implementation, users of Azure Monitoring should use version 3.2.x of the Application Insights Java agent, as that supports OpenTelemetry API versions later than 1.2.0.

1. Export an environment variable with the instrumentation key of the Application Insights resource:

export APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=${Ikey}

2. Download the latest auto-instrumentation Java OpenTelemetry-based agent for Application Insights from here: https://github.com/microsoft/ApplicationInsights-Java/releases/
3. Initialize an ADS instance as in the example:

java -javaagent:<path_to_file>/applicationinsights-agent-<version>.jar -cp <path_to_file>/access-decision-service-<version>.jar com.axiomatics.ads.App server <path_to_file>/deployment.yaml

4. Then, log in to the Azure account and open your Application Insights Resource (it may take a few minutes for data to show up in the portal).

This will provide both tracing and metrics information to Azure Monitor.

Further resources

• See Azure Monitor Application Insights documentation for more information about the configuration.