OpenTelemetry Zig

Zig docs   •   Installation   •   Features   •   Examples   •   Contributing   •   Community

Caution

This project is in alpha stage. While it is ready for usage and testing, it has not been battle-tested in production environments. Use with caution and expect breaking changes between releases.

This is an implementation of the OpenTelemetry specification for the Zig programming language.

The version of the OpenTelemetry specification targeted here is 1.48.0.

Goals

1. Provide a Zig library implementing the stable features of an OpenTelemetry SDK
2. Provide a reference implementation of the OpenTelemetry API
3. Provide examples on how to use the library in real-world use cases

Installation

Run the following command to add the package to your build.zig.zon dependencies, replacing <ref> with a release version:

zig fetch --save "git+https://github.com/zig-o11y/opentelemetry-sdk#<ref>"

Then in your build.zig:

const sdk = b.dependency("opentelemetry-sdk", .{
    .target = target,
    .optimize = optimize,
});

Features

std.log Bridge for Seamless Migration

The SDK includes a bridge that allows you to route Zig's standard std.log calls to OpenTelemetry without refactoring your entire codebase. This is perfect for gradual adoption of observability.

Quick Start:

const std = @import("std");
const sdk = @import("opentelemetry-sdk");

// Override std.log to use OpenTelemetry
pub const std_options: std.Options = .{
    .logFn = sdk.logs.std_log_bridge.logFn,
};

pub fn main() !void {
    var provider = try sdk.logs.LoggerProvider.init(allocator, null);
    defer provider.deinit();

    // Configure the bridge
    try sdk.logs.std_log_bridge.configure(.{
        .provider = provider,
        .also_log_to_stderr = true, // Dual mode: OTel + stderr
    });
    defer sdk.logs.std_log_bridge.shutdown();

    // Now std.log calls automatically go to OpenTelemetry!
    std.log.info("Application started", .{});
}

Key Features:

• Dual-mode logging: Send logs to both OpenTelemetry and stderr during migration
• Thread-safe: Safe for concurrent use across multiple threads
• Scope strategies: Single scope for all logs, or separate scopes per Zig module
• Automatic severity mapping: Zig log levels map to OpenTelemetry severity numbers
• Source location tracking: Optional file/line information as attributes

See examples/logs/std_log_basic.zig and examples/logs/std_log_migration.zig for complete examples.

Specification Support State

Signals

Signal	Status
Traces	✅
Metrics	✅
Logs	✅
Profiles	❌

OTLP Protocol

Feature	Status
HTTP/Protobuf	✅
HTTP/JSON	✅
gRPC	❌
Compression (gzip)	✅

Examples

Check out the examples folder for practical usage examples of traces, metrics, and logs.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to contribute to this project, including:

• Running tests locally
• Running benchmarks
• Test and benchmark options

Origins

This project originated from a proposal in the OpenTelemetry community to create a native Zig implementation of the OpenTelemetry SDK.

You can read more about the original proposal and discussion at:

open-telemetry/community#2514

For a more in-depth read of why OpenTelemetry needs a Zig SDK, see "Zig is great for Observability".

Join the community

You can find the Zig OTel SDK developers in the Zig-o11y Discord server.