Connections

The UI never talks to a backend directly — cards depend on three narrow contracts, resolved through named connections in config/telemetry-ui.php:

'connections' => [
    'metrics' => [
        'driver' => 'mimir',
        'url' => env('TELEMETRY_UI_METRICS_URL'),
        'prefix' => null,          // defaults to "prometheus" for mimir
        'tenant' => 'team-apps',   // sent as X-Scope-OrgID
        'token' => env('TELEMETRY_UI_METRICS_TOKEN'),      // -> Authorization: Bearer
        'basic_auth' => null,      // "user:pass" -> Authorization: Basic
        'headers' => [],           // any other headers
        'timeout' => 10.0,
    ],
    'traces' => ['driver' => 'tempo', 'url' => env('TELEMETRY_UI_TEMPO_URL')],
    'logs' => ['driver' => 'loki', 'url' => env('TELEMETRY_UI_LOKI_URL')],
],

Authentication

Backends behind an authenticated gateway take a Bearer token or basic auth:

• token → Authorization: Bearer <token> (e.g. a Grafana service account). Env: TELEMETRY_UI_<CONN>_TOKEN, or a shared TELEMETRY_UI_TOKEN.
• basic_auth → Authorization: Basic <base64>; give it as user:pass. Env: TELEMETRY_UI_<CONN>_BASIC_AUTH.
• An explicit Authorization under headers always wins.

To query Tempo/Loki/Mimir through Grafana instead of hitting them directly, see Connect through a Grafana datasource proxy.

The keys metrics, traces and logs are the defaults. Additional named connections are allowed and requested explicitly:

'connections' => [
    // ...
    'metrics-eu' => ['driver' => 'prometheus', 'url' => 'http://prom-eu:9090'],
],

$this->metrics('metrics-eu')->queryRange(...);

Semantics

• Lazy — connections resolve on first use, never at boot.
• Tenancy — tenant sets X-Scope-OrgID, honoured by Mimir, Tempo and Loki alike.
• Mimir = Prometheus + prefix — the mimir driver is the Prometheus driver with a default /prometheus path prefix and tenancy.
• Errors — all drivers throw SourceException with the failing URL and upstream message; cards render it as an inline error state.

Verifying a connection

Before trusting the dashboard, confirm the config actually reaches every backend — a URL typo, a wrong token or a missing tenant otherwise only shows up as an empty or broken card:

php artisan telemetry-ui:check

Each configured connection is probed with its cheapest read (an instant vector(1) for metrics, a service.name tag lookup for traces, a label lookup for logs, a one-issue page for the tracker) and reported as OK / FAIL / not configured. It exits non-zero if any probe fails, so it doubles as a deploy healthcheck. Scope it with --connection=metrics (repeatable).

Result types

Drivers return plain readonly DTOs, so cards never touch raw JSON:

• Sample (instant vector element) and TimeSeries/DataPoint (range) with an ECharts-ready toChartData().
• TraceSummary (search hit) and Trace/Span (full OTLP trace with typed attributes, SpanKind, error status and parent/child helpers).
• LogEntry (line + stream labels + nanosecond timestamp).