Configuration

Glasstrace is configured through environment variables, programmatic options passed to registerGlasstrace(), and server-managed capture settings synced from the dashboard. This page covers all three.

Environment Variables

The SDK reads six environment variables from process.env. Set these in .env.local or your hosting provider’s environment configuration.

Name	Type	Default	Description
GLASSTRACE_API_KEY	string	undefined	Your API key. Omit for anonymous mode (gt_anon_xxx generated automatically). Set to a gt_dev_xxx key after creating an account.
GLASSTRACE_FORCE_ENABLE	string	undefined	Set to "true" to keep the SDK active in production-like environments. Overrides the production guard.
GLASSTRACE_ENV	string	undefined	Override the detected environment label attached to traces. Useful when NODE_ENV does not match your intended trace grouping.
GLASSTRACE_COVERAGE_MAP	string	undefined	Set to "true" to enable import graph capture for coverage map generation. Requires a paid tier (Free Trial or Pro).
NODE_ENV	string	undefined	Standard Node.js environment variable. When set to "production", the SDK disables itself unless GLASSTRACE_FORCE_ENABLE=true.
VERCEL_ENV	string	undefined	Set automatically by Vercel. When set to "production", the SDK disables itself unless GLASSTRACE_FORCE_ENABLE=true.

Example .env.local

# Anonymous mode (no key needed)
# GLASSTRACE_API_KEY=

# After creating an account
GLASSTRACE_API_KEY=<your-api-key>

# Enable import graph capture (paid tier)
GLASSTRACE_COVERAGE_MAP=true

GlasstraceOptions

Pass options directly to registerGlasstrace() in your instrumentation.ts file. These override environment variables where applicable.

Name	Type	Default	Description
apiKey	string	undefined	API key. Overrides GLASSTRACE_API_KEY env var.
endpoint	string (URL)	undefined	Custom ingestion endpoint URL. For self-hosted or testing scenarios.
forceEnable	boolean	undefined	Override the production guard. Equivalent to GLASSTRACE_FORCE_ENABLE=true.
verbose	boolean	undefined	Enable verbose logging. Prints SDK lifecycle events, config resolution, and exporter activity to the console.

Example

instrumentation.ts

import { registerGlasstrace } from "@glasstrace/sdk";

registerGlasstrace({
  apiKey: "<your-api-key>",
  verbose: true,
});

Environment variables take effect without any code changes. Use GlasstraceOptions when you need per-environment overrides or want to keep configuration in code.

CaptureConfig

Capture settings are managed in the Glasstrace dashboard and synced to the SDK via the /v1/sdk/init call on startup. You do not set these in code or environment variables.

Name	Type	Default	Description
requestBodies	boolean	false	Capture request and response bodies. May contain PII.
queryParamValues	boolean	false	Capture query parameter values (not just names). May contain user data.
envVarValues	boolean	false	Capture environment variable values referenced in errors (not just names). May contain secrets.
fullConsoleOutput	boolean	false	Capture all console output (log, warn, info) in addition to errors.
importGraph	boolean	false	Capture file import relationships for coverage map generation. File paths only, no code content. Requires GLASSTRACE_COVERAGE_MAP=true and a paid tier.
consoleErrors	boolean	false	Capture error-level console output. Filtered and truncated to 500 characters. Sensitive patterns (JWT tokens, API keys, connection strings) are stripped.

Default posture: moderate

Out of the box, the SDK captures route URLs, methods, status codes, durations, error messages, stack traces, ORM query structure (model and operation, not parameter values), and environment variable names referenced in errors. It does not capture request bodies, query parameter values, environment variable values, or full console output.

This moderate posture is designed for solo development debugging on localhost. When you enable an opt-in setting in the dashboard, a warning explains what additional data will be captured.

Anonymous Mode

No API key is needed to start using Glasstrace. On first run without GLASSTRACE_API_KEY, the SDK generates a gt_anon_xxx key automatically and persists it to .glasstrace/anon_key. This key is stable across restarts.

What you get in anonymous mode:

• Traces captured and stored with a 48-hour TTL
• MCP tools (get_latest_error, get_trace, get_session_timeline) return trace data
• Rate limit: 100 traces per minute, 1 concurrent session

What anonymous mode does not include:

• LLM-powered enrichment (get_root_cause returns raw trace data only)
• Coverage map in get_test_suggestions (test ideas from patterns still work)
• Source map upload (stack traces show compiled code)
• Dashboard access
• Storage beyond 48 hours

