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

# Connect Better Stack

> Connect Better Stack so Glassray pulls your OpenTelemetry spans on a sync cadence.

Glassray connects to Better Stack as a **pull** integration: you provide SQL API credentials, the cluster endpoint, and the source table, and Glassray fetches new traces on a sync cadence. Better Stack stores its telemetry in ClickHouse, so Glassray reads your spans back out over the **SQL API** (Better Stack's *Connect remotely* interface). It's one of five [trace integrations](/docs/traces) - the others are [Langfuse](/docs/langfuse), [LangSmith](/docs/langsmith), [PostHog](/docs/posthog), and [OpenTelemetry](/docs/otlp-ingestion).

## Prerequisite

Your app must already be sending traces to a Better Stack **OpenTelemetry (spans)** source. If you export via the [`@langfuse/otel`](https://langfuse.com/docs/observability/sdk/typescript/setup) SDK or any OpenTelemetry exporter, point it at your Better Stack source's ingesting host (`https://<host>/v1/traces`, `Authorization: Bearer <source-token>`). You can confirm spans are arriving in Better Stack under **Live tail**.

## Connect

<Steps>
  <Step title="Create SQL API credentials" icon="key">
    In Better Stack, go to **Telemetry → Integrations → Connect remotely** (the **SQL API** tab) and create a connection. Better Stack shows a **username**, a **password** (once - copy it now), and a **Host**. Copy all three.
  </Step>

  <Step title="Note your cluster endpoint" icon="server">
    The **Host** is your region's cluster endpoint, e.g. `https://eu-central-1a-connect.betterstackdata.com`. Better Stack credentials are **region-scoped**, so this must be the cluster your source lives on - not the ingesting host you push to. In Glassray, pick it from the dropdown, or choose **Other cluster (paste URL)** and paste it.
  </Step>

  <Step title="Find your source table" icon="table">
    On the same page, the example query references your source's tables like `t123456_my_app_spans`. Glassray needs the **base** - the part **before** `_spans` (e.g. `t123456_my_app`). Enter it as the **source table**.
  </Step>

  <Step title="Connect in Glassray" icon="plug">
    In the dashboard, go to **Settings → Sources**, add **Better Stack**, and paste the **username**, **password**, **cluster endpoint**, and **source table**. Click **Test connection**, then **Save credentials**.
  </Step>

  <Step title="Glassray verifies and syncs" icon="circle-check">
    Glassray runs a live query to verify the credentials and table, then starts pulling new traces on a cadence. Spans are grouped into traces by their trace id and render in the [trace viewer](/docs/traces).
  </Step>
</Steps>

<Info>
  Your Better Stack SQL API credentials are stored in **WorkOS Vault**, never in Glassray's database. The connected source row only holds the source table, the cluster host, and a reference to the vaulted secret.
</Info>

<Warning>
  The cluster endpoint and source token you pasted are **region-scoped** - using a different region's cluster returns a `CLUSTER_DOESN'T_EXIST` / authentication error. If **Test connection** fails, double-check the cluster matches your source's data region and that the source table has no trailing `_spans`.
</Warning>

## Filtering

A source can carry an optional **filter** so only the traces you care about are pulled - narrow by trace name, trace ID, or a per-customer attribute. Filtering is applied at ingest, and changes are go-forward (re-sync to apply a new filter). See [Traces](/docs/traces).

<Tip>
  Prefer to push instead of pull? Point your OpenTelemetry exporter at Glassray directly with [OpenTelemetry](/docs/otlp-ingestion) - no SQL round-trip. Once traces land, head to [Flows](/docs/flows) or [Ask Glassray](/docs/ask-glassray).
</Tip>