Quickstart

Send a trace to telemetry.dev with TypeScript or Python in five minutes.

This guide sends one trace from a small sample program and finds it in the dashboard. The sample records a model call with a fixed answer, so you don’t need a model-provider key.

You need Node.js 22.18 or later, which runs TypeScript files directly, or Python 3.10 or later.

Create a project and copy its API key

Sign in at telemetry.dev and create a project. The Project created dialog shows the project’s first API key, named default. Copy it now: telemetry.dev shows the full key only once. Keys start with td_live_.

If you closed the dialog, create another key on the project’s API keys page.

Install the SDK

npm install @telemetry-dev/sdk

pip install telemetry-dev

Set your API key

The SDKs read their settings from environment variables. In the terminal where you will run the sample:

export TELEMETRY_DEV_API_KEY=td_live_...
export TELEMETRY_DEV_ENVIRONMENT=development
export OTEL_SERVICE_NAME=quickstart

The SDKs don’t load .env files. If you keep these values in one, load it the way your app already does, for example with node --env-file=.env.

Save the sample

Save one of these files. It records an agent span named after the function, with one model-call span inside it.

import { init, observe, shutdown, startSpan } from "@telemetry-dev/sdk";

init();

const planTrip = observe(
  async function planTrip(city: string) {
    const generation = startSpan("chat gpt-5-mini", {
      type: "generation",
      model: "gpt-5-mini",
      provider: "openai",
      input: [{ role: "user", content: `Plan a day trip to ${city}` }],
    });

    // A real app calls the model here. The fixed answer lets the sample run without a provider key.
    const answer = "Take the scenic route.";

    generation.end({
      output: [{ role: "assistant", content: answer }],
      usage: { inputTokens: 11, outputTokens: 7 },
      finishReason: "stop",
    });
    return answer;
  },
  { type: "agent", agentName: "trip-planner" },
);

console.log(await planTrip("Kyoto"));
await shutdown();

import telemetry_dev
from telemetry_dev import observe, start_span

telemetry_dev.init()


@observe(type="agent")
def plan_trip(city: str) -> str:
    with start_span(
        "chat gpt-5-mini",
        type="generation",
        model="gpt-5-mini",
        provider="openai",
        input=[{"role": "user", "content": f"Plan a day trip to {city}"}],
    ) as generation:
        # A real app calls the model here. The fixed answer lets the sample run without a provider key.
        answer = "Take the scenic route."
        generation.update(
            output=[{"role": "assistant", "content": answer}],
            usage={"input_tokens": 11, "output_tokens": 7},
            finish_reason="stop",
        )
    return answer


print(plan_trip("Kyoto"))
telemetry_dev.shutdown()

shutdown() sends any pending data before the program exits. A long-running server doesn’t need it after each request; see Flush and shut down.

Run it

node quickstart.mts

python quickstart.py

The program prints Take the scenic route.

Open the trace

In the dashboard, open your project and select Traces. The new trace is at the top of the list, in the development environment. Select it to see its two spans:

The quickstart trace

1planTrip

trip-planner

0.51ms

chat gpt-5-mini

gpt-5-mini

0.13ms

Timings are from one run of the TypeScript sample and vary from run to run. In Python, the agent span and its Operation are both named plan_trip.

Select the chat gpt-5-mini span to read its input and output messages, its 11 input and 7 output tokens, and its cost. The cost appears because gpt-5-mini has a price in the pricing snapshot.

If the trace doesn’t appear

Check the key. Without TELEMETRY_DEV_API_KEY, init() returns a client that does nothing, and SDK calls don’t raise errors. Confirm the variable is set in the same shell that runs the sample.
Read the program’s output. Both SDKs print export failures. A key that telemetry.dev rejects shows trace ingest failed: 401 in TypeScript and code: 401 in Python.
Clear the trace filters. An Environment filter set to another environment hides the development trace.

Environment variables

Variable	Default	Purpose
`TELEMETRY_DEV_API_KEY`	None	Authenticates exports. Keys start with `td_live_`.
`TELEMETRY_DEV_ENVIRONMENT`	`production`	Sets `deployment.environment.name`.
`OTEL_SERVICE_NAME`	`unknown_service`	Sets `service.name`.
`TELEMETRY_DEV_BASE_URL`	`https://ingest.telemetry.dev`	Sends to a different ingest URL.

Trace your real model calls

Replace the hand-written span with an integration. It records model, tokens, input, and output from your existing client.

Vercel AI SDK

Trace generations, streams, agent loops, and tool calls.

OpenAI

Wrap the OpenAI SDK for TypeScript or Python.

Anthropic

Wrap the Anthropic SDK for TypeScript or Python.

All integrations

Providers, frameworks, coding agents, and OpenTelemetry.