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.

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter