Telemetry Machine

https://telemetrymachine.com/docs
Admin
Telemetry Machine is a platform for sending OpenTelemetry traces, logs, and metrics and querying...
Tokens:11,807
Snippets:106
Trust Score:4.1
Update:3 hours ago
Show doc for...
Tokens:
Raw
### Node.js instrumentation with OpenTelemetry SDK

Source: https://telemetrymachine.com/docs/quick-start

Generated setup for Node.js using the OpenTelemetry SDK. Configures trace and log exporters with your API key and dataset name, then starts the SDK.

```javascript
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://api.telemetrymachine.com/v1/traces',
    headers: {
      'X-API-Key': '<your-api-key>',
      'X-Dataset-Name': '<your-dataset>',
    },
  }),
  logRecordExporter: new OTLPLogExporter({
    url: 'https://api.telemetrymachine.com/v1/logs',
    headers: {
      'X-API-Key': '<your-api-key>',
      'X-Dataset-Name': '<your-dataset>',
    },
  }),
});

sdk.start();
```

--------------------------------

### Start onboarding with Claude Code

Source: https://telemetrymachine.com/docs/quick-start

Run this command in Claude Code to start the onboarding process. If you stop part-way, run the same command again to continue from where you stopped.

```text
/mcp__plugin_telemetry-machine_telemetry-machine__onboarding
```

--------------------------------

### Create events dataset with tm-cli

Source: https://telemetrymachine.com/docs/json-events

Creates an events dataset named checkout-events using tm-cli. Requires tm-cli installed and signed in, and owner or admin permissions.

```bash
$ tm-cli datasets create --name checkout-events --type events
```

--------------------------------

### Get dataset schema with tm-cli

Source: https://telemetrymachine.com/docs/json-events

Use this command to view the columns of an events dataset. Replace 'checkout-events' with your dataset name.

```bash
$ tm-cli schema get checkout-events --type events
```

--------------------------------

### Python instrumentation with OpenTelemetry SDK

Source: https://telemetrymachine.com/docs/quick-start

Generated setup for Python using the OpenTelemetry SDK. Configures a span exporter with your API key and dataset name, and sets the tracer provider.

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()

exporter = OTLPSpanExporter(
    endpoint="https://api.telemetrymachine.com/v1/traces",
    headers={
        "X-API-Key": "<your-api-key>",
        "X-Dataset-Name": "<your-dataset>",
    },
)

provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
```

--------------------------------

### Install Telemetry Machine plugin for Claude Code

Source: https://telemetrymachine.com/docs/quick-start

Install the Telemetry Machine plugin for Claude Code. Requires Claude Code 2.1.292 or later. The plugin adds the Telemetry Machine MCP server.

```shell
$ claude plugin install telemetry-machine --marketplace https://telemetrymachine.com/docs/skills/marketplace.json
```

--------------------------------

### OpenTelemetry Collector configuration for Telemetry Machine

Source: https://telemetrymachine.com/docs/quick-start

Generated setup for the OpenTelemetry Collector. Configure the OTLP HTTP exporter with your API key and dataset name. Note: Collector versions before v0.144.0 call the exporter `otlphttp`.

```yaml
exporters:
  otlp_http:
    endpoint: "https://api.telemetrymachine.com"
    headers:
      X-API-Key: "<your-api-key>"
      X-Dataset-Name: "<your-dataset>"

service:
  pipelines:
    traces:
      exporters: [otlp_http]
    logs:
      exporters: [otlp_http]
