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

# Configuration reference

> Every @glassray/tracing constructor option and environment variable — precedence, defaults, and the kill switch.

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

<Note>
  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.
</Note>

## Options

| Constructor   | Env var                 | Default                   | What it does                                                                                                                                                                                    |
| ------------- | ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`      | `GLASSRAY_API_KEY`      | —                         | The write-only ingest key (`traces:write`) minted with your [OTLP source](/sdk-quickstart). 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](/sdk-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](/sdk-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](/projects), not an attribute. |
| `agent`       | —                       | —                         | [Metadata](/sdk-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](/sdk-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:

```ts theme={null}
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:

```sh theme={null}
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](/sdk-reliability)):

```ts theme={null}
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 }
```