opentelemetry_sls 0.15.1 copy "opentelemetry_sls: ^0.15.1" to clipboard
opentelemetry_sls: ^0.15.1 copied to clipboard

Platformweb

A framework for collecting traces from applications.

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'));

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();

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);

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);

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');

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');

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.

0
likes
90
pub points
65%
popularity

Publisher

unverified uploader

A framework for collecting traces from applications.

Repository (GitHub)
View/report issues

Documentation

API reference

License

unknown (LICENSE)

Dependencies

collection, fixnum, http, logging, protobuf, quiver

More

Packages that depend on opentelemetry_sls