Skip to main content
There is no aiAxonIQ agent to install. aiAxonIQ speaks standard OTLP, so what you install is the upstream OpenTelemetry Collector, or an OpenTelemetry SDK inside your application, with an endpoint and a header set. That is a deliberate property rather than a gap: nothing here is proprietary, and if you later point the same exporter at a second backend, none of this changes.

​
Collector or direct?

Both work, and most production setups end up using both. The decision is about where you want the endpoint, the key and the retry behaviour to live.

A collector — recommended

Your applications export to a collector on the same host or node; the collector forwards to aiAxonIQ.Choose this for anything running on real infrastructure.

Direct from the SDK

Each application exports straight to aiAxonIQ.Choose this for a laptop, a single container, or a first experiment.
Three reasons the collector is worth the extra component:
  • The license key lives in one place. With direct export, every workload carries an ingest credential in its environment. With a collector, one does.
  • It collects what your application cannot see. Host CPU, memory, disk, network, container and Kubernetes metrics come from the collector. An instrumented application knows nothing about the machine it runs on.
  • Batching and retry are configured once, correctly, instead of per service and per language.
Direct SDK export is not wrong, and it is the fastest way to see a trace. The cost is that the endpoint and key are then set in every service’s environment, which becomes the thing you have to change when either one changes.

​
Choose your platform

Docker

One collector container beside your application containers. The shortest real install.

Docker Compose

A collector service in your existing stack, reachable by name from every other service.

Linux VM

A native package under systemd, collecting host metrics and journald logs.

Kubernetes

A DaemonSet for node telemetry plus a single Deployment for cluster telemetry.
Not on any of these? Instrument your application covers exporting directly from your language’s SDK, and Send data with OpenTelemetry documents the raw endpoints if you want to build the request yourself.

​
What every install needs

Before you start, you need two values.
  1. Your base endpoint — shown on Get Started in the dashboard. These pages write it as $OIQ_ENDPOINT.
  2. A license key — created in Settings → License Keys, starting oiq_. Requires the Admin role. See Create a license key. These pages write it as $OIQ_LICENSE_KEY.
Export both before running anything below:
Both forms carry the /otlp prefix because nginx serves OTLP under it and strips it before forwarding, so the receiver still sees /v1/logs. Dropping the prefix is the most common setup mistake: the request reaches the dashboard instead of the receiver and comes back as an HTML 404 rather than an ingest error.

​
What arrives, and from where

Knowing which component produces which signal saves the most common disappointment — an empty Infrastructure or Kubernetes page while application telemetry flows perfectly.
Instrumenting your applications alone will never populate the Infrastructure or Kubernetes pages. Those are descriptions of the machine and the cluster, and only a collector running there can see them.

​
Verify any install

Whatever you install, the same two checks confirm it end to end. The collector publishes its own metrics on port 8888. Three counters separate the two things that can be wrong:
Accepted rising while sent stays flat is the classic signature of a wrong endpoint or a missing key in the exporter block. It is worth checking before anything else, because from inside your application everything looks fine. Then confirm the data landed: open Logs, set the range to the last 15 minutes, and search for a service you expect. Full detail in Verify your data arrived.

​
Troubleshooting

Read the error field on that line — it names the cause exactly.
  • no such host — the endpoint hostname does not resolve. Check $OIQ_ENDPOINT against the value on Get Started.
  • connection refused — the host resolves but nothing is listening on that port.
  • 401 Unauthorized — the key is missing, malformed or revoked.
  • 404 — the endpoint already ends in /v1/…. It must be the base URL; the collector appends the signal path itself.
The collector retries with backoff and does not drop data while it retries, so a transient failure here is not a loss.
The collector is running and receiving nothing. That is an application-side problem, not a collector one — your services are not exporting to it.Check that your application’s OTEL_EXPORTER_OTLP_ENDPOINT points at the collector’s OTLP port (4318 for HTTP, 4317 for gRPC), not at aiAxonIQ.
Two causes that are not about the key’s value:
  • A trailing newline. A key read from a file created by a shell heredoc, or a Kubernetes Secret made with --from-file, carries the newline as part of the value. Use --from-literal, or printf rather than echo.
  • A validation outage. If the receiver cannot reach the service that validates keys it fails closed and returns the same 401. A sudden 401 across every service at once, with a key you have not changed, is far more likely to be this. Check $OIQ_ENDPOINT/health first.
The collector reads its configuration only at startup. Restart it after any edit, and confirm the file you edited is the one mounted into the process — a bind mount pointing at a path that does not exist silently yields the image’s default config rather than an error.

​
Next

Quickstart first

Prove the path with curl before installing anything.

Endpoints and errors

Every path, status code and limit.

Troubleshooting

Stage-by-stage diagnosis.