Documentation

Quick Start

Connect an application with a coding agent or manual setup.

Telemetry Machine gives you two ways to connect an application:

  • AI setup lets a coding agent instrument your application, create the required datasets and API keys, and verify that data arrives.
  • Manual setup lets you create the datasets and API keys yourself, then use the generated OpenTelemetry configuration.

Both paths start in the same onboarding screen.

Create your account

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

Option 1: Set up with a coding agent

Use this path when a coding agent can edit your application and run commands in its development environment.

  1. Open your application's repository in your coding agent.
  2. In Telemetry Machine, select Start AI setup.
  3. Copy the generated prompt and give it to your agent.
  4. Follow your agent's instructions to run tm-cli auth login, then tell it once you've signed in.
  5. Let the agent inspect your application and complete the setup.

The generated prompt

The prompt uses your current site and organization. This example uses production and my-org. For development or staging, the generated login command adds --base-url <site-url>; subsequent commands use the saved server.

Start by asking me whether I want the Telemetry Machine skills downloaded only for this project or globally.

If I choose project-local, download them under `<repo root>/skills/telemetry-machine/`.

If I choose global, use this agent's global skills directory.

Download the full Telemetry Machine skill bundle from:
  `https://telemetrymachine.com/docs/skills/index.json`

Read the downloaded `otel-instrumentation` skill and its `verification-checklist` reference before changing code.

Use a TODO tool, if available, to make sure you cover each step of `verification-checklist`.

You must use `tm-cli`. If `tm-cli` is not installed, download it using the latest `tm-cli` manifest:
  `https://telemetrymachine.com/downloads/tm-cli/manifest.json`

Choose the artifact for this OS/architecture, download its URL, verify its `sha256` if possible, extract `tm-cli`, and place the binary in `~/.local/bin` or somewhere else in `$PATH` that does not need sudo.

Once tm-cli is installed, ask me to run `tm-cli auth login` and ask me to tell you once I've logged in: "Please tell me once you've successfully authenticated. If you run into any issues, you can paste the output here."

After login succeeds, confirm access:
```bash
tm-cli auth test
tm-cli datasets list
```

Keep in mind:
Deploy and validate as you go.
If you do not have or lost access to an ingest key's value, feel free to create a new one.

The agent uses the Telemetry Machine skills and tm-cli to:

  • 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. It shows CLI connected after browser login issues a CLI token for 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.

The browser and CLI must run on the same computer. --no-browser prints the login URL but does not enable login from another computer. If your coding agent runs remotely, run the agent and CLI on a computer with your browser before starting this flow.

Option 2: Set up manually

  1. Select Continue with manual setup.
  2. Choose the data you want to send: traces, logs, metrics, or events.
  3. Name the dataset and choose any optional starter widgets.
  4. Create the dataset. Telemetry Machine also creates a starter API key for it.
  5. Copy the API key and store it securely. Its full value is only shown once.
  6. Choose the generated setup for the OpenTelemetry Collector, Node.js, or Python.
  7. Add the configuration to your application and run or deploy it.
  8. Open the matching explorer and confirm that your data arrives.

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