logfire client for zig
add README
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+155
+155
README.md
+155
README.md
···
1
+
# logfire-zig
2
+
3
+
unofficial Zig SDK for [Pydantic Logfire](https://logfire.pydantic.dev/) - OTLP HTTP/JSON export for traces, logs, and metrics.
4
+
5
+
aiming for parity with [logfire-rust](https://github.com/pydantic/logfire-rust).
6
+
7
+
see also:
8
+
- [Logfire documentation](https://logfire.pydantic.dev/docs/)
9
+
- [alternative clients guide](https://logfire.pydantic.dev/docs/how-to-guides/alternative-clients/) for OTLP protocol details
10
+
11
+
## Using logfire-zig
12
+
13
+
First [set up a Logfire project](https://logfire.pydantic.dev/docs/#logfire). Configure the SDK by [creating a write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/) and setting it as an environment variable (`LOGFIRE_WRITE_TOKEN` or `LOGFIRE_TOKEN`).
14
+
15
+
Add to your `build.zig.zon`:
16
+
17
+
```zig
18
+
.dependencies = .{
19
+
.logfire = .{
20
+
.url = "https://tangled.sh/zzstoatzz.io/logfire-zig/archive/main",
21
+
.hash = "...", // zig build will tell you the hash
22
+
},
23
+
},
24
+
```
25
+
26
+
Add to your `build.zig`:
27
+
28
+
```zig
29
+
const logfire = b.dependency("logfire", .{
30
+
.target = target,
31
+
.optimize = optimize,
32
+
});
33
+
exe.root_module.addImport("logfire", logfire.module("logfire"));
34
+
```
35
+
36
+
Then instrument your code:
37
+
38
+
```zig
39
+
const std = @import("std");
40
+
const logfire = @import("logfire");
41
+
42
+
pub fn main() !void {
43
+
const lf = try logfire.configure(.{
44
+
.service_name = "my-service",
45
+
});
46
+
defer lf.shutdown();
47
+
48
+
// structured logging
49
+
logfire.info("application started", .{});
50
+
51
+
// spans for timing operations
52
+
{
53
+
const span = logfire.span("process.files", .{});
54
+
defer span.end();
55
+
56
+
// work happens here
57
+
std.time.sleep(10 * std.time.ns_per_ms);
58
+
}
59
+
60
+
// metrics
61
+
logfire.counter("files.processed", 42);
62
+
logfire.gaugeInt("queue.depth", 10);
63
+
64
+
// flush before exit
65
+
try lf.flush();
66
+
}
67
+
```
68
+
69
+
Run with your token:
70
+
71
+
```bash
72
+
LOGFIRE_WRITE_TOKEN=pylf_v1_us_xxx zig build run
73
+
```
74
+
75
+
Without a token, output goes to console for local development.
76
+
77
+
## Features
78
+
79
+
- **Spans** - timing and tracing with attributes
80
+
- **Logging** - trace, debug, info, warn, err with structured data
81
+
- **Metrics** - counters, gauges (int/double)
82
+
- **OTLP Export** - HTTP/JSON to logfire or any OTLP-compatible backend
83
+
- **Zero Config** - reads token and endpoint from environment
84
+
85
+
## API
86
+
87
+
```zig
88
+
// configuration
89
+
const lf = try logfire.configure(.{
90
+
.service_name = "my-service",
91
+
.service_version = "1.0.0",
92
+
.environment = "production",
93
+
});
94
+
defer lf.shutdown();
95
+
96
+
// spans
97
+
const span = logfire.span("operation.name", .{
98
+
.user_id = @as(i64, 123),
99
+
.request_path = "/api/search",
100
+
});
101
+
defer span.end();
102
+
103
+
// logging
104
+
logfire.trace("detailed trace", .{});
105
+
logfire.debug("debug info", .{});
106
+
logfire.info("something happened", .{});
107
+
logfire.warn("warning message", .{});
108
+
logfire.err("error occurred", .{});
109
+
110
+
// metrics
111
+
logfire.counter("requests.total", 1);
112
+
logfire.gaugeInt("connections.active", 42);
113
+
logfire.gaugeDouble("cpu.usage", 0.75);
114
+
115
+
// manual flush
116
+
try lf.flush();
117
+
```
118
+
119
+
## Environment Variables
120
+
121
+
| Variable | Description |
122
+
|----------|-------------|
123
+
| `LOGFIRE_WRITE_TOKEN` | Write token (preferred) |
124
+
| `LOGFIRE_TOKEN` | Write token (fallback) |
125
+
| `LOGFIRE_SERVICE_NAME` | Service name override |
126
+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Custom OTLP endpoint |
127
+
128
+
## Requirements
129
+
130
+
- Zig 0.15+
131
+
132
+
## Development
133
+
134
+
```bash
135
+
zig build test # run tests
136
+
zig build example # run examples/basic.zig
137
+
```
138
+
139
+
## Status
140
+
141
+
This is an unofficial community SDK aiming for parity with [logfire-rust](https://github.com/pydantic/logfire-rust). Current status:
142
+
143
+
- [x] Spans with attributes
144
+
- [x] Structured logging (trace/debug/info/warn/err)
145
+
- [x] Metrics (counter, gauge)
146
+
- [x] OTLP HTTP/JSON export
147
+
- [x] Environment-based configuration
148
+
- [ ] Histograms export (instruments implemented, export WIP)
149
+
- [ ] Protobuf encoding
150
+
- [ ] Trace context propagation
151
+
- [ ] Batched async export
152
+
153
+
## License
154
+
155
+
MIT