Changelog

View Source

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

[1.1.4] - 2026-06-13

Changed

  • Factored the repeated try Expr catch _:_ -> Default end swallow idiom into shared helpers in instrument_lib: safe_call/1, safe_call/2 (fun-based) and safe_apply/4 (MFA-based, no closure). Converted the cold-path swallows (shutdown, force_flush, persistent_term:erase, logger:remove, ets:info, detector callbacks) across the span processor, exporters, registry, logger, flight recorder, resource detector, propagator and processors. Per-span hot paths, specific-class catches (error:badarg, race handling, exit:/throw:), try ... of ... catch blocks with guards and catches that log stay inline by design.
  • Bumped hackney 3.2.1 to 4.4.0 and the quickrand test dependency 1.7.0 to 2.0.7. Transitive deps updated via the lock file.

[1.1.3] - 2026-05-28

Fixed

  • OTP 29 compatibility: replaced the deprecated prefix catch operator with try ... catch ... end throughout src/ and test/. Under OTP 29 the prefix form emits a deprecation warning, which warnings_as_errors turned into a build failure.

Changed

  • CI now builds and runs the test suite on OTP 29, alongside OTP 27 and 28.
  • Bumped the meck test dependency to 1.2.0. Older versions use the deprecated prefix catch in their own source and fail to compile on OTP 29.

[1.1.2] - 2026-05-25

Fixed

  • A registry restart no longer silently drops previously-created OTel instruments. instrument_registry:init/1 recreated the ETS tables empty and reset the instrument_metrics index to [], but left the per-name persistent_term entries behind. The surviving {otel_instrument, Name} made instrument_meter:get_instrument/1 return a stale record, so create_counter / create_up_down_counter / create_histogram short-circuited and never re-registered the underlying metric, while the index stayed empty — the metric vanished from collect_all/0 and the Prometheus export even though add/record kept succeeding. init/1 now erases the stale otel_instrument, otel_instruments, instrument_metric, instrument_label, and instrument_label_overflow entries, so get_instrument/1 returns undefined after a restart and the metric self-heals on the next create_*. unregister_all clears the same set (it previously missed otel_instrument / otel_instruments).

[1.1.1] - 2026-05-16

Fixed

  • observable_counter instruments now render as Prometheus counter with the _total suffix instead of gauge, in both unlabeled and labeled exposition. Previously create_observable_instrument/3 hardcoded gauge-shaped underlying storage and the labeled write path tagged the vec as gauge, so tooling that relies on # TYPE … counter to decide rate-ability (Grafana, rate(), alerting rules) saw the wrong type.
  • instrument_meter:add/3 on a labeled up_down_counter no longer crashes on negative deltas. The labeled write path previously hardcoded counter-shaped vec storage and hit instrument_counter:inc_counter/2's Val >= 0 guard. It now routes through gauge-shaped vec storage with a sign split, so add(Instrument, -1, #{label => ...}) decrements the per-label-set value.

[1.1.0] - 2026-05-11

Changed

  • Histogram bucket counts and the running sum are now backed by a single OTP atomics array per histogram (slot 1 = IEEE-754 bits of the sum via CAS retry, slots 2..N+2 = signed int64 bucket counts via atomics:add/3). Drops the per-bucket NIF resources and makes get_histogram / collect ~1.5x faster; observe_histogram is unchanged. Counters, gauges, and up-down counters remain on the NIF path.
  • Histogram count and per-bucket count fields in the collected map are now integers, matching the instrument_metrics_exporter spec which already declared them as integer(). Callers that compared these fields with =:= against float() values must update their expectations.

Added

  • instrument_atomics module: thin wrapper over atomics providing signed-integer slots and IEEE-754 double slots via bit-cast with a CAS retry loop.

[1.0.0] - 2026-05-03

First stable release. Hardens the runtime under contention and at high cardinality, brings the OTLP path up to spec, fixes deadlock and leak risks in the export pipeline, and lands a full audit of the documentation against the actual public API.

