OpenTelemetry

Squasher accepts OpenTelemetry data over OTLP/HTTP and OTLP/gRPC. Any language with an OpenTelemetry SDK, and any OpenTelemetry Collector, can send traces, logs, and metrics without a Squasher package. This page is the reference for the endpoint and headers that the other guides use. For the full accept and reject matrix, including protobuf aliases and intentional non-goals, see OTLP contract.

Endpoint and headers

Setting	Value
Base URL	`https://ingest.squasher.ai`
Traces	`POST /v1/traces`
Logs	`POST /v1/logs`
Metrics	`POST /v1/metrics`
Protocol	OTLP/HTTP with protobuf (`application/x-protobuf`) or JSON (`application/json`)
Compression	None, or `gzip`
Key	`x-squasher-key: <key>` or `Authorization: Bearer <key>`

OTLP requests do not need a project ID. Squasher finds the project from the ingest key. To get a key, see Create an ingest key. The Setup page also shows a Collector URL. Send OTLP/HTTP to https://ingest.squasher.ai instead: the project rate limit and region routing apply to that endpoint. Use the Collector URL only for OTLP/gRPC.

Send over gRPC

Squasher also accepts OTLP/gRPC for traces, logs, and metrics. Send gRPC to the Collector URL on the Setup page on port 443 with TLS. For a US project, that is https://collector-us.squasher.ai. Do not use port 4317.

export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector-us.squasher.ai:443
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_HEADERS="x-squasher-key=$SQUASHER_API_KEY"

The key, the project rate limit, and the stored data are the same as for OTLP/HTTP. Squasher accepts gzip compression. The exporter gets these gRPC status codes:

Status	Cause	Exporter action
`OK`	The batch is stored or saved for replay	None
`UNAUTHENTICATED`	Missing or invalid key	Fix the key
`RESOURCE_EXHAUSTED`	Project rate limit exceeded (`RetryInfo`)	Retries after the given delay
`RESOURCE_EXHAUSTED`	Free plan monthly allowance used (no `RetryInfo`)	Drops the batch; no retry
`UNAVAILABLE`	Temporary ingest unavailability	Retries with backoff

Set the exporter variables

Most OpenTelemetry SDKs read these variables. With the base URL, the SDK adds /v1/traces, /v1/logs, and /v1/metrics itself.

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.squasher.ai
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="x-squasher-key=$SQUASHER_API_KEY"
export OTEL_SERVICE_NAME=checkout-api
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production

Set deployment.environment.name. Squasher reads the environment from that attribute, and from the older deployment.environment when an SDK still sends it. Automatic AI triage runs only on issues in the production environment by default.

Connect your service

Node.js
Other languages
OpenTelemetry Collector

Install the packages

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

Start your app with the register hook

Set the variables above, then start Node.js with the hook. It reads the variables and turns on automatic instrumentation.

export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
node --require @opentelemetry/auto-instrumentations-node/register app.js

Add Squasher as an otlphttp exporter. Keep the key in an environment variable.

otel-collector-config.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch: {}

exporters:
  otlphttp/squasher:
    endpoint: https://ingest.squasher.ai
    headers:
      x-squasher-key: "${env:SQUASHER_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/squasher]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/squasher]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/squasher]

To keep your current backend, add otlphttp/squasher next to its exporter in each pipeline.

What Squasher does with each signal

Signal	What Squasher stores	Creates an issue when
Traces	Spans with attributes, events, and links	The span has an exception event, or the span status is `ERROR`
Logs	Log records with their resource and record attributes	The severity number is 17 (`ERROR`) or more, or the record holds an exception at `WARN` (13) or more
Metrics	Gauges, sums, histograms, and exponential histograms	Never

A span with the status ERROR makes one issue occurrence. The title is the status message, or the span name when the message is empty. When the span has exception events, the last one adds its attributes and stack trace to the occurrence.
An HTTP client span for a HEAD request that got a 404 response does not make an issue, also when its status is ERROR. A HEAD request asks if a resource exists, so 404 is the answer and not a failure. Squasher keeps the span with its status. Other methods and status codes make an issue as usual.
On a span without the ERROR status, each span event named exception, or with a name that ends in .exception, makes one issue occurrence, titled with exception.message, then exception.type. The event needs one of them. Squasher reads up to 32 such events from one span and 1,000 from one request.
A log record holds an exception when it has exception.type or exception.message, or when its event name is exception or ends in .exception. At severity 1 to 12 (TRACE to INFO) it stays a log record and does not make an issue.
The issue page shows the stack trace from exception.stacktrace.
Squasher groups issues by service.name, the error.type or exception.type attribute, and the first line of the message. An exception sent as a span event and again as a log record makes two occurrences.
Squasher drops summary metrics.