```

--------------------------------

### Cast attribute value to BIGINT for numeric comparison

Source: https://telemetrymachine.com/docs/writing-effective-queries

Attribute values are stored as strings, even when the instrumentation sent a number or a boolean. Cast them for numeric comparisons and math. This example checks if an HTTP response status code is 500 or greater.

```SQL
CAST("attr.http.response.status_code" AS BIGINT) >= 500
```

--------------------------------

### Extract string from JSON attribute with json_get_str

Source: https://telemetrymachine.com/docs/writing-effective-queries

Arrays, key-value lists, and span events are stored as JSON text. The `datafusion-functions-json` extension reads them. A path is a list of keys and array indexes. This example extracts the user agent from an HTTP request header attribute.

```SQL
json_get_str("attr.http.request.header.user_agent", 0)
```

--------------------------------

### Ask other coding agents to set up with MCP

Source: https://telemetrymachine.com/docs/quick-start

Use this prompt with other coding agents after adding the remote MCP server. It instructs the agent to call get_onboarding_guide and follow it to set up the app.

```text
Use the telemetry-machine MCP server: call get_onboarding_guide and follow it to set up this app.
```

--------------------------------

### Create API key for dataset with tm-cli

Source: https://telemetrymachine.com/docs/json-events

Creates an API key that can write to the checkout-events dataset. The output shows the full key in api_key.api_key, and it is shown only once.

```bash
$ tm-cli api-keys create --name checkout-backend --dataset checkout-events
```

--------------------------------

### Set OTLP environment variables for Telemetry Machine

Source: https://telemetrymachine.com/docs/send-opentelemetry

Configure the OpenTelemetry exporter to send traces and logs to Telemetry Machine. Set the endpoint, protocol, and per-signal headers. Replace <ingest-key> with your actual ingest key and use dataset names like shop-prod-traces.

```shell
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.telemetrymachine.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=X-API-Key=<ingest-key>,X-Dataset-Name=shop-prod-traces
OTEL_EXPORTER_OTLP_LOGS_HEADERS=X-API-Key=<ingest-key>,X-Dataset-Name=shop-prod-logs
```

--------------------------------

### Sign in with tm-cli

Source: https://telemetrymachine.com/docs/quick-start

Sign in to Telemetry Machine using the tm-cli command line tool. In CI, set TM_API_KEY to a personal access token instead.

```shell
tm-cli auth login
```

--------------------------------

### OTLP Endpoint Configuration

Source: https://telemetrymachine.com/docs/send-opentelemetry

Environment variables for configuring the OpenTelemetry exporter to send data to Telemetry Machine.

```APIDOC
## OTLP Endpoint Configuration

### Description
Configure the OpenTelemetry exporter to send traces, logs, and metrics to Telemetry Machine using environment variables.

### Endpoint
`https://api.telemetrymachine.com`

### Paths
- `/v1/traces`
- `/v1/logs`
- `/v1/metrics`

### Protocol
OTLP over HTTP with Protocol Buffers (`http/protobuf`)

### Headers
- `X-API-Key` (ingest key)
- `X-Dataset-Name` (dataset name)

### Environment Variables
```
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.telemetrymachine.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=X-API-Key=<ingest-key>,X-Dataset-Name=shop-prod-traces
OTEL_EXPORTER_OTLP_LOGS_HEADERS=X-API-Key=<ingest-key>,X-Dataset-Name=shop-prod-logs
```

### Notes
- Rejects OTLP JSON and does not expose OTLP over gRPC.
- Accepts gzip-compressed bodies.
- Each dataset holds one type of data: traces, logs, metrics, or events.
- Routes each request by its `X-Dataset-Name` header.
- Set per-signal variables, not `OTEL_EXPORTER_OTLP_HEADERS`.
- Name datasets `<app>-<environment>-<signal>`, e.g., `shop-prod-traces`.
```

--------------------------------

### Calculate counter rate with counter_rate window function

Source: https://telemetrymachine.com/docs/writing-effective-queries

OpenTelemetry cumulative sums keep a running total that drops to zero when a process restarts. `counter_rate(value, _time)` returns the increase per second since the previous row. Partition by the series and order by time.

```SQL
counter_rate(value_double, _time) OVER (
  PARTITION BY "resource.service.instance.id" ORDER BY _time)
```

--------------------------------

### Query your events

Source: https://telemetrymachine.com/docs/json-events

Describes how to query events after sending them, including using the application or tm-cli commands.

```APIDOC
## Query your events

### Description
Events are usually available to queries a few seconds after a success response, sometimes up to 30 seconds. Use the application or tm-cli to query events.

