Traces

Traces are the fundamental unit of observability in Glassbrain. Every error, warning, and informational event captured from your application becomes a trace - a structured record that Glassbrain stores, visualizes, and uses to generate AI-powered fix suggestions.

What Is a Trace

A trace in Glassbrain represents a single captured event from your application. Unlike traditional logging where events are flat text strings, a Glassbrain trace is a richly structured object that includes the error message, full stack trace, browser and OS metadata, the URL where the event occurred, and more.

Each trace is associated with a project and assigned a unique identifier. Once ingested, a trace becomes available in your dashboard where you can inspect it, replay it, and request AI fix suggestions.

Traces are designed to give you complete context about what happened in your application at a specific moment - not just what went wrong, but the full environment surrounding the event.

Trace Structure

Every trace follows a consistent schema. Here is an example of a complete trace object as returned by the Glassbrain API:

jsonexample-trace.json

{
  "id": "trc_a1b2c3d4e5f6",
  "project_id": "prj_x7y8z9w0",
  "type": "error",
  "message": "Cannot read properties of undefined (reading 'map')",
  "stack_trace": "TypeError: Cannot read properties of undefined (reading 'map')\n    at UserList (/app/components/UserList.tsx:14:22)\n    at renderWithHooks (/app/node_modules/react-dom/cjs/react-dom.development.js:14985:18)",
  "metadata": {
    "component": "UserList",
    "props": { "users": null },
    "react_version": "18.2.0"
  },
  "source": "client",
  "browser": "Chrome 120.0.6099.109",
  "os": "macOS 14.2.1",
  "url": "https://myapp.com/dashboard/users",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.109 Safari/537.36",
  "created_at": "2026-04-03T10:23:45.123Z"
}

Field Reference

Field	Type	Description
id	string	Unique trace identifier, prefixed with `trc_`
project_id	string	The project this trace belongs to, prefixed with `prj_`
type	string	One of `error`, `warning`, or `info`
message	string	Human-readable description of the event
stack_trace	string \| null	Full stack trace if available. Typically present for error-type traces
metadata	object \| null	Arbitrary JSON object for custom context. You control what goes here
source	string	Where the trace originated - typically `client` or `server`
browser	string \| null	Detected browser name and version
os	string \| null	Detected operating system and version
url	string \| null	The URL where the event occurred
user_agent	string \| null	Raw user agent string from the client
created_at	string	ISO 8601 timestamp of when the trace was captured

How Traces Are Captured

Glassbrain supports two methods for capturing traces: automatic capture through the SDK and manual capture through the API.

Auto-Capture

When you install the Glassbrain SDK and initialize it with your project API key, it automatically captures unhandled errors, uncaught promise rejections, and console warnings from your application. The SDK handles extracting the stack trace, browser metadata, URL, and user agent automatically.

typescriptapp/layout.tsx

400 font-semibold">import { GlassbrainSDK } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"@glassbrain/sdk";

400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Initialize once at the entry point 400 font-semibold">of your application
GlassbrainSDK.init({
  apiKey: process.env.NEXT_PUBLIC_GLASSBRAIN_API_KEY!,
  projectId: 400 font-semibold">class="text-emerald-400">"prj_x7y8z9w0",
  autoCapture: 400">true, 400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Captures unhandled errors automatically
  captureConsoleWarnings: 400">true, 400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Also capture console.warn calls
});

With auto-capture enabled, you do not need to write any additional instrumentation code. Every unhandled error and warning is captured, enriched with metadata, and sent to the Glassbrain API.

Manual Capture

For cases where you want to capture specific events - handled errors, informational events, or custom warnings - you can use the SDK or the API directly.

typescriptcapture-example.ts

400 font-semibold">import { GlassbrainSDK } 400 font-semibold">from 400 font-semibold">class="text-emerald-400">"@glassbrain/sdk";

400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Capture a handled error with custom metadata
400 font-semibold">try {
  400 font-semibold">const response = 400 font-semibold">await fetch(400 font-semibold">class="text-emerald-400">"/api/users");
  400 font-semibold">if (!response.ok) {
    400 font-semibold">throw 400 font-semibold">new Error(400 font-semibold">class="text-emerald-400">"Failed to fetch users: " + response.status);
  }
} 400 font-semibold">catch (error) {
  GlassbrainSDK.captureError(error, {
    metadata: {
      endpoint: 400 font-semibold">class="text-emerald-400">"/api/users",
      statusCode: 500,
      retryCount: 3,
    },
  });
}

400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Capture an informational event
GlassbrainSDK.captureInfo(400 font-semibold">class="text-emerald-400">"User completed onboarding flow", {
  metadata: {
    userId: 400 font-semibold">class="text-emerald-400">"usr_123",
    steps_completed: 5,
    duration_ms: 45000,
  },
});

400 font-semibold">class="text-[rgba(255,255,255,0.3)] italic">// Capture a warning
GlassbrainSDK.captureWarning(400 font-semibold">class="text-emerald-400">"API response time exceeded 2s threshold", {
  metadata: {
    endpoint: 400 font-semibold">class="text-emerald-400">"/api/search",
    response_time_ms: 2340,
  },
});

You can also send traces directly via the REST API using POST /api/v1/traces. See the API Reference for details.

Trace Types

Every trace has a type that indicates its severity. Glassbrain uses three trace types:

Error

Errors represent failures that disrupt normal application behavior. These include unhandled exceptions, runtime type errors, network failures, and any event that prevents a feature from working correctly. Error traces always include a stack trace when available and are prioritized in the dashboard.

Warning

Warnings indicate potential problems that have not yet caused a failure. These include deprecated API usage, slow response times, approaching rate limits, and other conditions that could become errors if left unaddressed. Warnings help you catch issues before they affect users.

Info

Informational traces record notable events that are not problems. These include completed user flows, successful deployments, feature flag changes, and other milestones you want to track. Info traces provide context that helps you understand the overall state of your application.

Trace Lifecycle

A trace moves through five stages from the moment it is captured to when you act on it:

Capture

The Glassbrain SDK or your custom integration detects an event in your application and constructs a trace object with all available context - the error message, stack trace, browser metadata, URL, and any custom metadata you attach.

Ingest

The trace is sent to the Glassbrain API via POST /api/v1/traces. The API validates the payload, authenticates the request using your API key, and checks your plan's rate limits.

Store

After validation, the trace is persisted in Glassbrain's data store. It is indexed by project, type, timestamp, and message for fast retrieval. The trace is now available through the API and the dashboard.

Visualize

The trace appears in your project dashboard where you can inspect its details, view the stack trace, and explore it in the Visual Trace Tree. Related traces are grouped together for pattern detection.

Suggest Fixes

For error-type traces, Glassbrain's AI engine analyzes the trace and generates AI fix suggestions with code diffs showing exactly what to change. You can review and apply these suggestions directly from the dashboard.