Skip to main content
Version: 1.16

Tracing

You can enable tracing, for monitoring needs that go beyond logging. Tracing makes it possible to track key events that relate to access requests.

The tracing functionality in ADS is based on OpenTelemetry (OT)Opens in a new tab, 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, like 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 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 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.

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.
note

ADS supports OpenTelemetry Java agent 1.32.x. Later OpenTelemetry upgrades (e.g. 2.0.0) may not be compatible.

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. In the example below you can see 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-<version>.jar \ 
 -Dotel.resource.attributes=service.name=<service-name-in-exporter-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​

Run ADS with the Application Insights Java agent​

note

For this implementation, you must have version 3.2.x or later of the Application Insights Java agent to use Azure Monitoring. This is necessary because only these versions support OpenTelemetry API versions 1.2.0 and above.

To run ADS with the Application Insights Java agent, follow the steps below:

  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 hereOpens in a new tab.

  3. Initialize an ADS instance as shown in the example below:

    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. Log in to the Azure account and open your Application Insights Resource.

    info

    It may take a few minutes for data to show up in the portal.

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

Further resources​