Skip to content

Latest commit

 

History

History
507 lines (415 loc) · 20 KB

QUICKSTART.md

File metadata and controls

507 lines (415 loc) · 20 KB

OpenTelemetry QuickStart

OpenTelemetry can be used to instrument code for collecting telemetry data. For more details, check out the OpenTelemetry Website.

Libraries that want to export telemetry data using OpenTelemetry MUST only depend on the opentelemetry-api package and should never configure or depend on the OpenTelemetry SDK. The SDK configuration must be provided by Applications which should also depend on the opentelemetry-sdk package, or any other implementation of the OpenTelemetry API. This way, libraries will obtain a real implementation only if the user application is configured for it. For more details, check out the Library Guidelines.

Tracing

In the following, we present how to trace code using the OpenTelemetry API. Note: Methods of the OpenTelemetry SDK should never be called.

First, a Tracer must be acquired, which is responsible for creating spans and interacting with the Context. A tracer is acquired by using the OpenTelemetry API specifying the name and version of the library instrumenting the instrumented library or application to be monitored. More information is available in the specification chapter Obtaining a Tracer.

Tracer tracer =
    OpenTelemetry.getTracer("instrumentation-library-name","semver:1.0.0");

Create basic Span

To create a basic span, you only need to specify the name of the span. The start and end time of the span is automatically set by the OpenTelemetry SDK.

Span span = tracer.spanBuilder("my span").startSpan();
try (Scope scope = tracer.withSpan(span)) {
	// your use case
	...
} catch (Throwable t) {
    Status status = Status.UNKNOWN.withDescription("Change it to your error message");
    span.setStatus(status);
} finally {
    span.end(); // closing the scope does not end the span, this has to be done manually
}

Create nested Spans

Most of the time, we want to correlate spans for nested operations. OpenTelemetry supports tracing within processes and across remote processes. For more details how to share context between remote processes, see Context Propagation.

For a method a calling a method b, the spans could be manually linked in the following way:

void a() {
  Span parentSpan = tracer.spanBuilder("a")
        .startSpan();
  b(parentSpan);
  parentSpan.end();
}
void b(Span parentSpan) {
  Span childSpan = tracer.spanBuilder("b")
        .setParent(parentSpan)
        .startSpan();
  // do stuff
  childSpan.end();
}

The OpenTelemetry API offers also an automated way to propagate the parentSpan:

void a() {
  Span parentSpan = tracer.spanBuilder("a").startSpan();
  try(Scope scope = tracer.withSpan(parentSpan)){
    b();
  } finally {
    parentSpan.end();
  }
}
void b() {
  Span childSpan = tracer.spanBuilder("b")
     // NOTE: setParent(parentSpan) is not required anymore, 
     // `tracer.getCurrentSpan()` is automatically added as parent
    .startSpan();
  // do stuff
  childSpan.end();
}

To link spans from remote processes, it is sufficient to set the Remote Context as parent.

Span childRemoteParent = tracer.spanBuilder("Child").setParent(remoteContext).startSpan();

Span Attributes

In OpenTelemetry spans can be created freely and it's up to the implementor to annotate them with attributes specific to the represented operation. Attributes provide additional context on a span about the specific operation it tracks, such as results or operation properties.

Span span = tracer.spanBuilder("/resource/path").setSpanKind(Span.Kind.CLIENT).startSpan();
span.setAttribute("http.method", "GET");
span.setAttribute("http.url", url.toString());

Some of these operations represent calls that use well-known protocols like HTTP or database calls. For these, OpenTelemetry requires specific attributes to be set. The full attribute list is available in the Semantic Conventions in the cross-language specification.

Create Spans with events

Spans can be annotated with named events that can carry zero or more Span Attributes, each of which is itself a key:value map paired automatically with a timestamp.

span.addEvent("Init");
...
span.addEvent("End");
Attributes eventAttributes = Attributes.of(
    "key", AttributeValue.stringAttributeValue("value"),
    "result", AttributeValue.longAttributeValue(0L));

