SDK quickstart

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

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

Already instrumented? You may not need the SDK - connect Langfuse, LangSmith, or PostHog as a pull source, or point an existing OTel exporter at Glassray (read Bring your own OTel first).

Install the SDK

Zero runtime dependencies; Node 18+.

pnpm add @glassray/tracing

Create a source and copy the 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.

The key is write-only (traces:write) - code holding it can send traces but can never read data back.

Set the key

export GLASSRAY_API_KEY="sk_..."

Wrap your agent

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.

See the trace

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 and scanning for deviations, exactly as it does for pulled traces.

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.

Next steps

Instrumenting your agent

The three instrumentation modes, LLM/tool/span helpers, sessions, usage, and errors.

Metadata

Attach customer, agent, and flow so every trace is filterable.

Configuration reference

Every constructor option and environment variable, in one table.

Troubleshooting

The “no traces appearing” checklist.

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

Next steps

Instrumenting your agent

Metadata

Configuration reference

Troubleshooting

​Next steps

Instrumenting your agent

Metadata

Configuration reference

Troubleshooting

Next steps