OpenTelemetry SDK for Dart #

Dartastic is an OpenTelemetry SDK to add standard observability to Dart applications. Dartastic can be used with any OTel backend, it's standards-compliant.

Flutter developers should use the Flutterific OpenTelemetry SDK which builds on top of Dartastic OTel.

The Dartastic and Flutterrific OTel SDK has been proposed for Donation to the CNCF. We need YOU to grow the Dartastic community and make this SDK the standard for Flutter and Dart OTel. Please use it, submit issues, support us with stars and contribute PRs. We are looking for contributors and maintainers. Also, please support the development by subscribing at Dartastic.io and gain early access to the Flutter SDK and the Wondrous Demo.

Dartastic.io provides an OpenTelemetry support, training, consulting and an Observability backend customized for Flutter apps, Dart backends, and any other service or process that produces OpenTelemetry data.

Features #

• 🚀 Friendly API: An easy to use, discoverable, immutable, typesafe API that feels familiar to Dart developers.
• 📐 Standards Compliant: Complies with the OpenTelemetry specification so it's portable and future-proof.
• 🌎 Ecosystem:
  • Dartastic.io is an OTel backend for Dart with a generous free tier, professional support and enterprise features.
  • Flutterrific OTel adds Dartastic OTel to Flutter apps with ease. Observe app routes, errors, web vitals and more with as few as two lines of code.
• 💪🏻 Powerful:
  • Propagate OpenTelemetry Context across async gaps and Isolates.
  • Pick from a rich set of Samplers including On/Off, probability and rate-limiting.
  • Automatically capture platform resources on initialization.
  • No skimping - If it's optional in the spec, it's included in Dartastic.
  • A pluggable and extensible API and SDK enables implementation freedom.
• 🧷 Typesafe Semantics: Ensure you're speaking the right language with a massive set of enums matching the OpenTelemetry Semantics Conventions.
• 📊 Excellent Performance:
  • Low overhead
  • Batch processing
  • Performance test suite for proven benchmarks
• 🐞 Well Tested: Good test coverage (>85%).
• 📃 Quality Documentation: If it's not clearly documented, it's a bug. Extensive examples and best practices are provided. See the examples directory.
• 🎬 Demo The Wonderous OpenTelemetry Demo demonstrates
  gskinner's Wonderous App with instrumentation for OpenTelemetry.
• ✅ Supported Telemetry Signals and Features:
  • Tracing with span processors and samplers
  • Metrics collection and aggregation
  • Context propagation
  • Baggage management
  • Logging is not available yet

Dartastic OTel is suitable for Dart backends, CLIs or any Dart application.

Dartastic OTel API is the API for the Dartastic OTel SDK. The dartastic_opentelemetry_api exists as a standalone library to strictly adhere to the OpenTelemetry specification which separates API and the SDK. All OpenTelemetry API classes on in dartastic_opentelemetry_api.

Flutterrific OTel adds Dartastic OTel to Flutter apps with ease. Sign Up at Dartastic.io for early access to this soon to be open source.

Dartastic.io is an OpenTelemetry backend based on Elastic with a generous free tier.

Dartastic and Flutterrific OTel are made with 💙 by Michael Bushe at Mindful Software.

Mindful Software offers paid support, consulting and developing on Flutter, OpenTelemetry and UI Architecture.

Getting started #

Include this in your pubspec.yaml:

dependencies:
  dartastic_opentelemetry: ^0.9.3

The entrypoint to the SDK is the OTel class. OTel has static "factory" methods for all OTel API and SDK objects. OTel needs to be initialized first to point to an OpenTelemetry backend. Initialization does a lot of work under the hood including gathering a rich set of standard resources for any OS that Dart runs in. It prepares for the creation of the global default TracerProvider with the serviceName and a default Tracer, both created on first use. All configuration, include Trace and Metric exporters, can be made in code via OTel.initialize().
Codeless configuration can be done with standard OpenTelemetry environmental variables either through POSIX variable or -D or --define for Dart or with --dart-define for Flutter apps.

Environment Variables #

Dartastic OpenTelemetry supports is working on support for all standard OpenTelemetry environment variables as defined in the OpenTelemetry Specification.

Environment variables provide a convenient way to configure OpenTelemetry without hardcoding values. All environment variable names are available as strongly-typed constants in the SDK for compile-time safety and IDE autocomplete. See lib/src/environment/env_constants.dart for a complete list.

How It Works #

Dart environment variables can be set in two ways:

1. System Environment Variables (Non-web only): Traditional POSIX environment variables

   export OTEL_SERVICE_NAME=my-service
   dart run
   

