opentelemetry_sls

Description:

opentelemetry sls

OpenTelemetry for Dart #
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_sls/sdk.dart' as otel_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
copied to clipboard
ConsoleExporter
The ConsoleExporter has no requirements, and has no configuration options.
import 'package:opentelemetry_sls/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
copied to clipboard
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


scheduledDelayMillis
How long to collect spans before processing them.
5000 ms



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

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.BatchSpanProcessor(exporter, scheduledDelayMillis: 10000);
copied to clipboard
SimpleSpanProcessor
A SimpleSpanProcessor has no configuration options, and executes the exporter when each span is closed.
import 'package:opentelemetry_sls/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.SimpleSpanProcessor(exporter);
copied to clipboard
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_sls/sdk.dart' as otel_sdk;
import 'package:opentelemetry_sls/api.dart';

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.TracerProviderBase(processors: [processor]);

// Optionally, multiple processors can be registered
final provider = otel_sdk.TracerProviderBase(processors: [
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.
registerGlobalTracerProvider(provider);

final tracer = provider.getTracer('instrumentation-name');
// or
final tracer = globalTracerProvider.getTracer('instrumentation-name');
copied to clipboard
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_sls/sdk.dart' as otel_sdk;
import 'package:opentelemetry_sls/web_sdk.dart' as web_sdk;
import 'package:opentelemetry_sls/api.dart';

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.
registerGlobalTracerProvider(provider);
final tracer = globalTracerProvider.getTracer('instrumentation-name');
copied to clipboard
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();
copied to clipboard
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();
copied to clipboard
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();
});
}
copied to clipboard
Development #
In order to generate protobuf definitions, you must have protoc installed and available in your path.