opentelemetry_api 0.5.0-dev.2 copy "opentelemetry_api: ^0.5.0-dev.2" to clipboard
opentelemetry_api: ^0.5.0-dev.2 copied to clipboard

discontinued
retracted[pending analysis]

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.

1
likes
0
points
17
downloads

Publisher

verified publisheropen-telemetry.com

Weekly Downloads

OpenTelemetry API for Dart

Homepage
Repository (GitHub)
View/report issues

License

(pending) (license)

Dependencies

fixnum

More

Packages that depend on opentelemetry_api