Getting Started

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. The prompt includes a short-lived onboarding credential that expires after one day.
4. Choose whether the agent should install the Telemetry Machine skills for this project only or globally for all projects.
5. Let the agent inspect your application and complete the setup.

The generated prompt looks like this. Telemetry Machine replaces <one-day onboarding token> with your credential.

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.

Provide this PAT (1-day expiry) to `tm-cli` as `TM_API_KEY` for this session:
  `export TM_API_KEY="<one-day onboarding token>"`

If `tm-cli` has no context yet, create and select an onboarding context:

```bash
tm-cli contexts create telemetry-machine-onboarding --base-url https://telemetrymachine.com --api-key "$TM_API_KEY"
tm-cli contexts use telemetry-machine-onboarding
```

Run `tm-cli orgs list` to confirm access.

Once onboarding is fully complete, tell me that this PAT expires in 1 day. After onboarding, I should create a longer-term PAT and store it in `tm-cli`'s config. The path can be found with `tm-cli config path`.

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 Agent connected after the agent checks in with tm-cli. Datasets created by the agent appear on the page. Select one to open its explorer.

The onboarding credential is only for initial setup. If you want to keep using tm-cli after onboarding, create a longer-lived personal access token and store it in the tm-cli config file.

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 atoms.
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.