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
Section titled “Endpoint and authentication”| 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:
Quick path: environment variables
Section titled “Quick path: environment variables”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.
Add deployment context while you are here — it is what makes the topology and the analysis readable later:
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.
Per-language setup
Section titled “Per-language setup”Auto-instrumentation needs no code in your application at all:
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.
opentelemetry-bootstrap -a install inspects your installed packages and pulls the matching
instrumentation libraries, so re-run it when your dependencies change.
Download the agent once, then attach it at startup:
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:
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.
Effect has tracing built in, so you set up no OpenTelemetry SDK — only the exporter layer from
@effect/opentelemetry:
Every Effect.withSpan becomes a span, and Effect.log inside one becomes a log record on the
same trace. The layer sends traces, metrics and logs; baseUrl is the base endpoint, and the layer
adds /v1/traces, /v1/metrics and /v1/logs itself. The endpoint and token come only from
code — the layer does not read OTEL_EXPORTER_OTLP_*. It merges OTEL_RESOURCE_ATTRIBUTES into the
resource either way; leave resource out and the service name comes from that variable’s
service.name, or else from OTEL_SERVICE_NAME, one of which must be set. Provide the
layer once, at the edge of your program: when the program exits, the layer sends what it has not sent yet.
Confirm arrival under Settings → App Onboarding → Check that your telemetry arrived: the layer logs a failed export only at Debug level, which the default log level hides, so a wrong token or an unreachable endpoint looks the same as success.
Tested on effect 3.22.1, @effect/opentelemetry 0.64.0, @effect/platform 0.97.1 and
@effect/platform-node 0.108.1.
OpenTelemetry Collector
Section titled “OpenTelemetry Collector”If you already run a Collector, add atrim.ai as an additional exporter. Your existing backends keep receiving everything they receive today:
Keep the token out of the file with the Collector’s environment-variable substitution:
Batch what you send
Section titled “Batch what you send”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.
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.
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
Section titled “Use your coding agent”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:
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.
Troubleshooting
Section titled “Troubleshooting”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.
-
Check the endpoint has no signal path on it.
OTEL_EXPORTER_OTLP_ENDPOINTis the base URL:https://otlp.atrim.ai. The SDK appends/v1/tracesitself. The per-signal variables (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) are the ones that take the full path. Setting the base variable tohttps://otlp.atrim.ai/v1/tracesproduces requests to…/v1/traces/v1/traces, which fail silently in most SDKs. -
Check the header, exactly.
x-api-key=atrim_sat_…inOTEL_EXPORTER_OTLP_HEADERS,=and not:, noBearerprefix, no quotes inside the value. Multiple headers are comma-separated. The value starts withatrim_sat_; anything else is refused, so generate a token and paste it in. A token that used to work and now gets401has been revoked — its Status in Settings → App Onboarding readsrevoked. -
Prove reachability from the sending machine.
Run the
curlabove from inside the container or host that is exporting — not from your laptop. A401means the network path works. A timeout or DNS failure means egress rules, a proxy, or a service mesh is in the way. -
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. -
Turn on the SDK’s own diagnostics.
Every SDK will tell you it failed to export if you ask it to:
An export error names the cause — TLS, DNS, 401, or a malformed endpoint — far faster than anything on this page.
-
Confirm the process is actually instrumented.
The agent or
--requireflag has to be on the command line of the process that serves traffic, not on a wrapper script or aDockerfileENTRYPOINTthat thenexecs something else. -
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.