Quickstart

This walks through the full loop: start the server, send it some telemetry, and query it from the CLI. It assumes you've already installed the tael binary.

1. Start the server

tael serve

Leave this running. It now accepts OTLP gRPC on 127.0.0.1:4317 and serves the REST API the CLI talks to on 127.0.0.1:7701.

2. Point an app at it

Tael speaks standard OTLP, so any OpenTelemetry-instrumented app works. Set the two standard environment variables before launching your app:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_SERVICE_NAME=my-agent

A minimal Python example using the OTel SDK:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("handle.request") as span:
    span.set_attribute("user.id", "u_123")
    span.set_attribute("result.count", 7)
    # ...do work...

Run it. Spans arrive within the exporter's batch window (a few seconds by default).

Tael ingests traces, logs, and metrics over the same OTLP endpoint, plus Prometheus remote-write at POST /api/v1/write. You don't need separate pipelines for each signal.

3. See which services are reporting

tael services --format table

Each service comes back with span_count, trace_count, avg_duration_ms, and error_rate — a quick way to spot which service is unhealthy.

4. Find interesting traces

# Everything that errored in the last hour
tael query traces --status error --last 1h

# Slow operations on a specific service
tael query traces --service my-agent --min-duration 500ms --last 1h --format table

# Match on a span attribute (repeatable, ANDed)
tael query traces --attribute http.method=GET --attribute http.status_code=500

tael query traces prints JSON by default. Add --format table when you want to read it yourself.

5. Pull a full trace

Grab a trace_id from the results above, then fetch every span in that trace, ordered by start time:

tael get trace <trace-id> --format table

Pipe the JSON through jq to drill in:

tael get trace <trace-id> | jq '.spans[] | select(.status=="error")'

6. Get a health summary

When you don't know where to start, ask for the aggregate picture:

tael summarize --last 15m --format table

You get back the trace count, top services, top error operations, and log/metric volume for the window — enough to decide what to dig into next.

7. Watch it live

For an interactive feed, service health, and a trace waterfall visualizer:

tael live

See The Live TUI for the keyboard controls.

Where to go next

Wide Events — attach everything to one span and these queries become powerful.
Debugging with an Agent — the recommended order of operations for an investigation.
CLI Reference — the complete command surface.