Skip to content
Glasstrace Glasstrace

Getting Started

Prerequisites

Section titled “Prerequisites”
  • Node.js 18 or later
  • A Next.js 14+ project (App Router or Pages Router)

Install the SDK

Section titled “Install the SDK”
Terminal window
npm install @glasstrace/sdk

Initialize your project

Section titled “Initialize your project”

Run the init command from your project root:

Terminal window
npx @glasstrace/sdk init

This creates:

  • instrumentation.ts — calls registerGlasstrace() to set up tracing
  • next.config.js wrapper — enables source map generation via withGlasstraceConfig()
  • .glasstrace/ directory — local cache for config and anonymous credentials

Capture your first trace

Section titled “Capture your first trace”

Start your dev server:

Terminal window
npm run dev

Make a request to any API route or page. Glasstrace logs a confirmation to your console:

Terminal window
[glasstrace] Trace captured: GET /api/hello (200) — 42ms

That trace is now stored and available to your AI agent. No dashboard login, no config files, no environment variables.

Connect your AI agent

Section titled “Connect your AI agent”

npx @glasstrace/sdk init detects installed AI agents (Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI) and writes their native MCP configuration files automatically. If your agent was running during init, restart it to pick up the new configuration.

If auto-detection missed your agent, or you want to add another one manually:

Terminal window
npx glasstrace mcp add

This walks you through selecting an agent and writes the correct MCP config file.

Debug your first error

Section titled “Debug your first error”

Trigger an error in your app — throw an exception in an API route, or make a request to a broken endpoint.

Your AI agent can now retrieve that error using the get_latest_error MCP tool. In your agent, ask it to check for recent errors. It calls:

// Conceptual — your agent handles this via its MCP integration
{
  "method": "tools/call",
  "params": {
    "name": "get_latest_error",
    "arguments": {}
  }
}

The response includes the full error trace with span tree:

{
  "success": true,
  "data": {
    "summary": {
      "traceId": "trc_abc123",
      "route": "GET /api/users/[id]",
      "statusCode": 500,
      "error": "Cannot read properties of undefined (reading 'id')",
      "duration": 12,
      "timestamp": "2026-04-08T12:00:00Z"
    },
    "spans": [
      {
        "name": "GET /api/users/[id]",
        "layer": "server",
        "duration": 12,
        "status": "ERROR",
        "error": "Cannot read properties of undefined (reading 'id')"
      }
    ]
  }
}

Your agent reads this trace, identifies the root cause, and suggests a fix — without you copying stack traces or switching to a browser.

What’s next

Section titled “What’s next”
  • SDK Reference — full API docs for registerGlasstrace() and withGlasstraceConfig()
  • Configuration — environment variables, capture settings, anonymous mode, production guard
  • MCP Server — all five debugging tools your agent can use