Skip to content
GitHub
Start a 14-day trial

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 https://otlp.atrim.ai
Protocol OTLP over HTTP (http/protobuf)
Compression gzip for SDK exporters; zstd for Collector otlphttp exporters (uncompressed also works)
Signal paths /v1/traces, /v1/metrics, /v1/logs
Auth header x-api-key: atrim_sat_…

The value is an ingest token. Create one under Admin & Governance → Settings → App Onboarding with Generate token: it lands straight in ready-to-paste exporter snippets. The full token is shown only once, so copy it then. Tokens start with atrim_sat_.

An ingest token sends telemetry to its workspace and can confirm that a trace ID has arrived there — nothing more. It can’t read, search, or query your data. To swap a token out without a gap, see rotating and revoking tokens.

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

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

Standard OpenTelemetry environment variables, understood by every language SDK and by the Collector. No SDK configuration, no code change. This is the quickest way to see data; for production, send through an OpenTelemetry Collector: it batches, retries when atrim.ai is unreachable, and fans out to your other backends.

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_sat_YOUR_TOKEN_HERE"
export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"
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"

service.version is also how I notice your deploys with no setup: when a new version takes over a service, I record the deploy within about an hour, and the incidents that open from then on list it. For exact deploy times, rollbacks and the incidents of the first hour, record your deploys from CI as well.

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.

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_sat_YOUR_TOKEN_HERE"
export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"
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.

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

exporters:
  otlphttp/atrim:
    endpoint: https://otlp.atrim.ai
    headers:
      x-api-key: atrim_sat_YOUR_TOKEN_HERE
    compression: zstd
    sending_queue: # needs Collector v0.123.0 or later
      sizer: items
      queue_size: 65536
      batch:
        flush_timeout: 1s
        min_size: 8192
        max_size: 8192

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 token out of the file with the Collector’s environment-variable substitution:

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

The sending_queue block sends to atrim.ai in fewer, larger requests: each goes out within a second of its first record, or as soon as it holds 8,192 spans, metric points, or log records. The queue holds up to 65,536 records in memory. It applies to this exporter only, so your other backends see no change.

It needs Collector v0.123.0 or later. On an older Collector, drop the sending_queue block and batch in your pipelines instead. If they already end in a batch processor, keep it; otherwise define this one and add batch as the last entry in each pipeline’s processors list. A pipeline processor batches for every exporter in that pipeline.

processors:
  batch:
    timeout: 1s
    send_batch_size: 8192
    send_batch_max_size: 8192

On Kubernetes, add the k8sattributes processor

Section titled “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.

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.

Hand the job to whatever coding agent you already use, in any language. The prompt asks it to look before it edits, keep any exporter you already run, add OpenTelemetry’s zero-code instrumentation where there is none, keep your token out of committed files, and confirm the export is accepted:

Send this project's OpenTelemetry to Atrim.

  endpoint:     https://otlp.atrim.ai
  protocol:     http/protobuf
  compression:  gzip for SDK exporters; zstd for a Collector's otlphttp exporter
  header:       x-api-key: atrim_sat_YOUR_TOKEN_HERE
  service name: (choose one per service, see step 5)

The token is a write-only ingest token for this workspace, shared on purpose: it can send
telemetry but can't read any data, and it can be revoked in Atrim under Settings → App
Onboarding.

1. Inspect before editing: the language, framework, how each service is built and started
   (scripts, Dockerfile, Compose, Helm, Procfile) and any OpenTelemetry already present: an
   SDK, an agent or a Collector config. Tell me what you found.
2. If OpenTelemetry is already set up, add Atrim beside it. Don't remove or replace an
   exporter, don't change existing OTEL_EXPORTER_OTLP_* values, and don't start a second SDK.
   - With a Collector, add an OTLP/HTTP exporter for Atrim to its pipelines.
   - With an SDK set up in code, add a second OTLP/HTTP exporter there, configured with the
     endpoint, header and compression above. Where the exporter option takes a full URL rather
     than a host or base endpoint, use the endpoint plus /v1/traces, /v1/metrics or /v1/logs.
   - If the only exporter is set by OTEL_EXPORTER_OTLP_* environment variables, with no code or
     Collector to extend, stop and tell me the options (add a Collector, or point those
     variables at Atrim) rather than choosing.
3. If there is none, add OpenTelemetry's zero-code auto-instrumentation for the language
   (Node.js, Python, Java, .NET, PHP, Ruby); for Go, the SDK plus instrumentation for the
   HTTP framework and database clients already in use. Use the project's package manager and
   current stable releases. Add no manual spans yet. Configure it through the standard
   OTEL_EXPORTER_OTLP_* environment variables where each service starts. The endpoint is the
   base URL: the SDK appends /v1/traces, /v1/metrics and /v1/logs, so don't add a path. The
   header goes in OTEL_EXPORTER_OTLP_HEADERS as x-api-key=<token>, not x-api-key: <token>.
4. If a service runs from an image you don't build (a third-party container or Helm chart),
   add the instrumentation through its deployment config (environment variables, a command
   override or an init container), configured as in step 3. Say which.
5. Set OTEL_SERVICE_NAME on every deployable service, named for what it does (checkout-api,
   not app). Never leave it unset.
6. Wherever the token goes (Collector config, SDK setup or environment), read it from an
   environment variable or the project's secret store. Never write it in a committed file or
   in your output. If you put it in a local env file, check that the file is gitignored; if it
   isn't, don't write the token there, and tell me. Add a placeholder to .env.example (or the
   equivalent) if there is one.
7. Send traces, plus metrics and logs where the SDK exports them over OTLP.
8. Run the project's existing checks. Start the app the way the project does, exercise it (a
   few requests, or one run of a job), and confirm the export is accepted (OTEL_LOG_LEVEL=debug
   shows export errors; 401 means the header is wrong). Check that each span is exported once
   (one Atrim exporter per path, not in both an SDK and the Collector it sends to) and that
   one request produces one trace, not two from duplicate instrumentation.
9. Leave the changes uncommitted and report the files changed, the environment variables to
   set, how to start it, and anything you could not check. I'll confirm arrival in Atrim
   under Settings → App Onboarding → Check that your telemetry arrived.

If anything here is unclear, read Atrim's agent docs rather than guessing: https://atrim.ai/llms.txt

The same prompt is offered in the product — Settings → App Onboarding → Have my coding agent do it — with your real endpoint and token already filled in and an optional service name, 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. Connect with a coding agent walks the whole round trip, from this prompt to handing your agent what atrim.ai found.

Start in the product: Settings → App Onboarding → Check that your telemetry arrived. It reports what actually reached us, so you rarely have to guess. If your telemetry is arriving but something is off, it names it — spans with no service.name, a request that was accepted but carried no records, a payload that was rejected, or a temporary refusal while the platform finishes starting — and tells you what to change. Only when it shows nothing has arrived at all do you need the list below.

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_sat_… in OTEL_EXPORTER_OTLP_HEADERS, = and not :, no Bearer prefix, no quotes inside the value. Multiple headers are comma-separated. The value starts with atrim_sat_; anything else is refused, so generate a token and paste it in. A token that used to work and now gets 401 has been revoked — its Status in Settings → App Onboarding reads revoked.

  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.