Upgrade path

1. Sign up at glasstrace.dev (email and password, credit card required for 30-day free trial)
2. Initiate the claim from the dashboard — existing anonymous traces from the same machine are linked to your new account
3. Your gt_dev_xxx key is revealed after the link succeeds
4. Set GLASSTRACE_API_KEY in your .env.local:

GLASSTRACE_API_KEY=<your-dev-api-key>

Existing anonymous traces are linked via the claim flow. A 30-day grace period allows straggler traces (in-flight when you switch keys) to be attributed to your account. After 30 days, the old gt_anon_xxx key stops working.

See Auth & Keys for the full claim flow and key management documentation.

Production Guard

Glasstrace is a development tool. The SDK disables itself in production environments to prevent capturing end-user data.

Detection logic

The SDK checks the following conditions in order:

1. If GlasstraceOptions.forceEnable === true or GLASSTRACE_FORCE_ENABLE === "true" — SDK stays active (all other checks skipped)
2. If NODE_ENV === "production" — SDK disables with a warning
3. If VERCEL_ENV === "production" — SDK disables with a warning
4. Otherwise — SDK stays active

What happens when disabled

When the production guard triggers, the SDK returns a no-op from registerGlasstrace(). No OpenTelemetry setup, no init call, no spans, no network traffic, no errors. Your application runs as if the SDK is not installed.

Overriding the guard

Set GLASSTRACE_FORCE_ENABLE=true to keep the SDK active in production-like environments. This is intended for staging environments that mirror production configuration, not for actual production use.

# .env.local (staging only)
GLASSTRACE_FORCE_ENABLE=true

Cached Config

The SDK caches configuration from the /v1/sdk/init response to .glasstrace/config. This ensures your server starts instantly even if the Glasstrace backend is unreachable.

Fallback chain

Configuration resolves in this order:

1. In-memory config from the latest init response (freshest)
2. File cache at .glasstrace/config (survives restarts, sub-millisecond load)
3. Moderate defaults from the SDK (safe settings — no request bodies, no query values, no env values)

Cache staleness

The cached config includes a cachedAt timestamp. If the cache is older than 24 hours, the SDK logs a verbose warning but still uses the cached values. The async init call refreshes the cache in the background.

Clearing the cache

Delete the cache file to force a fresh init:

rm .glasstrace/config

The SDK re-fetches configuration on the next startup. If the backend is unreachable, moderate defaults apply.

Advanced

Custom OTel span processors

Glasstrace uses a custom SpanExporter that enriches spans with glasstrace.* attributes before forwarding to the OTLP exporter. If you need additional span processing, register your span processors through the standard OpenTelemetry API. The Glasstrace exporter operates at the export layer and does not interfere with processors in the span processing chain.

Disabling specific instrumentations

The SDK auto-instruments Next.js API routes, Prisma/Drizzle ORM queries, and outbound fetch calls. To disable a specific instrumentation, configure it through the standard @opentelemetry/api configuration before calling registerGlasstrace().

Verbose logging

Enable verbose mode to see SDK lifecycle events in the console:

registerGlasstrace({ verbose: true });

Verbose output includes:

• Environment detection results
• API key resolution (anonymous vs. dev key)
• Init call timing and response status
• Config cache read/write events
• Exporter flush activity

Error responses

When the SDK encounters errors during initialization, it fails silently to avoid disrupting your application. The SDK may log warnings for certain failure paths (such as init auth failures or file write issues) even without verbose mode. Common error scenarios:

Invalid API key:

{
  "code": "invalid_key",
  "message": "The provided API key is not recognized. Check GLASSTRACE_API_KEY in your .env.local.",
  "retryable": false,
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Rate limited:

{
  "code": "rate_limited",
  "message": "Trace rate limit exceeded for your tier. Traces will be dropped until the rate window resets.",
  "retryable": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440001"
}

Rate limit responses include additional metadata:

{
  "retryAfterMs": 60000,
  "currentRate": 105,
  "tierLimit": 100,
  "upgradeUrl": "https://glasstrace.dev/pricing"
}

Expired anonymous key (after 30-day grace period):

{
  "code": "subscription_expired",
  "message": "This anonymous key has been claimed and the grace period has ended. Set GLASSTRACE_API_KEY to your gt_dev_xxx key.",
  "retryable": false,
  "requestId": "550e8400-e29b-41d4-a716-446655440002"
}

The SDK handles these responses internally. In all error cases, your application continues to run normally. No exceptions are thrown.