> ## Documentation Index
> Fetch the complete documentation index at: https://glassray.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK quickstart

> Install @glassray/tracing, wrap your agent, and see your first trace in Glassray - no OpenTelemetry setup required.

`@glassray/tracing` is Glassray's zero-dependency tracing SDK for TypeScript and JavaScript agents. If your agent isn't instrumented with anything yet, this is the fastest way in: install, set a key, wrap the entrypoint - every run lands as a full [trace](/traces).

<Tip>
  **Don't want to wire this up by hand?** These docs are written to be handed straight to a coding agent - copy this page's URL, paste it into Claude Code (or Cursor, Copilot, any agent with web/fetch access), and ask it to integrate Glassray tracing using the linked doc. It'll install the SDK, create the source, and wrap the entrypoint correctly on its own. For an agent that needs more than one page of context, point it at the [docs-search MCP server](/mcp-server#search-these-docs-over-mcp) instead of a single link. (Running Coach locally? `glassray-coach start` prints its own copy-paste setup prompt with your local key baked in - see the [Coach quickstart](/coach/quickstart).)
</Tip>

<Info>
  Already instrumented? You may not need the SDK - [connect Langfuse, LangSmith, or PostHog](/traces) as a pull source, or [point an existing OTel exporter at Glassray](/otlp-ingestion) (read [Bring your own OTel](/sdk-byo-otel) first).
</Info>

<Steps>
  <Step title="Install the SDK" icon="download">
    Zero runtime dependencies; Node 18+.

    ```sh theme={null}
    pnpm add @glassray/tracing
    ```
  </Step>

  <Step title="Create a source and copy the key" icon="key">
    In the dashboard, go to **Settings → Trace sources** and add an **OpenTelemetry** source. Glassray mints a write-scoped API key and shows it **once**, alongside a copy-ready SDK snippet with the key pre-filled.

    <Note>
      The key is **write-only** (`traces:write`) - code holding it can send traces but can never read data back.
    </Note>
  </Step>

  <Step title="Set the key" icon="terminal">
    ```sh theme={null}
    export GLASSRAY_API_KEY="sk_..."
    ```
  </Step>

  <Step title="Wrap your agent" icon="code">
    ```ts theme={null}
    import { Glassray } from "@glassray/tracing";

    const glassray = new Glassray();

    const result = await glassray.trace("handle-ticket", { customer: "acme-corp" }, async (t) => {
      const plan = await t.llm("plan", { model: "claude-opus-4-8", provider: "anthropic" }, () =>
        anthropic.messages.create(planRequest),
      );
      const docs = await t.tool("search-kb", () => searchKb(plan));
      return await t.llm("answer", { model: "claude-opus-4-8", provider: "anthropic" }, () =>
        anthropic.messages.create(answerRequest),
      );
    });
    ```

    The callback's return value becomes the trace's output. A throw is recorded as an error on the trace and it still sends - errored runs are the interesting ones.
  </Step>

  <Step title="See the trace" icon="circle-check">
    Run your agent, then open **Traces** in the dashboard. The run appears with its LLM calls, tool calls, inputs/outputs, timing, and token usage - and Glassray starts classifying it into [flows](/flows) and scanning for [deviations](/deviations), exactly as it does for pulled traces.
  </Step>
</Steps>

<Warning>
  On serverless runtimes (Vercel, AWS Lambda, Cloudflare) add one flush call so the platform doesn't freeze the process before the trace ships - see the [serverless matrix](/sdk-reliability#serverless).
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Instrumenting your agent" icon="code" href="/sdk-instrumenting">
    The three instrumentation modes, LLM/tool/span helpers, sessions, usage, and errors.
  </Card>

  <Card title="Metadata" icon="tags" href="/sdk-metadata">
    Attach customer, agent, and flow so every trace is filterable.
  </Card>

  <Card title="Configuration reference" icon="sliders" href="/sdk-configuration">
    Every constructor option and environment variable, in one table.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sdk-troubleshooting">
    The "no traces appearing" checklist.
  </Card>
</CardGroup>