### Usage
- Open Query in the application and select your events dataset.
- Use tm-cli commands to view schema or query events.

### tm-cli Commands
#### Get schema
```
$ tm-cli schema get checkout-events --type events
```

#### Query events of the last hour
```
$ tm-cli query checkout-events --type events --since 1h --limit 20
```
```

--------------------------------

### Query events from the last hour with tm-cli

Source: https://telemetrymachine.com/docs/json-events

Use this command to query events from the last hour, limited to 20 results. Adjust '--since' and '--limit' as needed.

```bash
$ tm-cli query checkout-events --type events --since 1h --limit 20
```

--------------------------------

### Collector configuration with otlp_http exporters for traces and logs

Source: https://telemetrymachine.com/docs/send-opentelemetry

Defines two otlp_http exporters (traces and logs) pointing to the Telemetry Machine API with API key and dataset headers, plus corresponding pipelines. Collector versions before v0.144.0 use the exporter name 'otlphttp' instead.

```yaml
exporters:
  otlp_http/traces:
    endpoint: https://api.telemetrymachine.com
    headers:
      X-API-Key: ${env:TM_INGEST_KEY}
      X-Dataset-Name: shop-prod-traces
  otlp_http/logs:
    endpoint: https://api.telemetrymachine.com
    headers:
      X-API-Key: ${env:TM_INGEST_KEY}
      X-Dataset-Name: shop-prod-logs

service:
  pipelines:
    traces:
      exporters: [otlp_http/traces]
    logs:
      exporters: [otlp_http/logs]
```

--------------------------------

### Send a request again

Source: https://telemetrymachine.com/docs/json-events

Guidance on retrying requests when receiving 429, 500, or 503 status codes, or no response. Use a new Idempotency-Key for each new request, and reuse the same key and body for retries.

```APIDOC
## Send a request again

### Description
Retry a request if the status is 429, 500, or 503, or if no response is received. Use a new `Idempotency-Key` for each new request, and reuse the same key and body for retries.

### Method
POST

### Endpoint
(Not specified)

### Parameters
#### Headers
- **Idempotency-Key** (string) - Required - A unique key for each new request. Reuse the same key and body for retries.

### Request Example
(Not provided)

### Response
#### Success Response (200)
- Returns the first response again if the same request is sent with the same key within 5 minutes.

#### Error Response (429, 500, 503)
- Retry the request with a new `Idempotency-Key`.

### Notes
- If a request does not have `Idempotency-Key`, it is treated as a new request and may duplicate events.
- If a large request is split into parts and one part fails, send the full request again with the same key.
```

--------------------------------

### Estimate histogram percentile with otlp_hist_percentile

Source: https://telemetrymachine.com/docs/writing-effective-queries

`otlp_hist_percentile(bounds, counts, quantile)` adds up the buckets of OTLP explicit-bucket histograms in a group and estimates a percentile. The quantile must be a literal.

```SQL
otlp_hist_percentile("hist.explicit_bounds", "hist.bucket_counts", 0.99)
```

--------------------------------

### Limits

Source: https://telemetrymachine.com/docs/json-events

Lists the limits for event requests, including body size, event size, number of events, fields, depth, event time, column name length, idempotency key length, and request rate.

```APIDOC
## Limits

### Description
Defines the maximum values for event requests. If a request exceeds any limit, Telemetry Machine rejects the full request with appropriate status codes.

### Limits Table
| Item | Limit |
| --- | --- |
| Request body, as sent | 32 MiB |
| One event | Less than 4 MiB |
| Events in one request | 65,536 |
| Different fields in one request | 249 |
| Events multiplied by different fields in a request | 1,048,576 |
| Depth of objects and arrays in one event | 64 levels |
| Event time | 1973 to 2262 |
| Column name | 1,024 bytes |
| `Idempotency-Key` | 512 characters |
| Requests for each API key | 1,000 per second, bursts up to 5,000 |

