Skip to content

Latest commit

 

History

History
75 lines (52 loc) · 4.39 KB

tracing.md

File metadata and controls

75 lines (52 loc) · 4.39 KB
Raw

Tracing

Azure SDK uses OpenTelemetery API implementation azure-core-tracing-opentelemetry plugin for enabling tracing on client libraries.

OpenTelemetry is one of the popular open-source observability framework for generating, capturing, and collecting telemetry data for cloud-native software.

Configure Tracer

To enable tracing for the client libraries, the user will have to add azure-core-tracing-opentelemetry plugin and opentelemetry-sdk package dependency to their application.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
  <version>1.0.0-beta.4</version>
</dependency>

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>0.2.4</version>
</dependency>

Customizing Tracer spans:

Users can additionally create a root span in their application and pass it down to the client calls for encapsulating all the outgoing requests in the application. This can be done by using the Context parameter on the client methods.

Context traceContext = new Context(PARENT_SPAN_KEY, span);
appConfigClient.setConfigurationSettingWithResponse(new ConfigurationSetting().setKey("hello").setValue("world"), true, traceContext);

In case of no parent span provided, a new parent span will be created to encapsulate all the client libraries outgoing requests.

Each client call results in two spans, convenience layer span and outgoing HTTP request span.

Tracer Span Attributes

In addition to OpenTelemetry's required standard attributes mentioned here, client libraries annotates the spans with below mentioned attributes:

  • az.namespace: Microsoft resource provider namespaces mapped to Azure services.
  • x-ms-request-id: The unique identifier for the request.
  • span.kind: Describes the relationship between the Span, its parents, and its children in a Trace.
  • span.status.message: Represents the status of a finished Span.
  • span.status.code: Represents the status code of a finished Span.

Additional metadata about the operation being performed is captured in the span names. The HTTP span names are set to the URI path value and the library method invocation span is of the form <namespace qualified type>.<method name>.

For example, an App Configuration client request to set Configuration setting i.e appConfigClient.setConfigurationSettingWithResponse(new ConfigurationSetting().setKey("hello").setValue("world") will result two spans:

  • Library method span named AppConfig.setKey.
  • HTTP outgoing request span named /kv/hello.

Configure Exporter:

User applications can export traces to different distributed tracing stores (such as Zipkin, Jeager, Stackdriver Trace).

// 1. Configure exporter to export traces to Jaeger.
ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 14250).usePlaintext().build();
JaegerGrpcSpanExporter exporter = JaegerGrpcSpanExporter.newBuilder()
    .setChannel(channel)
    .setServiceName("Sample")
    .setDeadline(0)
    .build();
TracerSdkFactory tracerSdkFactory = (TracerSdkFactory) OpenTelemetry.getTracerFactory();
tracerSdkFactory.addSpanProcessor(SimpleSpansProcessor.newBuilder(exporter).build());

Configure Application insights

User applications can export traces to Application Insights dashboard by adding the Java in-process agent and the azure-core-tracing-opentelemetry package to their project.

More information about attaching the Java codeless in-process agent and Application Insights can be found here.