Connect your app

atrim.ai is an OpenTelemetry backend. If your application already emits OTLP you do not need an SDK change, a vendor agent, or a code change — you need an endpoint and a header.

Endpoint and authentication

Endpoint	https://otlp.atrim.ai
Protocol	OTLP over HTTP (http/protobuf)
Signal paths	/v1/traces, /v1/metrics, /v1/logs
Auth header	x-api-key: atrim_key_…

Your API key is shown in the app under Admin & Governance → Settings. Keys look like atrim_key_ followed by 32 hex characters.

The key selects the workspace

The API key is what decides which workspace your telemetry lands in. There is no tenant header to set — one is ignored if you send it. Treat the key like a credential: it is write access to your workspace’s data.

A request without a valid key is rejected with 401 Unauthorized, which is also the quickest way to prove connectivity from the machine that will be sending data:

Reachability check

curl -i -X POST https://otlp.atrim.ai/v1/traces \
  -H 'content-type: application/json' \
  -d '{}'
# 401 Unauthorized  → you reached atrim.ai, the key is just missing
# connection error   → egress/DNS/proxy problem, not an atrim.ai problem

Quick path: environment variables

Standard OpenTelemetry environment variables, understood by every language SDK and by the Collector. No SDK configuration, no code change:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.atrim.ai"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=atrim_key_YOUR_KEY_HERE"
export OTEL_SERVICE_NAME="your-service-name"

Add deployment context while you are here — it is what makes the topology and the analysis readable later:

export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.version=1.4.2"

OTEL_SERVICE_NAME is the single most load-bearing value in that list: it is the node label in Service Topology, the grouping key for critical paths, and the identity an incident is opened against. payment-service is useful; app is not.

Per-language setup

Node.js

Auto-instrumentation needs no code in your application at all:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.atrim.ai"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=atrim_key_YOUR_KEY_HERE"
export OTEL_SERVICE_NAME="your-service-name"

node --require @opentelemetry/auto-instrumentations-node/register app.js

HTTP servers and clients, the common database drivers, and the popular messaging libraries are instrumented automatically. Add spans of your own with @opentelemetry/api where the interesting business operations are.

Python

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.atrim.ai"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=atrim_key_YOUR_KEY_HERE"
export OTEL_SERVICE_NAME="your-service-name"

opentelemetry-instrument python app.py

opentelemetry-bootstrap -a install inspects your installed packages and pulls the matching instrumentation libraries, so re-run it when your dependencies change.

Java

Download the agent once, then attach it at startup:

curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.atrim.ai"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=atrim_key_YOUR_KEY_HERE"
export OTEL_SERVICE_NAME="your-service-name"

java -javaagent:./opentelemetry-javaagent.jar -jar your-app.jar

Go

Go has no drop-in agent, so the exporter is wired in code. The environment variables above are still read by the SDK — this is the explicit form:

tracing.go

import (
    "context"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)

func initTracing(ctx context.Context) (*sdktrace.TracerProvider, error) {
    exporter, err := otlptracehttp.New(ctx,
        otlptracehttp.WithEndpoint("otlp.atrim.ai"),
        otlptracehttp.WithHeaders(map[string]string{
            "x-api-key": "atrim_key_YOUR_KEY_HERE",
        }),
    )
    if err != nil {
        return nil, err
    }

    res, err := resource.New(ctx,
        resource.WithAttributes(semconv.ServiceName("your-service-name")),
    )
    if err != nil {
        return nil, err
    }

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(res),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}

Call tp.Shutdown(ctx) on the way out so the last batch is flushed. WithEndpoint takes a host, not a URL, and defaults to TLS — use WithInsecure() only against a local collector.

OpenTelemetry Collector

If you already run a Collector, add atrim.ai as an additional exporter. Your existing backends keep receiving everything they receive today:

otel-collector-config.yaml

exporters:
  otlphttp/atrim:
    endpoint: https://otlp.atrim.ai
    headers:
      x-api-key: atrim_key_YOUR_KEY_HERE