### Error Handling
- **413** - Request body size exceeds limit.
- **429** - Request rate exceeds limit.
- **400** - Other limits exceeded.
```

--------------------------------

### Query for unhandled errors by missing exception.slug

Source: https://telemetrymachine.com/docs/send-opentelemetry

Use this SQL query to find errors that lack an exception.slug attribute, which indicates they were not handled with a fixed error slug. It filters for status_code 2 and checks that attr.exception.slug is NULL.

```SQL
"status_code" = 2 AND "attr.exception.slug" IS NULL
```

--------------------------------

### Send compressed NDJSON events with curl

Source: https://telemetrymachine.com/docs/json-events

Sends a gzip-compressed NDJSON file to the /v1/events endpoint. Requires the Content-Encoding: gzip header and uses --data-binary @- to stream the compressed data.

```shell
gzip -c events.ndjson | curl https://api.telemetrymachine.com/v1/events \
  -H "X-API-Key: $TM_API_KEY" \
  -H "X-Dataset-Name: checkout-events" \
  -H "Content-Type: application/x-ndjson" \
  -H "Content-Encoding: gzip" \
  --data-binary @-
```

--------------------------------

### Send a single event with curl

Source: https://telemetrymachine.com/docs/json-events

Sends one JSON event to the /v1/events endpoint. Requires an API key with write access to the dataset. The Idempotency-Key header is optional but recommended for retries.

```shell
curl https://api.telemetrymachine.com/v1/events \
  -H "X-API-Key: $TM_API_KEY" \
  -H "X-Dataset-Name: checkout-events" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c2f0e9a-3b1d-4f7e-9a58-0d4b1c7e2a91" \
  -d '{
    "timestamp": "2026-10-08T12:00:00Z",
    "uuid": "0b8e7c52-6d1f-4a3e-b9c4-5f2a8d1e7c60",
    "event": "order.paid",
    "order": { "id": "A-1042", "total": 129.5, "currency": "EUR" },
    "user": { "id": 77, "plan": "pro" }
  }'
```

--------------------------------

### POST /v1/events

Source: https://telemetrymachine.com/docs/json-events

Sends events to Telemetry Machine. The request body can be a single JSON object, an array of JSON objects, or NDJSON. Requires an API key and dataset name.

```APIDOC
## POST /v1/events

### Description
Sends events to Telemetry Machine. The request body can be a single JSON object, an array of JSON objects, or NDJSON. Requires an API key and dataset name.

### Method
POST

### Endpoint
https://api.telemetrymachine.com/v1/events

### Headers
- **X-API-Key** (string) - Required - The API key.
- **X-Dataset-Name** (string) - Required - The name of the dataset. Uppercase and lowercase letters are the same.
- **Content-Type** (string) - Required - `application/json` or `application/x-ndjson`.
- **Content-Encoding** (string) - Optional - `gzip` or `zstd`, if you compress the body.
- **Idempotency-Key** (string) - Optional - A different value for each request, 512 characters maximum.

### Request Body
The body can have one of these forms:
- One JSON object, with `Content-Type: application/json`.
- A JSON array of objects, with `Content-Type: application/json`.
- One JSON object on each line (NDJSON), with `Content-Type: application/x-ndjson`.

Send only JSON objects. Telemetry Machine does not keep array items or lines that are not objects. If one NDJSON line is not valid JSON, Telemetry Machine rejects the full request.

### Request Example
```
curl https://api.telemetrymachine.com/v1/events \
  -H "X-API-Key: $TM_API_KEY" \
  -H "X-Dataset-Name: checkout-events" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c2f0e9a-3b1d-4f7e-9a58-0d4b1c7e2a91" \
  -d '{
    "timestamp": "2026-10-08T12:00:00Z",
    "uuid": "0b8e7c52-6d1f-4a3e-b9c4-5f2a8d1e7c60",
    "event": "order.paid",
    "order": { "id": "A-1042", "total": 129.5, "currency": "EUR" },
    "user": { "id": 77, "plan": "pro" }
  }'
```

### Response
No response details are provided in the source.
```
Tokens:
Raw