Added

  • OTEL_METRIC_CARDINALITY_LIMIT (default 2000) caps distinct label sets per vector metric. Excess label sets aggregate into one shared series tagged otel.metric.overflow=true. Dropped count exposed via instrument_registry:cardinality_dropped/1.
  • instrument_otlp_retry module: bounded exponential backoff with Retry-After honoured, classifying transport and HTTP errors per the OTel spec. Configurable via OTEL_EXPORTER_OTLP_MAX_RETRIES, OTEL_EXPORTER_OTLP_RETRY_INITIAL_DELAY_MS, OTEL_EXPORTER_OTLP_RETRY_MAX_DELAY_MS.
  • Span attribute value length limit (OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT), per-event and per-link attribute count limits (OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT, OTEL_LINK_ATTRIBUTE_COUNT_LIMIT); excess attributes counted in dropped_attributes_count and emitted as droppedAttributesCount in OTLP.
  • Tracestate caps at 32 entries / 256 bytes; baggage caps at 180 entries / 8192 bytes per W3C trace-context.
  • instrument_attributes:apply_limits/2,3 and truncate_value/2 helpers.
  • Span Export Path section in the design and internals guide explaining the full chain from end_span to OTLP, with explicit notes that instrument_tracer_nif serves the flight recorder only.
  • Test coverage for 28 documented public APIs that previously had no call sites in CT (instrument_propagation:inject_headers/extract_headers/call_with_context/cast_with_context, instrument_context:remove_value/spawn_link_with_context, instrument_config:set_verbose_tracing/is_verbose_tracing/enable_exporter/disable_exporter, instrument_tracer:record_exception/update_name, instrument_test:assert_log_trace_context, instrument_logger:add_trace_context/emit, instrument_metric:remove_label/clear_labels/set_gauge_to_current_time, exporter callback contracts).

Changed

  • Batch processor force_flush/0 and the max-batch-size trigger no longer block the gen_server loop. An export worker is spawned and completion arrives as {export_done, ...}; concurrent flush callers are batched and replied to via gen_server:reply/2. A kill timer enforces export_timeout_millis without blocking the loop.
  • instrument_exporter shutdown now casts the hook unregister so the reply path stays unblocked.
  • instrument_span_processor:on_start/2 now has a 5 s safety timeout; the tracer hot path uses the inline persistent_term form.
  • OTLP exporters return {error, retryable, _} vs {error, permanent, _}. The batch processor keeps retryable batches for up to max_batch_retries cycles and drops permanent errors.
  • Probability sampler hashes the upper 8 bytes of the trace id, matching the Java/Go/Python reference SDKs.
  • Status transitions now follow the OTel spec: unset -> ok|error, error -> ok (success overrides), error -> error updates the description, ok is final.
  • Batch processor clamps max_export_batch_size to max_queue_size on init with a warning.
  • Documentation snippets fixed across guides/, book/, and README.md: 6 syntax bugs, 8+ calls to non-existent or wrong-arity functions, wrong arg shapes for set_sampler, parent_based config, metric_view record literal, exporter_otlp:export, and stale config keys (schedule_delay_millis, export_timeout_millis).
  • Book chapter prose smoothed for readability.

Fixed

Removed

  • instrument_exporter_kafka documentation section: the module never existed in src/exporters/.

Deprecated

  • None.

[0.6.1] - 2026-04-16

Fixed

  • Moved hex package files list from rebar.config to instrument.app.src so do_build.sh, do_cmake.sh, and c_src/ build assets are actually shipped in the published tarball (the rebar.config {hex, [{files, ...}]} entry was silently ignored for non-standard files)
  • ex_doc XML parse errors caused by <<...>> literals and comparison operators in doc comments

[0.6.0] - 2026-04-16

Changed

  • Renamed instrument module to instrument_metric to avoid conflict with Erlang's runtime_tools instrument module
  • Bumped application version in instrument.app.src to 0.6.0

[0.5.0] - 2026-04-08

Added

  • OTel spec compliance features: span limits, dropped counts tracking, exemplar support
  • B3 ParentSpanId injection for nested spans
  • Aggregation temporality support (cumulative/delta)
  • Observable instrument 1-arity callbacks with attributes
  • Tests for OTel spec compliance (30 new test cases)
  • Throughput optimizations for exporter and processor lookup
  • Updated benchmarks documentation

Fixed

  • Spawned-child trace leak with session-based cleanup
  • OpenTelemetry spec compliance issues in OTLP export
  • Preserved tracer scope in OTLP span export

[0.4.0] - 2026-04-07

Added

  • Tail-based sampling span processor
  • Generic client tracing utilities and attribute-based sampling
  • Flight recorder using erl_tracer NIF for low-overhead message tracing
  • Global tracing enable flag for performance optimization
  • Custom span_id support to tracer API
  • instrument_test module for validating instrumentation
  • startTimeUnixNano to OTLP metrics export
  • Debug logging to broad exception handlers
  • Error logging to span processor callbacks
  • Benchmarks for OpenTelemetry APIs and client tracing strategies
  • Design and internals documentation
  • Book chapters and reference guides
  • Elixir users guide
  • Runnable cross-process tracing and logging examples
  • Tests for metric names and attributes in exporter
  • Tests for tracing disabled and custom span_id
  • Regression tests for 4 bug fixes (record_only sampling, metric description/unit, histogram view boundaries, OTLP scope config)

