> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data-source connectors

> Connect OpenLIT to ClickHouse and OpenPlait-backed observability backends — atomic connectors, signal bindings, and portable query adapters

**Data-source connectors** attach OpenLIT to observability backends for reading traces, logs, and metrics. Each connector is atomic: one Tempo instance, one Loki instance, one Prometheus endpoint.

Configure them from **Configuration → Connectors** (`/connectors`) or manage bindings from **Organisation → Project → Connectors**. Select the correct [project](/latest/openlit/organisation/projects) and [environment](/latest/openlit/organisation/environments) before adding or binding connectors.

<Info>
  Several read paths use portable [@openplait](https://github.com/openlit/openplait) adapters so query behavior stays consistent across backends. See the [Connectors overview](/latest/openlit/connectors/overview) for memory connectors and shared registry concepts.
</Info>

## Mental model

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  subgraph org [Organisation]
    proj[Project]
  end
  subgraph env [Environment]
    bindT[traces binding]
    bindL[logs binding]
    bindM[metrics binding]
  end
  proj --> env
  bindT --> C1[Connector A]
  bindL --> C2[Connector B]
  bindM --> C3[Connector C]
  C1 --> Tempo[Tempo]
  C2 --> Loki[Loki]
  C3 --> Prom[Prometheus]
```

* **Atomic connectors** — never a multi-backend blob. One Tempo instance, one Loki instance, one Prometheus endpoint.
* **Signal routing** — each of traces / logs / metrics is bound independently. See [Signal routing](/latest/openlit/organisation/signal-routing).
* **Database Config** — ClickHouse lives as a Database Config and appears as the built-in connector. See [Database Config](/latest/openlit/organisation/database-config).

## Supported connectors (OpenLIT + OpenPlait)

These are the data-source connectors available in open-source OpenLIT. OpenPlait packages power the portable query adapters for ClickHouse, Tempo, Loki, Prometheus, and Jaeger.

### Built-in app store

| Connector      | Package / implementation                          | Signals                                | What it's for                                                   |
| -------------- | ------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
| **ClickHouse** | Database Config + `@openplait/adapter-clickhouse` | traces, logs, metrics (+ intelligence) | Default store; full correlation, raw SQL, evals metadata, vault |

### External data-source connectors

| Connector         | Package / implementation        | Signals | What it's for                                                                                                     |
| ----------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| **Grafana Tempo** | `@openplait/adapter-tempo`      | traces  | TraceQL search, trace tree, span events                                                                           |
| **Grafana Loki**  | `@openplait/adapter-loki`       | logs    | LogQL logs; correlate by trace id / service                                                                       |
| **Prometheus**    | `@openplait/adapter-prometheus` | metrics | PromQL HTTP API (also works with Prometheus-compatible endpoints such as Mimir when you point at their query URL) |
| **Jaeger**        | `@openplait/adapter-jaeger`     | traces  | Jaeger Query HTTP API; sampled in-process aggregates                                                              |

<Tip>
  Prometheus-compatible APIs (for example Grafana Mimir's PromQL endpoint) use the **Prometheus** connector — there is no separate Mimir connector type in open-source OpenLIT.
</Tip>

## Capability matrix

| Connector  | Signals               | Trace tree | Span events | Server aggregation | Raw SQL | Cross-signal correlation |
| ---------- | --------------------- | ---------- | ----------- | ------------------ | ------- | ------------------------ |
| ClickHouse | traces, logs, metrics | Yes        | Yes         | Yes                | Yes     | Full                     |
| Tempo      | traces                | Yes        | Yes         | No\*               | No      | trace / span / service   |
| Loki       | logs                  | —          | —           | No                 | No      | trace id, service        |
| Prometheus | metrics               | —          | —           | Yes                | No      | —                        |
| Jaeger     | traces                | Yes        | Yes         | No\*               | No      | trace / span / service   |

\* Aggregate graphs are reconstructed in-process from a bounded sample of full traces when the backend cannot aggregate server-side.

## Add a Jaeger connector

<Frame>
  <img src="https://mintcdn.com/openlit/ARLdG9OdsIzgrIz7/images/organisation/openlit-jaeger-connector.png?fit=max&auto=format&n=ARLdG9OdsIzgrIz7&q=85&s=10cf33a79ec0756cca6c6e7fd95b4b69" alt="Add source dialog with the connector type menu open, including Jaeger" width="1440" height="1100" data-path="images/organisation/openlit-jaeger-connector.png" />
</Frame>

<Steps>
  <Step title="Select project and environment">
    Use the header selectors to pick the [project](/latest/openlit/organisation/projects) and [environment](/latest/openlit/organisation/environments).
  </Step>

  <Step title="Open Connectors">
    Go to **Configuration → Connectors** and choose **Add connector** / **Add source**.
  </Step>

  <Step title="Pick Jaeger">
    Select **Jaeger** from the data-source connector list.
  </Step>

  <Step title="Configure endpoint">
    Set the Query URL (local all-in-one: `http://localhost:16686`) and auth if needed.
  </Step>

  <Step title="Bind traces">
    Bind **traces** to the connector under [signal routing](/latest/openlit/organisation/signal-routing).
  </Step>
</Steps>

<Tip>
  Local demo credentials for seeded installs: email `user@openlit.io`, password `openlituser`. Jaeger all-in-one + seed script live in the OpenPlait `adapter-jaeger` integration folder.
</Tip>

## Actions you can take on a connector

The connector registry is designed so **actions** attach to a connector type. Today's data-source actions:

| Action                             | When to use it                                                             |
| ---------------------------------- | -------------------------------------------------------------------------- |
| **Add / edit connector**           | Point OpenLIT at a new endpoint or rotate settings                         |
| **Store credentials in Vault**     | API keys and tokens stay encrypted; decrypted only server-side             |
| **Health check / test connection** | Confirm the endpoint is reachable with current auth                        |
| **Validate AI signal**             | Confirm recent AI telemetry exists (`gen_ai.*` / OpenLIT markers)          |
| **Bind signal**                    | Route traces, logs, or metrics to this connector for an environment        |
| **Unbind / rebind**                | Move a signal to another connector without deleting history in the backend |
| **Mark Database Config active**    | Choose which ClickHouse app store the UI uses                              |
| **Share Database Config**          | Grant edit / delete / re-share on a ClickHouse connection                  |

Enterprise audit logs record connector create/update/delete/test plus bind/unbind (with signal, environment, and previous source when switching).

## How OpenLIT finds AI telemetry

Backends hold all telemetry — not only AI. OpenLIT applies a layered **AI selector** so reads stay focused:

* Resource `telemetry.sdk.name = openlit`
* Resource `telemetry.distro.name = openlit-cli`
* Any `gen_ai.*` attribute
* `coding_agent.session.id`, or Claude Code session markers
* Known `coding_agent.*` span names

## Authentication cheat sheet

| Backend                                            | Typical auth                                                                                                      |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Grafana Cloud** (Tempo / Loki)                   | Basic: instance ID + access policy token (`traces:read` / `logs:read`). Use **query** URLs from the Cloud Portal. |
| **Self-hosted Tempo / Loki / Prometheus / Jaeger** | None, Basic, or Bearer; optional tenant / `X-Scope-OrgID`                                                         |
| **ClickHouse**                                     | Username / password on the Database Config                                                                        |

## Security and reliability

* Endpoints validated (`http`/`https` only); credentials in URLs rejected; private/metadata SSRF targets blocked where applicable.
* Secrets live in Vault, redacted from errors, never logged.
* Per-source concurrency caps, query budgets, short-lived cache + in-flight de-dupe, and backoff on transient `429`/`5xx`.

## OpenPlait packages

OpenLIT wraps these npm packages for portable reads:

| npm package                     | Used for                        |
| ------------------------------- | ------------------------------- |
| `@openplait/core`               | Query IR and normalized results |
| `@openplait/adapter-sdk`        | Adapter contracts               |
| `@openplait/adapter-clickhouse` | ClickHouse / OTel               |
| `@openplait/adapter-tempo`      | Tempo / TraceQL                 |
| `@openplait/adapter-loki`       | Loki / LogQL                    |
| `@openplait/adapter-prometheus` | Prometheus / PromQL             |
| `@openplait/adapter-jaeger`     | Jaeger Query HTTP API           |
| `@openplait/runtime`            | Planning and execution helpers  |

See the [OpenPlait repository](https://github.com/openlit/openplait) for publishing and adapter docs.

## Related

<CardGroup cols={2}>
  <Card title="Memory connectors" href="/latest/openlit/connectors/memory" icon="brain">
    Claude, Mem0, and Zep for agent memory.
  </Card>

  <Card title="Signal routing" href="/latest/openlit/organisation/signal-routing" icon="route">
    Bind traces, logs, and metrics independently.
  </Card>

  <Card title="Database Config" href="/latest/openlit/organisation/database-config" icon="database">
    Env vars → ClickHouse Database Config.
  </Card>

  <Card title="Connectors overview" href="/latest/openlit/connectors/overview" icon="plug">
    Shared connector model and project scope.
  </Card>
</CardGroup>