I Built an OpenTelemetry Logs Bridge. Encoding Was the Easy Part

Building an OpenTelemetry Logs Bridge: Ensuring Accuracy and Falsifiability

Creating an OpenTelemetry Logs bridge proved challenging beyond the simple encoding tasks. Key contracts between APIs needed preservation, affecting the bridge's functionality and reliability. These contracts include context usage, ownership of pooled entries, masking precedence, and provider lifecycle management.

A measurement boundary was established, focusing solely on Adapter.Write calls on a pre-built LogEntry and ending at an OpenTelemetry API Logger with a no-op Emit method. The measurements excluded HaloLog's public logger and builder path, masking, console/file fan-out, and other external components. This approach aimed to isolate the adapter's performance and fidelity as microbenchmarks, not production throughput or comparisons with other bridges.

Initially, HaloLog provided a Bind helper for attaching trace identifiers to log records, enabling correlation fields in JSON output. However, this did not route logs through the OpenTelemetry Logs pipeline. Daniel Loader later contributed an output adapter that converted HaloLog LogEntries into OpenTelemetry LogRecords, preserving crucial data such as timestamp, severity, body, structured fields, context, and optional trace context.

The bridge's architecture and tests were refined through maintainers' review, ensuring proper mapping of HaloLog LogEntries to OpenTelemetry LogRecords, including timestamp, severity, body, structured fields, and context. This mapping maintained the integrity of the correlation information. The bridge's design allows integration with existing console or file adapters, enabling seamless fan-out of log records to multiple destinations without compromising atomicity or consistency.

Key contracts were established to ensure accurate log emission and masking. The first contract required the bridge to utilize the same correlation context for both Enabled and Emit methods, preventing discrepancies caused by context probing or reconstruction. The second contract emphasized that masking must remain authoritative at the export boundary, preventing any representation from observing original values during transformation.

By adhering to these contracts and conducting thorough measurements, the OpenTelemetry Logs bridge provides a reliable and reproducible pathway for sending log records to the OpenTelemetry pipeline, ensuring accurate and falsifiable telemetry claims.