Skip to main content

Enable traces from your apps

The agent runs an OTLP receiver so your applications can send spans to the local host. The agent forwards them to AtherOps. Traces are on by default in the shipped config.

Spans are collected and stored, but this release does not include an in-product trace query view. See scope.

Step 1: Confirm the receiver is enabled​

In /etc/atherops/config.yaml:

collection:
  traces:
    enabled: true                   # default

enabled: true is the default. If you change it, save the file and the agent restarts the collector automatically.

The collector listens on:

  • gRPC: 0.0.0.0:4317
  • HTTP: 0.0.0.0:4318

To change those ports, set collection.traces.grpc_port / collection.traces.http_port in the collection.traces section, or use ports.otlp_grpc / ports.otlp_http. The more specific collection.traces.*_port fields take precedence when both are set. See Reference: config.yaml.

Step 2: Point your application at the agent​

Configure your app's OpenTelemetry SDK or exporter to send OTLP to the agent on the same host. Standard OTLP environment variables work:

# gRPC (port 4317)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# or HTTP/protobuf (port 4318)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

The agent accepts standard OTLP. Any OpenTelemetry SDK or a downstream collector can be the sender. You do not send your AtherOps key from the app; the agent signs the data for you before it leaves the host (see Architecture).

Step 3: Confirm the collector is healthy and receiving​

Verification has two parts: confirm the receiver is up and forwarding (locally, on the host), then confirm AtherOps actually stored your spans (positively, via the query API).

3a. Confirm the receiver and forwarder are up​

Tail the agent logs:

journalctl -u atherops-otel-agent -f

At startup a working agent logs these lines (the trace receiver runs inside the collector; the proxy is the loopback that signs and forwards spans to AtherOps):

level=info msg="collector started" collector_version=0.102.0 pid=3821
level=info msg="proxy listening" addr=127.0.0.1:9599

The agent does not log a line per span, and the bundled OpenTelemetry Collector is not configured to log received spans, so a quiet log while traffic flows is normal, not a failure. If the collector were failing you would instead see crash/restart lines (see Troubleshooting). A forwarding error to AtherOps is logged as level=error msg="forward traces failed"; if you do not see that line, spans are leaving the host.

:::note LOG_LEVEL=debug does not add per-span logging LOG_LEVEL=debug (or --log-level=debug) raises the verbosity of the agent wrapper only; it does not make the collector log each span. Use the query check below for positive confirmation. :::

3b. Confirm AtherOps received your spans (positive check)​

The agent stores spans server-side. You can read them back with the traces query API, scoped to your org by the JWT your platform session already holds.

curl -s \
  -H "Authorization: Bearer $ATHEROPS_JWT" \
  "https://api.atherops.com/query/traces?limit=20"
  • $ATHEROPS_JWT is the bearer token from your AtherOps session. To obtain it from the command line, see Get a query token.
  • A JSON array of span objects (each with TraceID, Service, Operation, DurationMs, and StatusCode) means your spans reached the backend. An empty array [] means none stored yet in the window; generate traffic and retry (the default window is the last hour; widen it with start=/end= in RFC3339).
  • Useful filters: service=<name>, error=true (error spans only), trace_id=<hex> (one trace). See Ingest & query API reference.

A non-empty result is your positive confirmation that traces are flowing end to end. Remember there is no in-product trace explorer UI in this release (per the note above). The query API is how you confirm and read spans today.

Custom metrics and other OTLP​

The OTLP receiver above is for traces. To send arbitrary OTLP (your own metrics/logs) or to use the AtherOps ingest endpoints directly from another system, see the advanced Ingest API reference.

See also​