logfire-zig#

unofficial Zig SDK for Pydantic Logfire - OTLP HTTP/JSON export for traces, logs, and metrics.

aiming for parity with logfire-rust.

see also:

• Logfire documentation
• alternative clients guide for OTLP protocol details

Using logfire-zig#

First set up a Logfire project. Configure the SDK by creating a write token and setting it as an environment variable (LOGFIRE_WRITE_TOKEN or LOGFIRE_TOKEN).

Add to your build.zig.zon:

.dependencies = .{
    .logfire = .{
        .url = "https://tangled.sh/zzstoatzz.io/logfire-zig/archive/main",
        .hash = "...", // zig build will tell you the hash
    },
},

Add to your build.zig:

const logfire = b.dependency("logfire", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("logfire", logfire.module("logfire"));

Then instrument your code:

const std = @import("std");
const logfire = @import("logfire");

pub fn main() !void {
    const lf = try logfire.configure(.{
        .service_name = "my-service",
    });
    defer lf.shutdown();

    // structured logging
    logfire.info("application started", .{});

    // spans for timing operations
    {
        const span = logfire.span("process.files", .{});
        defer span.end();

        // work happens here
        std.time.sleep(10 * std.time.ns_per_ms);
    }

    // metrics
    logfire.counter("files.processed", 42);
    logfire.gaugeInt("queue.depth", 10);

    // flush before exit
    try lf.flush();
}

Run with your token:

LOGFIRE_WRITE_TOKEN=pylf_v1_us_xxx zig build run

Without a token, output goes to console for local development.

Features#

• Spans - timing and tracing with attributes
• Logging - trace, debug, info, warn, err with structured data
• Metrics - counters, gauges (int/double)
• OTLP Export - HTTP/JSON to logfire or any OTLP-compatible backend
• Zero Config - reads token and endpoint from environment

API#

// configuration
const lf = try logfire.configure(.{
    .service_name = "my-service",
    .service_version = "1.0.0",
    .environment = "production",
});
defer lf.shutdown();

// spans
const span = logfire.span("operation.name", .{
    .user_id = @as(i64, 123),
    .request_path = "/api/search",
});
defer span.end();

// logging
logfire.trace("detailed trace", .{});
logfire.debug("debug info", .{});
logfire.info("something happened", .{});
logfire.warn("warning message", .{});
logfire.err("error occurred", .{});

// metrics
logfire.counter("requests.total", 1);
logfire.gaugeInt("connections.active", 42);
logfire.gaugeDouble("cpu.usage", 0.75);

// manual flush
try lf.flush();

Environment Variables#

Requirements#

• Zig 0.15+

Development#

zig build test       # run tests
zig build example    # run examples/basic.zig

Status#

This is an unofficial community SDK aiming for parity with logfire-rust. Current status:

• Spans with attributes
• Structured logging (trace/debug/info/warn/err)
• Metrics (counter, gauge)
• OTLP HTTP/JSON export
• Environment-based configuration
• Histograms export (instruments implemented, export WIP)
• Protobuf encoding
• Trace context propagation
• Batched async export

License#

MIT