span.addEvent("End Computation", eventAttributes);

Create Spans with links

A Span may be linked to zero or more other Spans that are causally related. Links can be used to represent batched operations where a Span was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch.

Link link1 = SpanData.Link.create(parentSpan1.getContext());
Link link2 = SpanData.Link.create(parentSpan2.getContext());
Span child = tracer.spanBuilder("childWithLink")
        .addLink(link1)
        .addLink(link2)
        .addLink(parentSpan3.getContext())
        .addLink(remoteContext)
    .startSpan();

For more details how to read context from remote processes, see Context Propagation.

Context Propagation

In-process propagation leverages gRPC Context, a well established context propagation library, contained in a small artifact, which is non-dependent on the entire gRPC engine.

OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.

The following presents an example of an outgoing HTTP request using HttpURLConnection.

// Tell OpenTelemetry to inject the context in the HTTP headers
HttpTextFormat.Setter<HttpURLConnection> setter =
  new HttpTextFormat.Setter<HttpURLConnection>() {
    @Override
    public void put(HttpURLConnection carrier, String key, String value) {
        // Insert the context as Header
        carrier.setRequestProperty(key, value);
    }
};

URL url = new URL("http://127.0.0.1:8080/resource");
Span outGoing = tracer.spanBuilder("/resource").setSpanKind(Span.Kind.CLIENT).startSpan();
try (Scope scope = tracer.withSpan(outGoing)) {
  // Semantic Convention.
  // (Observe that to set these, Span does not *need* to be the current instance.)
  outGoing.setAttribute("http.method", "GET");
  outGoing.setAttribute("http.url", url.toString());
  HttpURLConnection transportLayer = (HttpURLConnection) url.openConnection();
  // Inject the request with the *current*  Context, which contains our current Span.
  OpenTelemetry.getPropagators().getHttpTextFormat().inject(Context.current(), transportLayer, setter);
  // Make outgoing call
} finally {
  outGoing.end();
}
...

Similarly, the text-based approach can be used to read the W3C Trace Context from incoming requests. The following presents an example of processing an incoming HTTP request using HttpExchange.

HttpTextFormat.Getter<HttpExchange> getter =
  new HttpTextFormat.Getter<HttpExchange>() {
    @Override
    public String get(HttpExchange carrier, String key) {
      if (carrier.getRequestHeaders().containsKey(key)) {
        return carrier.getRequestHeaders().get(key).get(0);
      }
      return null;
    }
};
...
public void handle(HttpExchange httpExchange) {
  // Extract the SpanContext and other elements from the request.
  Context extractedContext = OpenTelemetry.getPropagators().getHttpTextFormat()
        .extract(Context.current(), httpExchange, getter);
  Span serverSpan = null;
  try (Scope scope = ContextUtils.withScopedContext(extractedContext)) {
    // Automatically use the extracted SpanContext as parent.
    serverSpan = tracer.spanBuilder("/resource").setSpanKind(Span.Kind.SERVER)
        .startSpan();
    // Add the attributes defined in the Semantic Conventions
    serverSpan.setAttribute("http.method", "GET");
    serverSpan.setAttribute("http.scheme", "http");
    serverSpan.setAttribute("http.host", "localhost:8080");
    serverSpan.setAttribute("http.target", "/resource");
    // Serve the request
    ...
  } finally {
    if (serverSpan != null) {
      serverSpan.end();
    }
  }
}

Metrics

Spans are a great way to get detailed information about what your application is doing, but what about a more aggregated perspective? OpenTelemetry provides supports for metrics, a time series of numbers that might express things such as CPU utilization, request count for an HTTP server, or a business metric such as transactions.

All metrics can be annotated with labels: additional qualifiers that help describe what subdivision of the measurements the metric represents.

The following is an example of counter usage:

// Gets or creates a named meter instance
Meter meter = OpenTelemetry.getMeter("instrumentation-library-name","semver:1.0.0");