Spans that carry AI attributes go to AI observability as well. Squasher recognizes OpenTelemetry gen_ai.* attributes, Vercel AI SDK ai.* attributes, Langfuse langfuse.* attributes, OpenLLMetry llm.*, traceloop.*, and indexed gen_ai.prompt.<n>.* attributes, OpenInference attributes (with indexed llm.input_messages.<n>.* messages), lmnr.* and mlflow.* span attributes, and the anthropic.* spans of the Claude API and SDK. These log events also go to AI observability, one model call or tool call each:

Producer	Log events
OpenTelemetry GenAI	`gen_ai.client.inference.operation.details`
Claude Code	`claude_code.api_request`, `claude_code.api_error`, `claude_code.tool_result`
Codex	`codex.sse_event` (the completed response), `codex.tool_result`
Gemini CLI	`gemini_cli.api_response`, `gemini_cli.api_error`, `gemini_cli.tool_call`

A model call counts once. When a span that reports usage holds another span or log event that reports usage, Squasher counts the inner one. Claude Code logs its events in the interaction span, not in the request span, so Squasher joins its claude_code.llm_request span and its claude_code.api_request event by the API request ID, and its tool spans and tool_result events by the tool use ID. So an agent that sends both traces and log events, or an SDK span around a provider span, does not count the same tokens twice. AI metrics, such as gen_ai.client.token.usage, stay metrics: they are totals without a call, so Squasher does not add them to AI observability.

Use current attribute names

Squasher follows the OpenTelemetry semantic conventions, version 1.44.0, and the GenAI conventions. Send the current attribute names. Squasher also accepts older names, because many SDKs still send them.

When a resource, span, span event, log record, or metric point has an older name and not the current name, Squasher adds the current name with the same value. The older attribute stays.
When both names are present with different values, Squasher uses the current name.
AI attributes from the Vercel AI SDK, OpenInference, OpenLLMetry, and Langfuse also get the matching gen_ai.* name, for example ai.usage.promptTokens to gen_ai.usage.input_tokens.
Some values change with the name, as the conventions say. For example, db.system=mssql becomes db.system.name=microsoft.sql_server, and an http.method outside the standard list becomes _OTHER. Search and dashboard filters convert an older value too, so db.system:mssql finds both forms. In SQL, compare with the current value.
Squasher does not rename metrics. Some metric renames also changed the unit, for example http.server.duration in milliseconds to http.server.request.duration in seconds.

Older name	Current name
`deployment.environment`	`deployment.environment.name`
`http.method`	`http.request.method`
`http.status_code`	`http.response.status_code`
`http.url`	`url.full`
`db.system`	`db.system.name`
`db.statement`	`db.query.text`
`code.filepath`	`code.file.path`
`gen_ai.system`	`gen_ai.provider.name`
`gen_ai.usage.prompt_tokens`	`gen_ai.usage.input_tokens`

Search, dashboards, monitors, and SQL queries can use either name. Squasher reads the current name first, then the older one, so data from before and after an SDK upgrade appears together.

Verify

Send one span with status ERROR, or one log record at ERROR severity.
Select Issues in the sidebar. The error is at the top of the list.
Select Logs in the sidebar, then choose Traces, Logs, or Metrics in the source menu to see the raw data.

If nothing arrives, check the exporter’s own logs for 401 (wrong key), 415 (wrong content type), or 404 (a wrong path). A gRPC exporter that sends to ingest.squasher.ai or to port 4317 also fails; send gRPC to the Collector URL on port 443.

Limits

A 200 response means that Squasher stored the batch or saved it for replay. Delivery is at least once, so a retry can store a duplicate. Keep stable trace and span IDs.
Retry 429 and 5xx responses with backoff. Do not retry other 4xx responses before you fix the request.
Each project can send 10,000 records per minute by default. Squasher counts each span, log record, and metric point.
A gzip body can expand to at most 16 MiB.

Next steps

OTLP contract

Paths, media types, responses, limits, and non-goals.

Tail sampling

Keep error and slow traces and drop routine ones.

Prometheus metrics

Send Prometheus metrics through a Collector.

Kubernetes

Collect pod logs and workload metrics with Helm.

Read AI triage

Learn what the triage summary tells you.

Get started

Guides

Endpoint and headers

Send over gRPC

Set the exporter variables

Connect your service

What Squasher does with each signal

Use current attribute names

Verify

Limits

Next steps

OTLP contract

Tail sampling

Prometheus metrics

Kubernetes

Read AI triage

​Endpoint and headers

​Send over gRPC

​Set the exporter variables

​Connect your service

​What Squasher does with each signal

​Use current attribute names

​Verify

​Limits

​Next steps

OTLP contract

Tail sampling

Prometheus metrics

Kubernetes

Read AI triage

Endpoint and headers

Send over gRPC

Set the exporter variables

Connect your service

What Squasher does with each signal

Use current attribute names

Verify

Limits

Next steps