otell

Install

curl -fsSL https://otell.dev/install.sh | sh

Start otell

otell run

Send your logs/traces/metrics to otell

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Teach your model how to use otell

Add the following to your AGENTS.md:

# Development Logging and Observability

The development setup is forwarding logs/traces/metrics to a local OpenTelemetry collector called `otell` that is listening on 4317/4318.

To see the logs/traces/metrics, you can use the `otell` binary. Run `otell intro` to learn how to use the binary to search for logs/traces/metrics.

```
otell intro
otell search
otell traces
otell trace
otell span
```

Advanced usage

Tee a copy of your logs/traces/metrics to a human-friendly collector (e.g. Datadog, Dash0, HyperDX, etc.):

export OTELL_FORWARD_OTLP_ENDPOINT=http://remote-collector.example
export OTELL_FORWARD_OTLP_PROTOCOL=http/protobuf
export OTELL_FORWARD_OTLP_COMPRESSION=gzip
export OTELL_FORWARD_OTLP_HEADERS=x-tenant=dev,authorization=Bearer abc123
export OTELL_FORWARD_OTLP_TIMEOUT=10s

Configure otell via environment variables or config file:

#   Linux:   ~/.config/otell/config.toml
#   macOS:   ~/.config/otell/config.toml
#   Windows: %APPDATA%\otell\config.toml

otlp_grpc_addr = "127.0.0.1:4317"
otlp_http_addr = "127.0.0.1:4318"

db_path = "/Users/me/.local/share/otell/otell.duckdb"
uds_path = "/tmp/otell.sock"
query_tcp_addr = "127.0.0.1:1777"
query_http_addr = "127.0.0.1:1778"

retention_ttl = "24h"
retention_max_bytes = 2147483648
write_batch_size = 2048
write_flush_ms = 200

forward_otlp_endpoint = "http://remote-collector.example"
forward_otlp_protocol = "grpc" # or "http/protobuf"
forward_otlp_compression = "none" # or "gzip"
forward_otlp_headers = "x-tenant=dev,authorization=Bearer abc123"
forward_otlp_timeout = "10s"