OpenTelemetry Dart Packages: A New Design Doc Lays Out the Namespace

OpenTelemetry for Dart is still early, and this week the open-telemetry/opentelemetry-dart repo shipped exactly one change: a design document. It landed as the package namespaces proposal (#7), merged on October 15 as commit 74827c2. The document now lives at docs/design/packages.md.

No code shipped. But for anyone planning to use or contribute to the Dart SDK, this document sets the names and structure that everything else will follow, so it is worth a read now while the shape is still open for discussion.

One package per app, not per signal

The core decision: Dart will publish all telemetry signals together, following the example of Python, .NET, Rust, Swift and Erlang rather than Java or JavaScript. App developers get a single dependency.

The document sketches three pubspec shapes:

# A Dart app
dependencies:
  opentelemetry: ^1.0.0

# A Flutter app
dependencies:
  opentelemetry_flutter: ^1.0.0

# A library author instrumenting their own package
dependencies:
  opentelemetry_api: ^1.0.0

Why not split metrics, traces and logs into separate packages like JavaScript does? The argument is the Dart AOT compiler tree shakes unused code. If you never record a metric, it is not compiled in, so bundle size concerns mostly disappear. The proposal also flags the honest cost of this choice: the project needs tests proving that apps which skip signals really do stay smaller, and it needs a policy for new or unstable signals. The recommendation there is pragmatic: alpha and beta signals ride along in the main package, documented as such.

The package map

The proposal defines a fixed set of package names on pub.dev:

  • opentelemetry_semantics: semantic conventions, generated by Weaver, plus a spec directory for Dart and Flutter federated definitions
  • opentelemetry_api: the API, published separately as the spec requires
  • opentelemetry_sdk: the SDK, which keeps the console and in memory exporters since they carry no heavy dependencies
  • opentelemetry_otlp_http: the OTLP HTTP exporter, with JSON encoding, gzip and certificate utilities
  • opentelemetry_otlp_grpc: the gRPC exporter, kept in its own package so web builds stay simple
  • opentelemetry_prometheus: the Prometheus exporter
  • opentelemetry and opentelemetry_flutter: the entry point packages users actually depend on

The gRPC split is the detail I find most sensible. The document says HTTP covers roughly 90 percent of real usage, and there is no dart:io on the web, so a hard gRPC dependency in the main SDK would hurt Flutter web users the most. Entry point packages re-export the API, so OTel.initialize() for Dart and FlutterOTel.initialize() for Flutter are the two expected entry calls, with Flutter getting extras like RUM.

Two smaller notes worth knowing. Zipkin is explicitly deprecated and not planned. And platform or vendor specific resource detectors must live outside the SDK as separate packages; only generic host, os, process and service detectors ship in the box.

Status and what to watch

The document is marked as a proposal and the PR invites discussion, so none of these names are locked yet. If you have opinions on pub.dev packaging, now is the cheap moment to comment.

  • Watch for the workspace bootstrapping work that this layout depends on. The proposal references a bootstrap branch as a companion effort.
  • Expect the API, SDK and semantics packages to appear first, since everything else depends on them.
  • The exporter packages arrive last. Until then, the existing donation SDK stays as the reference implementation that will get broken apart.

This is a low volume week in commit terms, one file and 176 added lines. For a project being bootstrapped, the design doc is more consequential than a handful of code commits would have been. If you plan to depend on or contribute to OpenTelemetry in Dart, read the proposal and leave feedback while the namespace is still on paper.

← All updates