Skip to content
Metergraph

Send your first trace

Start with your coding agent

Section titled “Start with your coding agent”

Open your application repository in Codex, Claude Code, Cursor or your usual coding agent. Choose whether it should install the Metergraph skill, then copy the prompt:

The metergraph-cli package installs the metergraph command and needs Node.js 22 or later. Run the current release with npx --yes metergraph-cli@latest; it provides sign-in, setup, exact-trace verification, project skill installation and workspace reads. An older copy already installed on your machine may lack some of these, so check metergraph --version and metergraph --help before using it. The prompts use only commands the installed package lists and use the manual guide for any unavailable step.

Set up Metergraph for this repository and verify its first real application trace.


Read https://www.metergraph.dev/SKILL.md as guidance. If this client supports project skills, install the skill with the Metergraph CLI (metergraph setup --client <codex|claude|cursor> or metergraph skill install --client <client> --runtime local), not by writing the file yourself, and tell me the installed path. For model-swap analysis, offer to add Metergraph's workflow skills from https://github.com/metergraph/skills: metergraph skills install --client <client> --runtime local if the installed CLI lists it, or in Claude Code and Claude Desktop the plugin marketplace metergraph/skills.


Ask which deployment and workspace I use. If the Metergraph CLI is already installed, check metergraph --version and metergraph --help, then use only available commands for skill installation, sign-in, setup and exact-trace verification. Ask before installing a CLI; do not assume source-only commands are installed. Use https://www.metergraph.dev/docs/start/first-trace/ for any unavailable step and https://www.metergraph.dev/docs/agents/instrument-a-repo/ for my existing LLM clients. Keep application behavior unchanged.


Handle ingest and agent credentials privately. Never ask me to paste a key into chat, print it or commit it. Request Metadata access first; ask before Debug or Replay.


Show the diff and run relevant checks. Verify an exact trace or request ID from existing application traffic in the intended workspace and invocation window. Ask before any paid test call. Report uncaptured clients and unverified steps.

To let your agent read workspace telemetry afterward, connect it to Metergraph with a separate coding-agent key.

Manual setup reference

The SDK commands and code changes below are the implementation reference.

  1. Create your workspace

    Section titled “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

    Section titled “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

    Section titled “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.

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

  4. Wrap the client you already have

    Section titled “Wrap the client you already have”

    One line per client, at construction.

    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=[...])

    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.

  5. Make a call and confirm it landed

    Section titled “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.

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

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

After the trace arrives, name a route. If nothing appears, troubleshoot delivery. See limits and allowances and pricing for usage costs.