2. Compile-time Constants (All platforms including Flutter web): Passed during compilation/execution

   For Dart commands (dart run, dart compile, dart test):

   # Using --define (or -D shorthand)
   dart run --define=OTEL_SERVICE_NAME=my-service
   dart compile exe -D=OTEL_SERVICE_NAME=my-service -o myapp
   dart test -DOTEL_SERVICE_NAME=my-service
   

   For Flutter commands:

   # Flutter uses --dart-define (note the different flag name)
   flutter run --dart-define=OTEL_SERVICE_NAME=my-service
   flutter build apk --dart-define=OTEL_SERVICE_NAME=my-service
   

Priority: Compile-time constants (--define or --dart-define) take precedence over system environment variables. Explicit parameters to OTel.initialize() override both. Thus, POSIX env vars cannot override --dart-defines and neither POSIX env vars nor --dart-defines can override code. This is sensible and reduces security vectors.

Web Support: Flutter web and Dart web only support compile-time constants (--define or --dart-define), as browser environments don't have access to system environment variables.

Using Environment Variable Constants #

All OpenTelemetry environment variable names are available as typed constants:

import 'package:dartastic_opentelemetry/dartastic_opentelemetry.dart';

void main() {
  // Reference constants instead of strings
  final serviceName = EnvironmentService.instance.getValue(otelServiceName);
  final endpoint = EnvironmentService.instance.getValue(otelExporterOtlpEndpoint);
  
  print('Service: $serviceName');
  print('Endpoint: $endpoint');
}

Constants are defined for all 74 OpenTelemetry environment variables. See lib/src/environment/env_constants.dart for the complete list.

Supported Environmental Variables #

Service Configuration

OTLP Exporter Configuration

Signal-Specific Configuration

Traces

Metrics

For the complete list of all 74 supported environment variables with full documentation, see lib/src/environment/env_constants.dart.

Usage Examples #

Dart Application with Environment Variables

Note the ',' in OTEL_RESOURCE_ATTRIBUTES for POSIX env vars but a ';' for --dart-define. This is due to a Dart quirk.

# Set environment variables
export OTEL_SERVICE_NAME=my-backend-service
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.2.3,deployment.environment=prod"
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=api-key=your-key
export OTEL_LOG_LEVEL=DEBUG

# Run your application
dart run bin/my_app.dart

Flutter Application with --dart-define

flutter run \
  --dart-define=OTEL_SERVICE_NAME=my-flutter-app \
  --dart-define=OTEL_RESOURCE_ATTRIBUTES="service.version=1.2.3;deployment.environment=prod"
  --dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector:4317 \
  --dart-define=OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
  --dart-define=OTEL_EXPORTER_OTLP_HEADERS=api-key=your-key

Flutter Web (requires --dart-define)

# Web MUST use --dart-define (environment variables don't work in browsers)
flutter run -d chrome \
  --dart-define=OTEL_SERVICE_NAME=my-web-app \
  --dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=https://collector:4318

Combining Both (--dart-define wins)

# Environment variable
export OTEL_SERVICE_NAME=from-environment

# --dart-define takes precedence
dart run --dart-define=OTEL_SERVICE_NAME=from-dart-define

# Result: Uses "from-dart-define"

In Code

import 'package:dartastic_opentelemetry/dartastic_opentelemetry.dart';

void main() async {
  // OTel.initialize() automatically reads environment variables
  // when parameters are not explicitly provided
  await OTel.initialize();
  
  // Environment variables are read automatically:
  // - OTEL_SERVICE_NAME
  // - OTEL_EXPORTER_OTLP_ENDPOINT
  // - OTEL_EXPORTER_OTLP_PROTOCOL
  // - And 90+ others...
  
  // Explicit parameters override environment variables
  await OTel.initialize(
    serviceName: 'explicit-service',  // Overrides OTEL_SERVICE_NAME
    endpoint: 'https://override:4318', // Overrides OTEL_EXPORTER_OTLP_ENDPOINT
  );
  
  // You can also read environment variables directly
  final endpoint = EnvironmentService.instance.getValue(otelExporterOtlpEndpoint);
  print('Using endpoint: $endpoint');
}

Testing with Environment Variables #

Integration tests can use real environment variables:

# Run tests with environment variables
OTEL_SERVICE_NAME=test-service dart test

# Run tests with --dart-define
dart test --dart-define=OTEL_SERVICE_NAME=test-service

# Run the provided integration test script
./tool/test_env_vars.sh

The SDK includes an integration test suite (test/integration/environment_variables_test.dart) and a test script (tool/test_env_vars.sh) that demonstrates proper environment variable usage.

Minimal Code Example #

import 'package:dartastic_opentelemetry/dartastic_opentelemetry.dart';