service:
  pipelines:
    traces:  { exporters: [your-existing-exporter, otlphttp/atrim] }
    metrics: { exporters: [your-existing-exporter, otlphttp/atrim] }
    logs:    { exporters: [your-existing-exporter, otlphttp/atrim] }

Keep the key out of the file with the Collector’s environment-variable substitution:

    headers:
      x-api-key: ${env:ATRIM_API_KEY}

On Kubernetes, add the k8sattributes processor

Running on Kubernetes? Add the k8sattributesprocessor to your Collector. It watches the Kubernetes API and stamps the namespace, workload, pod, and node each signal came from onto every span, metric, and log — which is what lets your service map group by namespace → workload → pod and pivot by node.

otel-collector-config.yaml

processors:
  k8sattributes:

service:
  pipelines:
    traces:  { processors: [k8sattributes], exporters: [otlphttp/atrim] }
    metrics: { processors: [k8sattributes], exporters: [otlphttp/atrim] }
    logs:    { processors: [k8sattributes], exporters: [otlphttp/atrim] }

Without it your telemetry still arrives and every other view works — the Kubernetes hierarchy is the one thing that can’t be reconstructed after the fact, so it’s simply absent rather than guessed. I never infer a namespace or node I didn’t observe.

Use your coding agent

If your application is not instrumented yet, hand the job to whatever coding agent you already use. The prompt is short on purpose — your agent knows how to wire OpenTelemetry, and the depth it might want is at a URL it can fetch:

Paste into Claude Code, Cursor, or any coding agent

Send this project's OpenTelemetry to atrim.ai. Add us as an exporter — don't replace one.

  endpoint: https://otlp.atrim.ai
  header:   x-api-key: atrim_key_YOUR_KEY_HERE

Then restart it and confirm a span arrives.
Docs: https://atrim.ai/llms.txt

The same prompt is offered in the product with your real credentials already filled in, and it is editable there before you copy it. https://atrim.ai/llms.txt and https://atrim.ai/llms-full.txt are these docs in a form an agent can read directly.

Troubleshooting

Nothing has arrived. Work down this list — it is ordered by how often each one is the answer.

1. Check the endpoint has no signal path on it.

   OTEL_EXPORTER_OTLP_ENDPOINT is the base URL: https://otlp.atrim.ai. The SDK appends /v1/traces itself. The per-signal variables (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) are the ones that take the full path. Setting the base variable to https://otlp.atrim.ai/v1/traces produces requests to …/v1/traces/v1/traces, which fail silently in most SDKs.

2. Check the header, exactly.

   x-api-key=atrim_key_… in OTEL_EXPORTER_OTLP_HEADERS, = and not :, no Bearer prefix, no quotes inside the value. Multiple headers are comma-separated.

3. Prove reachability from the sending machine.

   Run the curl above from inside the container or host that is exporting — not from your laptop. A 401 means the network path works. A timeout or DNS failure means egress rules, a proxy, or a service mesh is in the way.

4. Check the protocol.

   Set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf. An SDK left on its gRPC default will not reach an HTTP endpoint, and the failure is usually logged once at startup and never again.

5. Turn on the SDK’s own diagnostics.

   Every SDK will tell you it failed to export if you ask it to:

   export OTEL_LOG_LEVEL=debug          # Node.js, Java
   export OTEL_PYTHON_LOG_LEVEL=debug   # Python

   An export error names the cause — TLS, DNS, 401, or a malformed endpoint — far faster than anything on this page.

6. Confirm the process is actually instrumented.

   The agent or --require flag has to be on the command line of the process that serves traffic, not on a wrapper script or a Dockerfile ENTRYPOINT that then execs something else.

7. Generate traffic.

   A batching exporter with no spans to send is indistinguishable from a broken one. Make a few requests against your service, then wait for the batch interval (5 seconds by default).

Still nothing? Send us the output of step 5 at hello@atrim.ai — the SDK’s own export error is almost always enough to resolve it in one round trip.