[ANN] OpenTelemetry 1.0 release

Hello, all!

After a number of years and false starts on trying to wrap my head around the metrics spec, I’m pleased to announce the release of the 1.0 edition of the hs-opentelemetry-* ecosystem!

OpenTelemetry is an open source observability framework that provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application.

The reason this is 1.0 and not yet another 0.x is that it is a big bang release with a number of breaking interface changes in order to hit full spec compliance. Prior versions of the library were operating on a 4+ year old version of the OTel specifications, and much has changed since then. Rather than trickle the remaining work out over a long tail of point releases, everything lands together: traces, metrics, and logs are all implemented, the SDK has been audited against the OpenTelemetry specification at version 1.55.0, and the full set of resource detectors is baked into the SDK. Logging and metrics have been “coming soon” for years now, but now they are here, for real!

Highlights

• Full conformance with the OTel 1.55.0 spec. (* bugs or oversights are possible, let me know if you spot something)
• New Amazonka and Gogol instrumentation packages
• Metrics! (Export using the OTel-native protocol, or provide your metrics as a scrapable Prometheus endpoint)
• Logs! (Hook into your existing log library of choice and have it correlated with your traces!)
• Inert instrumentation is 1,000x cheaper than before.
• Massive performance improvements. Hot-path code for tracing is 60-200x faster than before, depending on a number of factors. In trace ID and span ID generation are 60-100x cheaper than before, and a number of new techniques (SIMD acceleration, better OS-specific API usage, better thread-local RNG, etc) have been developed to reduce contention, reduce allocation overhead, and just be faster throughout.

Upgrading

There is a migration guide here, and for most of you the read will be short. If you are already running hs-opentelemetry in production you are running it for traces, since traces are all that existed until today, so the code you have to touch is mostly a single rename: InstrumentationLibrary is now InstrumentationScope, to match the spec. A type alias and an instrumentationScope constructor are provided, so it is a find-and-replace rather than an afternoon.

The part that YOU SHOULD REALLY CHECK CAREFULLY is not in your source at all. If you rely on specific attribute names, stop and check before you ship. A number of attributes have been renamed to conform to modern OpenTelemetry semantics. There is an environment variable you can set for subsystems to dual-write the old and new attribute names until you’ve migrated alerting, dashboards, SLOs, and so forth over to the new names. A renamed attribute does not break the build. It breaks weeks later, silently, when someone notices a dashboard flatlined or an alert that should have fired never did, because it was keyed to a name that no longer exists. The compiler cannot help you here, so you will have to look yourself.

Metrics and logs, of course, cannot break anything, because they didn’t really exist before.

What 1.0 leaves out

OTLP/HTTP with JSON encoding. The binary protobuf and gRPC transports are in place, but JSON is not since proto-lens doesn’t support it, and the demand for it is close to nil.

Thanks

A number of dedicated contributors have helped keep the lights on for the project during a very difficult time of life for me. In particular, I’d like to provide deep thanks to Oliver Charles, Patrick Brisbin, kakkun61, velveteer, Michael Peyton Jones.

Also, many thanks to Mercury, my employer, that gives me the chance to contribute to the ecosystem.

Development can be supported through GitHub Sponsors at https://github.com/sponsors/iand675.