opentelemetry_api 0.5.0-dev.2

OpenTelemetry API for Dart

OpenTelemetry for Dart

This library is a fork of the original work done by Workiva Inc.

I (Andreas Gorges) converted it to null-safety and split it up into independend submodules to make integration and usage easier. Please be aware that this is a pre-release and the API will certainly change.

The WEB part ist not yet included.

Package	Description
opentelemetry_api	The Open Telemetry API
opentelemetry_sdk	The Open Telemetry SDK
opentelemetry_otlp	The Open Telemetry Protocol
opentelemetry_otlp_http	The OTLP over http exporter
opentelemetry_otlp_grpc	The OTLP over grpc exporter (not available yet)
opentelemetry_shelf	Open Telemetry Middleware for the shelf package (not available yet)

The rest of this README file is the original and does not reflect the current state of the API. More cleanup is needed.

Original README

This repo is intended to be the Dart implementation of the OpenTelemetry project, with a long-term goal of being open sourced.

All contributions and designs should follow the OpenTelemetry specification in an effort to be consistent with all other languages.

Getting Started

First, you will need to configure at least one exporter. An exporter determines what happens to the spans you collect. The current options are:

Exporter	Description
CollectorExporter	Sends Spans to a configured opentelemetry-collector.
ConsoleExporter	Prints Spans to the console.

Span Exporters

CollectorExporter

The CollectorExporter requires a Uri of the opentelemetry-collector instance's trace collector.

import 'package:opentelemetry/sdk.dart' as otel_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));

ConsoleExporter

The ConsoleExporter has no requirements, and has no configuration options.

import 'package:opentelemetry/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();

Span Processors

Next, you will need at least one span processor. A span processor is responsible for collecting the spans you create and feeding them to the exporter. The current options are:

SpanProcessor	Description
BatchSpanProcessor	Batches spans to be exported on a configured time interval.
SimpleSpanProcessor	Executes the provided exporter immediately upon closing the span.

BatchSpanProcessor

BatchSpanProcessors collect up to 2048 spans per interval, and executes the provided exporter on a timer.

Option	Description	Default
maxExportBatchSize	At most, how many spans are processed per batch.	512
scheduledDelay	How long to collect spans before processing them.	5000 ms

import 'package:opentelemetry/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.BatchSpanProcessor(exporter, scheduledDelay: 10000);

SimpleSpanProcessor

A SimpleSpanProcessor has no configuration options, and executes the exporter when each span is closed.

import 'package:opentelemetry/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.SimpleSpanProcessor(exporter);

Tracer Provider

A trace provider registers your span processors, and is responsible for managing any tracers.

Option	Description	Default
processors	A list of SpanProcessors to register.	A SimpleSpanProcessor configured with a ConsoleExporter.

import 'package:opentelemetry/sdk.dart' as otel_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
final processor = otel_sdk.BatchSpanProcessor(exporter);

// Send spans to a collector every 5 seconds
final provider = otel_sdk.TracerProvider([processor]);

// Optionally, multiple processors can be registered
final provider = otel_sdk.TracerProvider([
  otel_sdk.BatchSpanProcessor(otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'))),
  otel_sdk.SimpleSpanProcessor(otel_sdk.ConsoleExporter())
]);

// Register the tracer provider as a global, so the MSDK middleware has access to it.
otel_sdk.registerGlobalTracerProvider(provider);

final tracer = provider.getTracer('instrumentation-name');
// or
final tracer = otel_sdk.globalTracerProvider.getTracer('instrumentation-name');

Tracer Provider with Browser Performance Features

A web-specific trace provider is also available. This trace provider makes available configurable options using the browser's performance API.

import 'package:opentelemetry/sdk.dart' as otel_sdk;
import 'package:opentelemetry/web_sdk.dart' as web_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
final processor = otel_sdk.BatchSpanProcessor(exporter);

// This provider is configured to create tracers which use the browser's
// performance API instead of Dart's DateTime class when determining
// timestamps for any spans they create.
final provider = web_sdk.WebTracerProvider(
  processors: [processor],
  timeProvider: web_sdk.WebTimeProvider()
);

// This tracer has been configured to use the browser's performance API when
// determining timestamps for any spans it creates.
final tracer = provider.getTracer('instrumentation-name');

// Or, these trace providers can also be registered globally.
otel_sdk.registerGlobalTracerProvider(provider);
final tracer = otel_sdk.globalTracerProvider.getTracer('instrumentation-name');

Important Note: Span timestamps resulting from use of this trace provider may be inaccurate if the executing system is suspended for sleep. See https://github.com/open-telemetry/opentelemetry-js/issues/852 for more information.

Collecting Spans

To start a span, execute startSpan on the tracer with the name of what you are tracing. When complete, call end on the span.

final span = tracer.startSpan('doingWork');
...
span.end();

To create children spans, you must set the parent span as "current", and execute work within withContext.

final checkoutSpan = tracer.startSpan('checkout');
withContext(setSpan(Context.current, checkoutSpan), () {
  final ringUpSpan = tracer.startSpan('ringUp');
  ...
  ringUpSpan.end();
  final receiveSpan = tracer.startSpan('receiveCash');
  ...
  receiveSpan.end();
  final returnSpan = tracer.startSpan('returnChange');
  ...
  returnSpan.end();
});
checkoutSpan.end();

To avoid needing to pass spans around as arguments to other functions, you can get the current span with Context.current.span.

doWork() {
  Span parentSpan = Context.current.span;

  Context.current.withSpan(parentSpan).execute(() {
    Span span = tracer.startSpan('doWork');
    ...
    span.end();
  });
}

Development

In order to generate protobuf definitions, you must have protoc installed and available in your path.