dartastic_opentelemetry 0.9.5

OpenTelemetry SDK for Dart and Flutter. Distributed tracing, metrics, OTLP exporters (gRPC/HTTP), and context propagation for observability backends.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.9.5

This is 1.1.0-beta code with a 0.9.5 version stamp to get the important fixes out to non-beta users before the v1 release.

1.1.0-beta - 2026-05-07

Changed

• Bumped dartastic_opentelemetry_api to ^1.0.0-beta.2 (Zone-based context propagation, contributed to the API by Kevin Moore @kevmoo; the cross-isolate isRemote fix in beta.1; new DatabaseResource.dbCollectionName, DatabaseResource.dbResponseReturnedRows, and UserSemantics.userRoles semconv enums in beta.2; and the breaking removal of the singular UserSemantics.userRole in beta.2).
• Breaking: Tracer.withSpan and Tracer.withSpanAsync now propagate context via Zones (Context.runSync / Context.run) instead of mutating the static Context.current. Async callbacks within a spanned scope now correctly observe the active span across await boundaries; concurrent withSpanAsync calls no longer race on the global static.
• Breaking: Tracer.startSpan no longer auto-activates the returned span (matching the new API contract and the OpenTelemetry specification). Use OTel.withSpan / OTel.withSpanAsync (or the equivalent on Tracer, or the startActiveSpan / startActiveSpanAsync convenience methods) to make a span active for a scope.
• Breaking: removed Tracer.recordSpan and Tracer.recordSpanAsync. They were redundant with startActiveSpan/Async (which expose the span to fn) and the name was unclear ("record what?"). Migration: a one-liner tracer.recordSpan(name: x, fn: f) becomes OTel.tracer().startActiveSpan(name: x, fn: (_) => f()). For the explicit lifecycle, use tracer.startSpan(...) + OTel.withSpan(span, fn) + try/catch/finally with span.end() in finally.
• Added OTel.withSpan(span, fn) and OTel.withSpanAsync(span, fn) static convenience methods that delegate to the default tracer — saves callers from threading a Tracer reference for the common activation case. Both accept APISpan (matching the API contract for cross-implementation interop).
• Breaking: renamed the SDK Logger class to OTelLogger to avoid clashing with package:logging's Logger. Migration: replace Logger (the SDK type) with OTelLogger in your code. OTel.logger(...) and OTel.loggerProvider().getLogger(...) continue to return the same instances, only the type name changed. LoggerProvider, APILogger, and other Logger*-prefixed symbols are unchanged.
• Breaking: Tracer.startSpanWithContext no longer mutates Context.current. It is now a thin wrapper around startSpan(name, context: ctx) and is @Deprecated. Activate the returned span explicitly with Tracer.withSpan / withSpanAsync.
• Tracer.startSpan: when both context and parentSpan are provided with different traces, the explicit parentSpan now wins for traceId and traceFlags resolution. Previously the SDK would build an internally inconsistent SpanContext (context's traceId + parentSpan's spanId) which the new API validation correctly rejects.
• Tracer.startSpan: replaced the stale effectiveContext != Context.root identity-style check with a content-based check (effectiveContext.span != null + always read effectiveContext.spanContext). The old check skipped parent inheritance whenever Context.current == Context.root, which is the case inside an isolate spawned via Context.runIsolate() (the API attaches the propagated context as both the isolate's current and root). Combined with the API beta.1 isRemote fix, trace continuity now works end-to-end across runIsolate.

Added

• OTel.contextKey<T>(name) now accepts an optional isTransferable flag (default false) which is forwarded to the API. Custom context keys must opt in to cross-isolate transfer; built-in Baggage and SpanContext always transfer.
• Re-exported ServerResource and UrlResource semantic enums from the API.
• New regression test (tracer_methods_test.dart) verifying that concurrent withSpanAsync operations isolate their active span — would catch any future regression of the Zone migration.

Fixed

• test/web/util/zip/gzip_web_test.dart: replaced a corrupt hardcoded base64 gzip blob (CRC mismatch — the browser's DecompressionStream, Python's gzip, and Node all reject it) with a freshly-generated one (mtime=0 for a deterministic header). Pre-existing bug; the test had never passed under a strict gzip decoder.
• Tooling: Makefile test-safe and test-web targets pointed at tool/run_tests.sh and tool/web_tests.sh, neither of which existed. Repointed test-safe at the existing tool/test.sh (used by CI). Added tool/web_tests.sh running dart test -p chrome ./test/web.
• CI: added a test-web job to .github/workflows/dart.yml that runs tool/web_tests.sh in Chrome on every push and PR — web tests previously only ran locally on demand.
• Documentation: every example file (and every code snippet in the SDK and API READMEs) now uses typed enum keys for span/log/baggage attributes — never raw strings. Examples without a matching OTel-semconv enum define a small local ExampleAttribute / ExampleBaggage / DemoAttribute enum at the top of the file to demonstrate the recommended pattern (the placeholder name is ExampleAttribute/ExampleBaggage rather than AppAttribute so readers rename it for their domain instead of copying it verbatim; the redundant app. prefix was also dropped from invented demo keys). Replaces deprecated net.peer.*, client.ip, http.url, http.response_content_length with their modern semconv equivalents (ServerResource.serverAddress/Port, ClientResource.clientAddress, UrlResource.urlFull, HttpResource.responseBodySize).
• Examples updated for spec-aligned behavior:
  • example.dart, grafana_cloud_env_example.dart, grafana/grafana_cloud_env_example.dart: replaced 'url.full' / 'url.path' / 'net.peer.name' / 'net.peer.port' string literals with the new UrlResource and ServerResource enums.
  • isolate_context_example.dart: rewritten to use tracer.withSpanAsync so the parent SpanContext propagates into runIsolate, and to avoid capturing non-sendable SDK objects in the isolate closure. Also dropped a private src/ import.
  • propagator_example.dart: built the inject Context from span.spanContext directly instead of relying on the deprecated auto-activation; Step 5 now reports the child span's own ids (and parent linkage) rather than the active context's.

1.0.2-alpha - 2026-04-19

Fixed

• Fixed OTel.defaultEndpoint to use the OTLP/HTTP port 4318 instead of the gRPC port 4317, matching the default http/protobuf protocol per the OpenTelemetry specification (#29). Removed the conditional port-swap workarounds in trace and logs configuration.
• Fixed SimpleLogRecordProcessor.shutdown() not flushing pending exports (#28).
• Fixed flaky OtlpGrpcLogRecordExporter endpoint empty host defaults to 127.0.0.1 test that depended on no process listening on port 4317.

Changed

• MetricsConfiguration now defaults to the HTTP/protobuf protocol (consistent with the trace and logs pipelines and with the OpenTelemetry specification). Set OTEL_EXPORTER_OTLP_PROTOCOL=grpc (or OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=grpc) to opt back into gRPC.

Added

• Public exporter getter on PeriodicExportingMetricReader and exporters getter on CompositeMetricExporter for introspection and testability.

1.0.1-alpha - 2026-04-05

• Added a BaggageSpanProcessor that adds Baggage as SpanAttributes

1.0.0-alpha - 2026-04-02

Added

• Log Signal SDK implementation
• Upgraded to dartastic_opentelemetry_api: ^1.0.0-alpha with Log Signal API

0.9.3 - 2025-10-25

Added

• New W3CTracePropagator
• Defined all 74 env var constants

Fixed

• Fixed env vars on Flutter web
• Fixed service.name, service.version, now from OTEL_RESOURCE_ATTRIBUTES

Removed

• OTEL_SERVICE_VERSION, not in the spec

0.9.2 - 2025-10-12

• Default to INFO OTel logging.

0.9.1 - 2025-10-04

• Bumped API to 0.8.8 to fix logging.

0.9.0 - 2025-10-04

• Added support for OTEL_EXPORTER_OTLP_HEADERS for http and grpc exporters for trace and metrics
• Added support for all other exporter env vars
• Documented OTEL_* env var usage, added grafana examples
• Certificates env vars may not work yet tests skipped.

0.8.7 - 2025-09-29

• Upgraded to api 0.8.7. Upgraded all dependencies including grpc to 4.1
• Respected all OTel env vars when no explicit values are specified, uses OTEL_CONSOLE_EXPORTER
• Fixed default export, uses http/protobuf by default, not grpc
• Fixed issue with creation of the grpc exporter
• ConsoleExporter now only created on env vars or explicity
• Minor, doc, dart format, improved .gitignore, removed generated mistakenly committed

0.8.6 - 2025-09-24

• Minor, cleaning, format, doc.

0.8.5 - 2025-06-14

• prep for wondrous otel demo, upgrade to api 0.8.3, span toString

0.8.4 - 2025-06-06

• fix: Issue #3 - Fixed Metric generics for Histogram.
• chore: All 445 tests pass, 12 ignored, 0 fail, no crashes, thoroughly applied OTel.shutdown in test tearDowns.

0.8.3 - 2025-06-04

• fix: Issue 4, lack of span export

0.8.2 - 2025-05-06

• README.md updates

0.8.1 - 2025-05-06

• README.md updates

0.8.0 - 2025-05-01

Added

• Initial public release of the OpenTelemetry SDK for Dart
• Complete implementation of the OpenTelemetry API
• Full tracing implementation with span processors
• Multiple exporters: OTLP (gRPC and HTTP), Console, Zipkin
• Resource providers for service information
• Sampler implementations: AlwaysOn, AlwaysOff, TraceIdRatio, ParentBased
• Context propagation: W3C Trace Context, W3C Baggage, Composite
• Batch processing with configurable parameters
• Comprehensive test suite
• Complete examples for various use cases

Compatibility

• Implements OpenTelemetry SDK specification v1.0.0-rc3
• Requires opentelemetry_api: ^0.8.0
• Compatible with OpenTelemetry Protocol (OTLP) v0.18.0