Fixed

  • Critical tracing and OTLP spec compliance issues
  • Histogram and OTLP spec compliance issues
  • Empty bucket validation crash in histogram
  • Tuple metric name handling for OTEL metrics
  • Race condition in tracer exporter list
  • Race condition in metric index updates
  • Vec metric cleanup and concurrent attribute race condition
  • mark/1,2 not working in spawned child processes
  • erl_tracer issues: teardown, idempotency, async parent spans
  • Multiple bugs in client and tail sampler
  • 5 bugs in span processors, metrics, and context propagation
  • 5 client tracing issues
  • Test failures in metrics exporter and span processor
  • E2E test skip behavior and timing issues

Changed

  • Replaced seq_trace with erl_tracer NIF for flight recorder performance
  • Improved flight recorder eviction performance
  • Improved config auto-registration and processor shutdown handling
  • Improved edge case handling in tail sampler
  • Renamed exporter callbacks to avoid gen_server conflicts
  • Added xref checks
  • Documented processor callback restrictions
  • Filter internal tracer bootstrap messages in trace_receive

[0.3.0] - 2026-04-01

Added

  • OpenTelemetry-compatible API with native implementation
  • Context propagation via instrument_context module
  • W3C TraceContext format support in instrument_propagation
  • W3C Baggage propagation via instrument_baggage module
  • B3 single-header propagator (instrument_propagator_b3) for Zipkin compatibility
  • B3 multi-header propagator (instrument_propagator_b3_multi) for X-B3-* headers
  • Support for b3 and b3multi in OTEL_PROPAGATORS environment variable
  • Native span implementation via instrument_tracer with full lifecycle management
  • OTel-compatible MeterProvider/Meter API via instrument_meter
  • Attribute handling via instrument_attributes
  • Erlang logger integration via instrument_logger with automatic trace correlation
  • Trace/Span ID generation per W3C spec via instrument_id
  • Span exporter system via instrument_exporter with batch processing
  • Console exporter (instrument_exporter_console) with text and JSON formats
  • OTLP HTTP exporter (instrument_exporter_otlp) for OpenTelemetry collectors
  • Cross-process context propagation helpers
  • New test suites for context, tracer, meter, and exporter modules
  • New instrument_otel.hrl header with OTel record definitions
  • Documentation guides: getting started, instrumentation, context propagation, exporters
  • E2E tests with Docker (Prometheus + Jaeger)
  • Stress tests and race condition tests
  • OpenTelemetry compatibility info to README
  • Sampling and processing guide, external collectors documentation

Fixed

  • Context/memory leaks with instrument cleanup

Changed

  • Extended metric record with OTel fields (description, unit, meter, attributes)
  • Updated application description to mention OpenTelemetry support
  • Added hackney 3.2.1 as dependency for OTLP HTTP export
  • Documentation updates for B3 propagation and OTel clarity

[0.2.0] - 2026-03-31

Added

  • Vec API for labeled metrics (prometheus-cpp style): new_counter_vec/3, new_gauge_vec/3, new_histogram_vec/3
  • Direct vec operations: inc_counter_vec/2,3, get_counter_vec/2, inc_gauge_vec/2,3, dec_gauge_vec/2,3, set_gauge_vec/3, get_gauge_vec/2, observe_histogram_vec/3, get_histogram_vec/2
  • labels/2 function to get labeled metric instances
  • Prometheus text format export via instrument_prometheus:format/0
  • GitHub Actions CI for OTP 26/27 on Linux and macOS
  • ex_doc documentation support
  • Type specs for prometheus, vector, and registry modules

Changed

  • Modernized NIF code from C++ to C11 with CMake build system
  • Updated README with examples and API documentation
  • Updated copyright to 2017-2026

[0.1.0] - 2017-04-28

Added

  • Initial release
  • Counter metrics with new_counter/2, inc_counter/1,2, get_counter/1
  • Gauge metrics with new_gauge/2, inc_gauge/1,2, dec_gauge/1,2, set_gauge/2, get_gauge/1
  • Histogram metrics with new_histogram/2,3, observe_histogram/2, get_histogram/1
  • Vector support for labeled metrics
  • NIF-based implementation for high performance