Quick Start

Connect an application with a coding agent or manual setup.

Telemetry Machine gives you two ways to connect an application. Both start on the same onboarding screen.

Create your account

Sign up with your email address and a password.
Verify your email address, then sign in.
Open an explorer such as Traces. If your organization has no datasets, Telemetry Machine takes you to onboarding.

Option 1Set up with a coding agent

Use this path when a coding agent can edit your application and run commands in its development environment. On the onboarding page, pick your agent in the first step.

Claude Code

In a terminal, install the Telemetry Machine plugin. It needs Claude Code 2.1.292 or later.

Terminal

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

Start Claude Code in your application's folder and run:
Text
```
/telemetry-machine:tm-onboarding
```
On development or staging, the onboarding page adds the site URL after the command, so tm-cli signs in to that site.
Sign in when Claude Code shows you a link and a code.
Answer its questions. Claude Code instruments your application, creates the datasets and API keys it needs, confirms that data arrives, and answers a first question from your data.

If you stop part-way, run the same onboarding command again. It continues from where you stopped.

The plugin also lets Claude Code query Telemetry Machine and investigate production problems. Ask in plain words, or run /telemetry-machine:tm-investigate followed by your question.

Other coding agents

Open your application's repository in your coding agent.
On the onboarding page, pick your agent and copy the generated prompt.

The prompt is shown in full below.
Give the prompt to your agent.
Approve the sign-in in your browser when the agent runs tm-cli auth login.
Let the agent inspect your application and complete the setup.

Your agent can run on another computer

tm-cli auth login prints a URL and a code, and opens the page in a browser when there is one on the same computer. If your coding agent runs remotely, open the URL in your own browser, check that it shows the same code, and approve.

The generated prompt

The prompt uses your current site. This example is for production with the Other agent. For development or staging, its URLs point at that site and the login command adds --base-url <site-url>.

Text

Set up my app to send telemetry to Telemetry Machine, and connect to my account so you can query it.

1. Check `tm-cli --version` against the current release manifest and install or update it:
   https://telemetrymachine.com/downloads/tm-cli/manifest.json
   Pick the artifact for this OS and architecture, check its sha256, and put
   `tm-cli` on $PATH somewhere that does not need sudo.
2. Run `tm-cli auth login`. It opens my browser. Wait while I
   approve, then run `tm-cli auth status` and `tm-cli auth test` to confirm the
   API URL, organization and active credentials. Authentication alone does not verify write access.
   If dataset creation reports a missing scope, sign in again with the updated CLI;
   check whether TM_API_KEY overrides the browser session before requesting permission changes.
3. Download the skills at
   https://telemetrymachine.com/docs/skills/index.json
   Save them wherever you keep skills or project instructions.
   Always bound queries with --since.
4. Read the `otel-instrumentation` skill and its `verification-checklist`
   reference before changing code. Track each checklist step with a TODO
   tool if you have one.
5. Instrument this app with OpenTelemetry for traces and application logs. Use tm-cli
   to create separate traces and logs datasets and the ingest keys they need.
   Connect the existing application logger to an OpenTelemetry log exporter, preserving
   console output. Trace instrumentation alone does not export logs. Preserve severity,
   timestamps and trace correlation when available, and flush logs on shutdown.
   Inspect existing deployment settings and reuse working telemetry configuration.
   Deploy, exercise the app, and verify both a trace and an application log in their
   respective datasets using queries bounded with --since.

With either agent, the Telemetry Machine skills and tm-cli let the agent:

add or update the OpenTelemetry instrumentation;
create the required traces, logs, or metrics datasets and ingest keys;
deploy or run the application; and
verify that the application is sending data.

Keep the onboarding page open if you want to follow its progress. The page tells you when tm-cli has signed in to your organization. This confirms authorization; the agent still needs to finish instrumentation and verify data. Datasets created by the agent appear on the page. Select one to open its explorer.

The CLI saves your login and refreshes the session automatically, so you can keep using it after onboarding. To disconnect, run tm-cli auth logout.

Option 2Set up manually

On the onboarding page, under Set it up yourself, select Create a dataset.
Choose the data you want to send: traces, logs, metrics, or events.
Name the dataset and choose any optional starter widgets.
Create the dataset. Telemetry Machine also creates a starter API key for it.
Copy the API key and store it securely.

Its full value is only shown once.
Choose the generated setup for the OpenTelemetry Collector, Node.js, or Python.
Add the configuration to your application and run or deploy it.
Open the matching explorer and confirm that your data arrives.

The generated setup looks like this, with your API key and dataset name filled in:

otel-collector.yaml

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

service:
  pipelines:
    traces:
      exporters: [otlphttp]
    logs:
      exporters: [otlphttp]

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();

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)

You can repeat the manual wizard to create more datasets for other signal types, services, or environments.