void main() async {
  // Initialize - automatically reads environment variables
  await OTel.initialize();

  // Get the default tracer
  final tracer = OTel.tracer();

  // Create a span
  final span = tracer.startSpan('my-operation');
  
  try {
    // Your code here
    await doWork();
  } catch (e, stackTrace) {
    span.recordException(e, stackTrace: stackTrace);
    span.setStatus(SpanStatusCode.error, 'Operation failed');
  } finally {
    span.end();
  }
}

Since dartastic_opentelemetry exports all the classes of opentelemetry_api, refer to opentelemetry_api for documentation of API classes.

See the /example folder for more examples.

OpenTelemetry Metrics API #

The Metrics API in OpenTelemetry provides a way to record measurements about your application. These measurements can be exported later as metrics, allowing you to monitor and analyze the performance and behavior of your application.

Concepts #

• MeterProvider: Entry point to the metrics API, responsible for creating Meters
• Meter: Used to create instruments for recording measurements
• Instrument: Used to record measurements
  • Synchronous instruments: record measurements at the moment of calling their APIs
  • Asynchronous instruments: collect measurements on demand via callbacks

Instrument Types #

• Counter: Synchronous, monotonic increasing counter (can only go up)
• UpDownCounter: Synchronous, non-monotonic counter (can go up or down)
• Histogram: Synchronous, aggregable measurements with statistical distributions
• Gauge: Synchronous, non-additive value that represents current state
• ObservableCounter: Asynchronous version of Counter
• ObservableUpDownCounter: Asynchronous version of UpDownCounter
• ObservableGauge: Asynchronous version of Gauge

Usage Pattern #

Similar to the Tracing API, the metrics API follows a multi-layered factory pattern:

1. API Layer: Defines interfaces and provides no-op implementations
2. SDK Layer: Provides concrete implementations
3. Flutter Layer: Adds UI-specific functionality

The API follows the pattern of using factory methods for creation rather than constructors:

// Get a meter from the meter provider
final meter = OTel.meterProvider().getMeter('component_name');

// Create a counter instrument
final counter = meter.createCounter('my_counter');

// Record measurements
counter.add(1, {'attribute_key': 'attribute_value'});

For asynchronous instruments:

// Create an observable counter
final observableCounter = meter.createObservableCounter(
  'my_observable_counter',
  () => [Measurement(10, {'attribute_key': 'attribute_value'})],
);

Understanding Metric Types and When to Use Them #

Integration with Dartastic/Flutterrific #

This API implementation follows the same pattern as the tracing API, where the creation of objects is managed through factory methods. This allows for a clear separation between API and SDK, and ensures that the metrics functionality can be used in a no-op mode when the SDK is not initialized.

Commercial Support #

Dartastic.io provides an OpenTelemetry Observability backend specifically built for Dart and Flutter applications. Features include:

• Enhanced tracing with source code integration
• Real-time user monitoring for Flutter apps
• Advanced dashboard and visualization
• Integration with native platforms
• Generous free tier and enterprise support options

Roadmap #

• ❌ Enhanced metrics support
• ❌ Support for Zipkin, Jaeger
• ❌ Integration with common Dart libraries (Dio, etc.)
• ❌ Context propagation through http, Android, iOS, WebViews

CNCF Contribution and Alignment #

This project aims to align with Cloud Native Computing Foundation (CNCF) best practices:

• Interoperability - Works with the broader OpenTelemetry ecosystem
• Specification compliance - Strictly follows the OpenTelemetry specification
• Vendor neutrality - Provides a vendor-neutral implementation

License #

Apache 2.0 - See the LICENSE file for details.

Commercial Support #

Mindful Software offers paid Dartastic support, and consulting and developing on Flutter, OpenTelemetry and UI Architecture.

Dartastic.io provides an OpenTelemetry support, training, consulting, enhanced private packages and an Observability backend customized for Flutter apps, Dart backends, and any other service or process that produces OpenTelemetry data. Dartastic.io is built on open standards, specifically catering to Flutter and Dart applications with the ability to show Dart source code lines and function calls from production errors and logs.

Dartastic.io offers:

• Free, paid, and enterprise support
• Packages with advanced features not available in the open source offering
• Native code integration and Real-Time User Monitoring for Flutter apps
• Multiple backends (Elastic, Grafana) customized for Flutter apps.

AI Usage #

Practically all code in Dartastic was generated via Claude. EVERY character is reviewed by a human. Tests may need improved quality.

Additional information #

• Flutter developers should use the Flutterific OTel SDK.
• Dart backend developers should use the Dartastic OTel SDK.
• Also see:
  • Dartastic.io the Flutter OTel backend
  • The OpenTelemetry Specification