Send your first trace

You need a verified email address and an application that already calls an LLM. Metergraph wraps the OpenAI, Anthropic and Google Gemini clients, synchronous and asynchronous, streaming and not. Start with the client your application already uses.

If you would rather hand this to a coding agent, the same work is written up as a prompt in instrument a repository.

1. Create your workspace

   Go to app.metergraph.dev and sign up. Verifying your email is the whole process. A free workspace is created on first sign-in and you are its owner. There is nothing to name and nothing to configure.

2. Mint an ingest key

   Signup drops you on Get started. Create a key there and copy it immediately: the plaintext value is returned exactly once, and only a hash and a short hint are kept afterwards. A key is mg_ followed by 48 hex characters, and carries the ingest scope and nothing else. It cannot read your traces back. Owners and members can mint keys; viewers cannot.

3. Install the SDK and export the token

   Neither package has runtime dependencies. The provider SDKs are optional peer dependencies, so Metergraph wraps whichever ones you already installed.

   Python

   pip install metergraph
   export METERGRAPH_APP_TOKEN=mg_...

   TypeScript

   npm install metergraph
   export METERGRAPH_APP_TOKEN=mg_...

   You do not need to set METERGRAPH_INGEST_URL. Left unset, the SDK points at the hosted service on its own. Set it only when you are running Metergraph yourself.

   Optional: identify the repository

   Capture and analysis both work without this. Adding it lets Metergraph associate traces and recommendations with the right codebase, and is the precondition for letting MetergraphBot prepare a pull request later. It grants no access to your repository. Any one of these is sufficient:

   • pass repository="owner/repository" to init();
   • set METERGRAPH_REPOSITORY=owner/repository; or
   • commit .metergraph/config.json containing {"repository":"owner/repository"}.

   The SDK reads that file but never creates or changes it. With none of the three set, the SDK logs one warning and continues.

4. Wrap the client you already have

   One line per client, at construction.

   Python

   app/llm.py

   import metergraph
   from openai import OpenAI
   
   client = metergraph.wrap(OpenAI())
   
   # then use it exactly as before
   client.chat.completions.create(model="gpt-5.6-luna", messages=[...])

   TypeScript

   src/llm.ts

   import * as mg from "metergraph";
   import OpenAI from "openai";
   
   const client = mg.wrap(new OpenAI());
   
   // then use it exactly as before
   await client.chat.completions.create({ model: "gpt-5.6-luna", messages: [...] });

   wrap() calls init() for you and returns the same client object, so assign the return value. Call sites, arguments, types, streaming and async all keep working untouched. Anthropic, Gemini, gateways and the Vercel AI SDK each have their own page under Instrument.

   Caution

   Wrapping and throwing the result away captures nothing. metergraph.wrap(OpenAI()) on a line of its own is the second most common reason people see no data.

5. Make a call and confirm it landed

   Run your application normally and make one instrumented call. Within a few seconds, Get started shows a first-trace card naming the trace, the model, the token count and the cost. From there, Traces shows the call itself and Spend shows it in the totals.

   Capture is asynchronous and batched, so a process that exits immediately can take its queue with it. In a script, a job, or a serverless handler, flush first.

   Python

   metergraph.flush()      # process stays alive, runtime may freeze
   metergraph.shutdown()   # process is exiting

   TypeScript

   await mg.flush();       // process stays alive, runtime may freeze
   await mg.shutdown();    // process is exiting

   In Python, shutdown() is registered with atexit for you. See serverless and short-lived jobs for the platform-specific hooks.

What it costs to keep it running

A new workspace is on the free plan, which captures 100,000 calls per month. When that allowance is spent, POST /v1/ingest answers 402 with quota_exceeded and the dashboard shows a banner. Nothing about your application changes: the SDK drops the batch, logs, and keeps serving your users. Traffic already captured stays queryable, and metadata is retained for 90 days.

The limits and allowances page has the rest of the numbers, and pricing has what happens when you need more.

Next

Name a route Your first trace arrived under a generated fingerprint. Give it a name and watch the dashboard change.

Nothing showed up The ordered checklist, starting with the two causes that account for most cases.