// Build counter e.g. LongCounter 
LongCounter counter = meter
        .longCounterBuilder("processed_jobs")
        .setDescription("Processed jobs")
        .setUnit("1")
        .build();

// It is recommended that the API user keep a reference to a Bound Counter for the entire time or 
// call unbind when no-longer needed.
BoundLongCounter someWorkCounter = counter.bind(Labels.of("Key", "SomeWork"));

// Record data
someWorkCounter.add(123);

// Alternatively, the user can use the unbounded counter and explicitly
// specify the labels set at call-time:
counter.add(123, Labels.of("Key", "SomeWork"));

Observer is an additional instrument supporting an asynchronous API and collecting metric data on demand, once per collection interval.

The following is an example of observer usage:

// Build observer e.g. LongObserver
LongObserver observer = meter
        .observerLongBuilder("cpu_usage")
        .setDescription("CPU Usage")
        .setUnit("ms")
        .build();

observer.setCallback(
        new LongObserver.Callback<LongObserver.ResultLongObserver>() {
          @Override
          public void update(ResultLongObserver result) {
            // long getCpuUsage()
            result.observe(getCpuUsage(), Labels.of("Key", "SomeWork"));
          }
        });

Tracing SDK Configuration

The configuration examples reported in this document only apply to the SDK provided by opentelemetry-sdk. Other implementation of the API might provide different configuration mechanisms.

The application has to install a span processor with an exporter and may customize the behavior of the OpenTelemetry SDK.

For example, a basic configuration instantiates the SDK tracer registry and sets to export the traces to a logging stream.

// Get the tracer
TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();

// Set to export the traces to a logging stream
tracerProvider.addSpanProcessor(
    SimpleSpanProcessor.newBuilder(
        new LoggingSpanExporter()
    ).build());

Sampler

It is not always feasible to trace and export every user request in an application. In order to strike a balance between observability and expenses, traces can be sampled.

The OpenTelemetry SDK offers three samplers out of the box:

  • AlwaysOnSampler which samples every trace regardless of upstream sampling decisions.
  • AlwaysOffSampler which doesn't sample any trace, regardless of upstream sampling decisions.
  • Probability which samples a configurable percentage of traces, and additionally samples any trace that was sampled upstream.

Additional samplers can be provided by implementing the io.opentelemetry.sdk.trace.Sampler interface.

TraceConfig alwaysOn = TraceConfig.getDefault().toBuilder().setSampler(
        Samplers.alwaysOn()
).build();
TraceConfig alwaysOff = TraceConfig.getDefault().toBuilder().setSampler(
        Samplers.alwaysOff()
).build();
TraceConfig half = TraceConfig.getDefault().toBuilder().setSampler(
        Samplers.probability(0.5)
).build();
// Configure the sampler to use
tracerProvider.updateActiveTraceConfig(
    half
);

Span Processor

Different Span processors are offered by OpenTelemetry. The SimpleSpanProcessor immediately forwards ended spans to the exporter, while the BatchSpanProcessor batches them and sends them in bulk. Multiple Span processors can be configured to be active at the same time using the MultiSpanProcessor.

tracerProvider.addSpanProcessor(
    SimpleSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
);
tracerProvider.addSpanProcessor(
    BatchSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
);
tracerProvider.addSpanProcessor(MultiSpanProcessor.create(Arrays.asList(
            SimpleSpanProcessor.newBuilder(new LoggingSpanExporter()).build(),
            BatchSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
)));

Exporter

Span processors are initialized with an exporter which is responsible for sending the telemetry data a particular backend. OpenTelemetry offers four exporters out of the box:

  • In-Memory Exporter: keeps the data in memory, useful for debugging.
  • Jaeger Exporter: prepares and sends the collected telemetry data to a Jaeger backend via gRPC.
  • Zipkin Exporter: prepares and sends the collected telemetry data to a Zipkin backend via the Zipkin APIs.
  • Logging Exporter: saves the telemetry data into log streams.
  • OpenTelemetry Exporter: sends the data to the OpenTelemetry Collector (not yet implemented).

Other exporters can be found in the OpenTelemetry Registry.

