Observability
anthrogo ships opt-in OTel tracing and Prometheus metrics. Both are
zero-overhead when their respective env vars are unset — no SDK initialisation,
no port binding, no goroutines.
Quick start
# Export traces to a local Jaeger/Tempo collector
export ANTHROGO_OTEL_ENDPOINT=localhost:4317
# Expose Prometheus /metrics on port 9100
export ANTHROGO_METRICS_ADDR=:9100
anthrogo serve --addr 127.0.0.1:8765
Then scrape metrics:
curl -sf http://localhost:9100/metrics | grep anthrogo_
OTel tracing
Environment variable
| Variable |
Example |
Description |
ANTHROGO_OTEL_ENDPOINT |
localhost:4317 |
OTLP/gRPC endpoint. When unset OTel is disabled. |
The connection is made insecure (no TLS) by default. To use a TLS-enabled
collector, point at it with the standard OTEL_EXPORTER_OTLP_CERTIFICATE
variable from the OTel spec alongside ANTHROGO_OTEL_ENDPOINT.
Service resource
| Attribute |
Value |
service.name |
anthrogo |
service.version |
binary version (e.g. 0.14.2-dev) |
Spans produced
| Span name |
Package |
Notes |
serve.HTTP <METHOD> <PATH> |
internal/serve |
One per HTTP request, wraps the full handler. |
engine.turn |
pkg/query |
One per runOneAPITurnAttempt call. |
provider.Stream <model> |
pkg/query |
Child of engine.turn; covers the Provider.Stream call. |
tool.<name> |
pkg/query |
One per tool execution; child of engine.turn. |
hook.<event> |
internal/hooks |
One per RunHook subprocess; event = PreToolUse, PostToolUse, etc. |
Pointing at Jaeger
# docker-compose snippet
services:
jaeger:
image: jaegertracing/all-in-one:latest
ports:
- "16686:16686" # UI
- "4317:4317" # OTLP gRPC
ANTHROGO_OTEL_ENDPOINT=localhost:4317 anthrogo -p "hello"
# open http://localhost:16686 → search "anthrogo"
Pointing at Grafana Tempo
# tempo.yaml (minimal)
server:
http_listen_port: 3200
distributor:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
ANTHROGO_OTEL_ENDPOINT=localhost:4317 anthrogo serve --addr 127.0.0.1:8765
Prometheus metrics
Environment variable
| Variable |
Example |
Description |
ANTHROGO_METRICS_ADDR |
:9100 |
TCP address for the /metrics endpoint. When unset no server starts. |
Metric reference
| Metric |
Type |
Labels |
Description |
anthrogo_serve_in_flight_chats |
Gauge |
— |
Number of /v1/chat requests currently in flight. |
anthrogo_engine_turns_total |
Counter |
stop_reason |
Total engine turns by stop reason (end_turn, tool_use, max_tokens, …). |
anthrogo_tool_calls_total |
Counter |
tool, is_error |
Total tool calls by tool name and error flag. |
anthrogo_tool_duration_seconds |
Histogram |
tool |
Tool call duration (default Prometheus buckets). |
anthrogo_provider_stream_errors_total |
Counter |
provider, transient |
Provider stream errors by provider type and transient flag. |
anthrogo_tokens_in_total |
Counter |
— |
Cumulative input tokens consumed. |
anthrogo_tokens_out_total |
Counter |
— |
Cumulative output tokens emitted. |
anthrogo_hook_duration_seconds |
Histogram |
event |
Hook subprocess duration by event name. |
Sample Prometheus scrape config
scrape_configs:
- job_name: anthrogo
static_configs:
- targets: ["localhost:9100"]
scrape_interval: 15s
Verify with curl
# Start serve with metrics enabled
ANTHROGO_METRICS_ADDR=:9100 anthrogo serve --addr 127.0.0.1:8765 &
# Wait for startup, then scrape
curl -sf http://localhost:9100/metrics | grep anthrogo_
# Example output:
# anthrogo_serve_in_flight_chats 0
# anthrogo_engine_turns_total{stop_reason="end_turn"} 3
# anthrogo_tokens_in_total 1240
# anthrogo_tokens_out_total 580