Send data from Docker

Run an OpenTelemetry Collector container beside your application containers, forward host and application telemetry, and verify it from the collector’s own metrics.

One collector container, one config file. Your application containers export to it over OTLP; it forwards everything to aiAxonIQ with your license key held in a single place.

This is the shortest install that produces real, continuous telemetry rather than a single test record.

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:

export OIQ_ENDPOINT="https://app.aiaxoniq.com/otlp"   # or your own
export OIQ_LICENSE_KEY="oiq_..."

You also need Docker with a running daemon — docker ps should succeed.

Why a collector rather than exporting directly

Your application can export straight to aiAxonIQ, and for one container on a laptop that is fine. On a host running several containers, the collector earns its place for three reasons: the license key stops being duplicated into every container’s environment, host and container metrics become available at all (an instrumented app cannot see the machine it runs on), and batching and retry are configured once instead of per service.

1. Write the config

Save this as config.yaml. It receives OTLP on 4317/4318, scrapes host metrics, and exports to aiAxonIQ.

config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
      memory:
      disk:
      filesystem:
      network:
      load:

processors:
  # Order matters and is not alphabetical. memory_limiter can only shed load it
  # sees before anything has buffered it, so it goes first; batch should group
  # records after every other processor has finished changing them, so it goes
  # last. A pipeline that batches first and limits afterwards will still run out
  # of memory under exactly the load the limiter was added for.
  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 25
  resourcedetection:
    detectors: [env, system]
    system:
      hostname_sources: [os]
  batch:
    timeout: 5s
    send_batch_size: 1000

exporters:
  otlphttp/aiaxoniq:
    endpoint: ${env:OIQ_ENDPOINT}
    headers:
      X-License-Key: ${env:OIQ_LICENSE_KEY}
    compression: gzip

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: 0.0.0.0
                port: 8888
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlphttp/aiaxoniq]
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlphttp/aiaxoniq]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlphttp/aiaxoniq]

2. Run the collector

docker run -d --name aiaxoniq-collector \
  --restart unless-stopped \
  -v "$PWD/config.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  -e OIQ_ENDPOINT="$OIQ_ENDPOINT" \
  -e OIQ_LICENSE_KEY="$OIQ_LICENSE_KEY" \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8888:8888 \
  otel/opentelemetry-collector-contrib:latest

Port	Purpose
4317	OTLP/gRPC in, from your applications
4318	OTLP/HTTP in, from your applications
8888	The collector’s own metrics — how you verify it

Pin a version rather than using latest for anything you intend to keep. The collector’s configuration schema does change between releases, and latest turns that into a surprise on restart.

3. Confirm it started

docker logs aiaxoniq-collector 2>&1 | head -20

Expected output — the line that matters is the last one:

info  service@v0.115.0/service.go:166   Setting up own telemetry...
info  telemetry/metrics.go:70           Serving metrics  {"address": "0.0.0.0:8888"}
info  memorylimiter@v0.115.0/…          Memory limiter configured  {"limit_mib": 12534}
info  service@v0.115.0/service.go:238   Starting otelcol-contrib...  {"Version": "0.115.0"}
info  otlpreceiver@v0.115.0/otlp.go:112 Starting GRPC server  {"endpoint": "0.0.0.0:4317"}
info  otlpreceiver@v0.115.0/otlp.go:169 Starting HTTP server  {"endpoint": "0.0.0.0:4318"}
info  service@v0.115.0/service.go:261   Everything is ready. Begin running and processing data.

Everything is ready. Begin running and processing data. is the success signal.

You will also see two warnings, and both are expected:

'Using the 0.0.0.0 address exposes this server to every network interface'

Correct and intentional here. The collector must accept connections from other containers, which it cannot do bound to loopback.

On a host reachable from an untrusted network, do not publish 4317/4318 with -p. Put the collector and your applications on a shared Docker network instead and let them reach it by container name — nothing needs to be published to the host at all.

'No root_path config set when running in docker environment'

This one changes what your data means, so it is worth acting on.

The hostmetrics receiver inside a container sees the container’s filesystem, not the host’s. Disk and filesystem metrics will describe the collector container — which is small, idle and not what you wanted to monitor.

To report real host metrics, mount the host root read-only and tell the receiver where it is:

-v /:/hostfs:ro

receivers:
  hostmetrics:
    root_path: /hostfs

4. Point your applications at it

Applications on the same host export to the collector rather than to aiAxonIQ. They carry no license key — that is the point.

Same Docker network

# Recommended: no ports published to the host at all.
docker network create observability

docker network connect observability aiaxoniq-collector

docker run -d --name checkout \
  --network observability \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://aiaxoniq-collector:4318" \
  -e OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
  -e OTEL_SERVICE_NAME="checkout" \
  your-image:tag

OTEL_EXPORTER_OTLP_ENDPOINT is a base URL. The SDK appends /v1/traces itself, so a value ending in /v1/traces produces requests to /v1/traces/v1/traces — a 404 that reads like a wrong endpoint and sends people to change the one part that was correct.

Verify

The collector publishes its own metrics on port 8888. Three counters separate the two things that can be wrong:

curl -s localhost:8888/metrics | grep -E 'otelcol_(receiver_accepted|exporter_sent|exporter_send_failed)'

Counter	Rising means
otelcol_receiver_accepted_*	Your application is reaching the collector
otelcol_exporter_sent_*	The collector is reaching aiAxonIQ
otelcol_exporter_send_failed_*	It is trying and being refused

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.

Expected output shortly after start, with host metrics flowing:

otelcol_receiver_accepted_metric_points{receiver="hostmetrics"} 312
otelcol_exporter_sent_metric_points{exporter="otlphttp/aiaxoniq"} 312
otelcol_exporter_send_failed_metric_points{exporter="otlphttp/aiaxoniq"} 0

send_failed at zero and sent climbing is a working install.

Then confirm it landed: open Logs or Infrastructure, set the range to the last 15 minutes, and look for your host. Full detail in Verify your data arrived.

Troubleshooting

The collector starts, then logs 'Exporting failed. Will retry'

Read the error field on that line — it names the cause exactly.

Exporting failed. Will retry the request after interval.
  {"kind": "exporter", "name": "otlphttp/aiaxoniq",
   "error": "failed to make an HTTP request: Post \"…/v1/metrics\":
             dial tcp: lookup … : no such host", "interval": "5.2s"}

• 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.

Nothing at all in the logs after 'Everything is ready'

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.

401 with a key you know is correct

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.

Config changes appear to do nothing

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.

The container exits immediately

Almost always a config error — the collector refuses to start on an invalid configuration rather than running degraded.

docker logs aiaxoniq-collector

Validate before running, which reports the problem without starting anything:

docker run --rm \
  -v "$PWD/config.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:latest \
  validate --config=/etc/otelcol-contrib/config.yaml

Exit code 0 and no output means the config is valid.

Disk and filesystem metrics look wrong or tiny

You are seeing the collector container’s own filesystem. Mount the host root and set root_path — see the root_path warning above.

Applications cannot reach the collector

Confirm which name they should use. On a shared Docker network it is the container name (aiaxoniq-collector); from the host it is localhost; from inside another container reaching the host it is host.docker.internal, which does not exist on Linux without --add-host.

Test from inside the application container rather than from your shell:

docker exec checkout curl -sv http://aiaxoniq-collector:4318/v1/traces

Next

Docker Compose

The same collector as a service in your stack.

Instrument your application

Zero-code setup per language.

Verify your data

Confirm it landed.