tracerProvider.addSpanProcessor(
    SimpleSpanProcessor.newBuilder(InMemorySpanExporter.create()).build());
tracerProvider.addSpanProcessor(
    SimpleSpanProcessor.newBuilder(new LoggingSpanExporter()).build());

ManagedChannel jaegerChannel =
    ManagedChannelBuilder.forAddress([ip:String], [port:int]).usePlaintext().build();
JaegerGrpcSpanExporter jaegerExporter = JaegerGrpcSpanExporter.newBuilder()
    .setServiceName("example").setChannel(jaegerChannel).setDeadline(30000)
    .build();
tracerProvider.addSpanProcessor(BatchSpanProcessor.newBuilder(
    jaegerExporter
).build());

TraceConfig

The TraceConfig associated with a TracerSdkProvider can be updated via system properties, environment variables and builder set* methods.

// Get TraceConfig associated with TracerSdkProvider 
TraceConfig traceConfig = OpenTelemetrySdk.getTracerProvider().getActiveTraceConfig();

// Get TraceConfig Builder
Builder builder = traceConfig.toBuilder();

// Read configuration options from system properties
builder.readSystemProperties();

// Read configuration options from environment variables
builder.readEnvironmentVariables()

// Set options via builder.set* methods, e.g.
builder.setMaxNumberOfLinks(10);

// Update the resulting TraceConfig instance
OpenTelemetrySdk.getTracerProvider().updateActiveTraceConfig(builder.build());

Supported system properties and environment variables:

System property Environment variable Purpose
otel.config.sampler.probability OTEL_CONFIG_SAMPLER_PROBABILITY Sampler which is used when constructing a new span (default: 1)
otel.config.max.attrs OTEL_CONFIG_MAX_ATTRS Max number of attributes per span, extra will be dropped (default: 32)
otel.config.max.events OTEL_CONFIG_MAX_EVENTS Max number of Events per span, extra will be dropped (default: 128)
otel.config.max.links OTEL_CONFIG_MAX_LINKS Max number of Link entries per span, extra will be dropped (default: 32)
otel.config.max.event.attrs OTEL_CONFIG_MAX_EVENT_ATTRS Max number of attributes per event, extra will be dropped (default: 32)
otel.config.max.link.attrs OTEL_CONFIG_MAX_LINK_ATTRS Max number of attributes per link, extra will be dropped (default: 32)
otel.config.max.attr.length OTEL_CONFIG_MAX_ATTR_LENGTH Max length of string attribute value in characters, too long will be truncated (default: unlimited)

Logging and Error Handling

OpenTelemetry uses java.util.logging to log information about OpenTelemetry, including errors and warnings about misconfigurations or failures exporting data.

By default, log messages are handled by the root handler in your application. If you have not installed a custom root handler for your application, logs of level INFO or higher are sent to the console by default.

You may want to change the behavior of the logger for OpenTelemetry. For example, you can reduce the logging level to output additional information when debugging, increase the level for a particular class to ignore errors coming from that class, or install a custom handler or filter to run custom code whenever OpenTelemetry logs a particular message.

Examples

## Turn off all OpenTelemetry logging 
io.opentelemetry.level = OFF
## Turn off logging for just the BatchSpanProcessor 
io.opentelemetry.sdk.trace.export.BatchSpanProcessor.level = OFF
## Log "FINE" messages for help in debugging 
io.opentelemetry.level = FINE

## Sets the default ConsoleHandler's logger's level 
## Note this impacts the logging outside of OpenTelemetry as well 
java.util.logging.ConsoleHandler.level = FINE

For more fine-grained control and special case handling, custom handlers and filters can be specified with code.

// Custom filter which does not log errors that come from the export
public class IgnoreExportErrorsFilter implements Filter {

 public boolean isLoggable(LogRecord record) {
    return !record.getMessage().contains("Exception thrown by the export");
 }
}
## Registering the custom filter on the BatchSpanProcessor
io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensions.logging.IgnoreExportErrorsFilter