Configuration reference

Configuration resolves in strict precedence: constructor option > environment variable > default. There is nothing you must configure beyond the API key.

Invalid configuration never throws. The SDK warns (once, rate-limited) and disables itself — fail-open extends to misconfiguration, so a bad env var can’t take your agent down.

Options

Constructor	Env var	Default	What it does
`apiKey`	`GLASSRAY_API_KEY`	—	The write-only ingest key (`traces:write`) minted with your OTLP source. Missing or invalid → warn once and disable sending; the agent runs unaffected.
`endpoint`	`GLASSRAY_ENDPOINT`	`https://app.glassray.ai`	Where traces go. Accepts an app origin or a full OTLP traces URL — if the value doesn’t end with `/v1/traces`, the SDK appends `/api/public/otel/v1/traces`. Override for self-hosted Glassray.
`enabled`	`GLASSRAY_TRACING`	`true`	The kill switch. `GLASSRAY_TRACING=false` (or `enabled: false`) disables all tracing — every handle becomes an inert no-op.
`sampleRate`	`GLASSRAY_SAMPLE_RATE`	`1`	`0`–`1`. The decision is made once at trace start, so a trace is always kept or dropped whole — never partially sampled.
`hideInputs`	`GLASSRAY_HIDE_INPUTS`	`false`	Replace all input content with `[hidden]`. Structure, names, timing, and tokens still flow. See Privacy.
`hideOutputs`	`GLASSRAY_HIDE_OUTPUTS`	`false`	Same, for output content.
`scrubbing`	—	`true`	Scrub secret-shaped keys (`password`, `api_key`, `token`, `authorization`, …) inside captured I/O. `scrubbing: false` turns it off.
`redact`	—	—	`(key, value) => value` hook over every content attribute. Fail-closed: if the hook throws, the value is withheld — never sent raw.
`customer`	—	—	Metadata default; usually set per trace instead.
`environment`	—	—	Deprecated, ignored since 0.1.3. Still accepted so existing code compiles, but setting it warns once and has no effect — the ingest key selects the project, not an attribute.
`agent`	—	—	Metadata default identifying which agent produced the trace.
`onWarn`	—	console	Callback receiving the SDK’s rate-limited warnings instead of the console.
—	`GLASSRAY_DEBUG`	`false`	Verbose diagnostics — queue activity, transport results, drop reasons. First stop when troubleshooting.

The zero-config path

With only GLASSRAY_API_KEY set, new Glassray() sends to the hosted endpoint with content capture on, scrubbing on, and full sampling:

import { Glassray } from "@glassray/tracing";

const glassray = new Glassray();

Endpoint override

Point the SDK at a self-hosted Glassray by setting the app origin — the SDK derives the traces path itself:

export GLASSRAY_ENDPOINT="https://glassray.internal.example.com"

A full OTLP traces URL (ending in /v1/traces) is used verbatim.

Lifecycle

Three methods manage the transport — you only need them on serverless (see Reliability & serverless):

await glassray.flush(); // drain the queue — awaitable, for serverless handoff
await glassray.shutdown(); // flush + stop; also wired best-effort to process exit
glassray.stats(); // { sent, dropped: { byReason }, queued }

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

Configuration reference

Options

The zero-config path

Endpoint override

Lifecycle

​Options

​The zero-config path

​Endpoint override

​Lifecycle

Options

The zero-config path

Endpoint override

Lifecycle