Skip to content

Commit bbaabb0

Browse files
docs: add observability usage examples to README
Add comprehensive observability section: - Distributed tracing with OpenTelemetry quick start - Metrics collection with Prometheus - Structured logging example - Link to detailed observability.md guide Features section updated: - Add "Full Observability" bullet point (v0.7.1+) Addresses user request for usage documentation.
1 parent 31d9c64 commit bbaabb0

1 file changed

Lines changed: 72 additions & 0 deletions

File tree

README.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ For detailed threat model, security architecture, and best practices, see [SECUR
158158
- **Minimal Overhead** - 45μs p50 latency, 200,000+ req/s with 8 workers
159159
- **Production Ready** - Health checks, graceful shutdown, automatic restarts
160160
- **Easy Deployment** - Single binary + Python scripts, no service mesh needed
161+
- **Full Observability** - OpenTelemetry tracing, Prometheus metrics, structured logging (v0.7.1+)
161162

162163
## 🚀 Quick Start (5 minutes)
163164

@@ -264,6 +265,77 @@ make demo
264265

265266
This starts a Python worker from examples/basic/worker.py and calls it from Go. The example adjusts PYTHONPATH to import the local worker/python/pyproc_worker package.
266267

268+
## 📊 Observability (v0.7.1+)
269+
270+
pyproc includes built-in support for distributed tracing, metrics, and structured logging.
271+
272+
### Distributed Tracing with OpenTelemetry
273+
274+
```go
275+
import (
276+
"context"
277+
"github.com/YuminosukeSato/pyproc/pkg/pyproc"
278+
"github.com/YuminosukeSato/pyproc/pkg/pyproc/telemetry"
279+
)
280+
281+
func main() {
282+
// Initialize telemetry provider
283+
provider, shutdown := telemetry.NewProvider(telemetry.Config{
284+
ServiceName: "my-service",
285+
Enabled: true,
286+
SamplingRate: 0.01, // 1% sampling
287+
ExporterType: "stdout", // or "otlp" for production
288+
})
289+
defer shutdown(context.Background())
290+
291+
// Create pool
292+
pool, _ := pyproc.NewPool(poolOpts, logger)
293+
294+
// Attach tracer (opt-in)
295+
pool.WithTracer(provider.Tracer("my-service"))
296+
297+
// All calls are now traced automatically
298+
ctx := context.Background()
299+
result, _ := pyproc.CallTyped[Req, Resp](ctx, pool, "predict", request)
300+
}
301+
```
302+
303+
**Key features:**
304+
- ✅ Automatic span creation for all `Pool.Call()` invocations
305+
- ✅ W3C Trace Context propagation over Unix Domain Sockets
306+
- ✅ <1% overhead with 1% sampling (production target)
307+
- ✅ Zero overhead when disabled (no-op mode)
308+
- ✅ Fully backward compatible (opt-in via `WithTracer()`)
309+
310+
### Metrics
311+
312+
Built-in Prometheus metrics:
313+
314+
```go
315+
// Expose metrics endpoint
316+
http.Handle("/metrics", promhttp.Handler())
317+
318+
// Metrics automatically collected:
319+
// - pyproc_pool_calls_total
320+
// - pyproc_pool_call_duration_seconds
321+
// - pyproc_pool_errors_total
322+
// - pyproc_worker_active_connections
323+
```
324+
325+
### Structured Logging
326+
327+
```go
328+
import "log/slog"
329+
330+
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
331+
Level: slog.LevelInfo,
332+
}))
333+
334+
pool, _ := pyproc.NewPool(poolOpts, logger)
335+
```
336+
337+
For comprehensive observability documentation, see [docs/observability.md](docs/observability.md).
338+
267339
## 📚 Detailed Usage Guide
268340

269341
### Installation

0 commit comments

Comments
 (0)