Skip to main content

Metrics, logs, and APM traces: what the agent does for each

When AtherOps detects a running service on your host, you will see a guidance card in the UI. This page explains what the agent actually does for each signal type, so you are not surprised by what enabling something does (or doesn't) do.

Metrics and logs: zero app change required​

For infrastructure integrations (PostgreSQL, Nginx, Redis, Docker, and others), the agent scrapes or tails data from the service directly. Your application code is not involved.

  • Metrics -- the agent sends a native receiver (for example, postgresqlreceiver) to poll the service's stats endpoint. You enable it in config.yaml and the agent handles the rest.
  • Logs -- the agent tails the service's log files with a filelog receiver and parses them. Again, no app change.

In both cases, once you enable the integration and restart the agent, data flows. The app is a black box from the agent's perspective.

APM traces: the app must send them​

Traces are different. A distributed trace is a connected set of spans that your application generates and emits. The agent cannot produce spans by inspecting a running process -- there is no equivalent to "tailing a log file" for trace data.

What the agent does: it runs an OTLP receiver that listens for spans your app sends over the standard OpenTelemetry Protocol. The agent then signs and forwards those spans to AtherOps.

What the agent does not do: it cannot inject tracing into a running JVM, Python process, or Go binary without your involvement.

What detecting a Java (or Node, Python, Go) process means​

When the agent detects a running Java, Node.js, Python, or Go process, it shows you a guidance card. That card is a prompt, not an automatic action. Detection confirms the runtime is present; it does not mean traces are flowing.

To get traces, you need to:

  1. Add OpenTelemetry instrumentation to the app (SDK or auto-instrumentation -- the per-language pages below walk through this).
  2. Point the exporter at the agent's OTLP port (localhost:4317 for gRPC, localhost:4318 for HTTP).
  3. Confirm collection.traces.enabled: true in /etc/atherops/config.yaml (the default).

After that, spans the app emits arrive at the agent and are forwarded to AtherOps.

Per-language instrumentation guides​

  • Java -- attach the OTel Java agent at JVM startup
  • Node.js -- load the OTel Node.js SDK at process startup
  • Python -- wrap with opentelemetry-instrument
  • Go -- import the OTel Go SDK and initialize a tracer

The OTLP endpoint the agent exposes​

The collector inside the agent listens on:

ProtocolAddressDefault port
gRPC0.0.0.0:43174317
HTTP/protobuf0.0.0.0:43184318

These are the standard OpenTelemetry Collector defaults. The standard environment variables work:

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

# HTTP/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

You do not pass an AtherOps API key from the app. The agent's auth-proxy handles signing before data leaves the host. See How the agent works for the full picture.

See also​