Grafana

1. Create a Grafana Reader key

In your workspace's API keys, create a dedicated key with the Reader role. It can query metrics, logs, and traces without ingestion or administration permissions. Save the one-time value in your secret manager. Keep the collector's Writer key separate.

2. Settings

Use the query URL shown in Settings → Connect. Replace <QUERY_URL> in the provisioning file with that URL. These settings apply whichever setup method you choose.

Grafana-managed alert rules can query this connection. Leave both Prometheus alerting options off.

Apply with provisioning

Supply the saved Reader key as the Grafana server environment variable PACKDB_GRAFANA_READER_API_KEYthrough your deployment's secret store. Place this file in Grafana's datasource provisioning directory. Grafana resolves the variable at startup; keep the credential out of the YAML and version control.

apiVersion: 1

datasources:
  - name: PackDB Metrics
    type: prometheus
    access: proxy
    uid: packdb
    url: <QUERY_URL>
    isDefault: true
    editable: true
    jsonData:
      httpMethod: POST
      httpHeaderName1: X-API-Key
      httpHeaderName2: X-PackDB-Grafana-Query
      timeInterval: 10s
      queryTimeout: 60s
      manageAlerts: false
      allowAsRecordingRulesTarget: false
      tlsSkipVerify: false
    secureJsonData:
      httpHeaderValue1: "${PACKDB_GRAFANA_READER_API_KEY}"
      httpHeaderValue2: "true"

  - name: PackDB Logs
    type: loki
    access: proxy
    uid: packdb-loki
    url: <QUERY_URL>
    editable: true
    jsonData:
      httpHeaderName1: X-API-Key
      httpHeaderName2: X-PackDB-Grafana-Query
      timeout: 60
      tlsSkipVerify: false
    secureJsonData:
      httpHeaderValue1: "${PACKDB_GRAFANA_READER_API_KEY}"
      httpHeaderValue2: "true"

  - name: PackDB Traces
    type: tempo
    access: proxy
    uid: packdb-tempo
    url: <QUERY_URL>
    editable: true
    jsonData:
      serviceMap:
        datasourceUid: packdb
      streamingEnabled:
        search: false
        metrics: false
      httpHeaderName1: X-API-Key
      httpHeaderName2: X-PackDB-Grafana-Query
      tlsSkipVerify: false
    secureJsonData:
      httpHeaderValue1: "${PACKDB_GRAFANA_READER_API_KEY}"
      httpHeaderValue2: "true"

  - name: PackDB Jaeger
    type: jaeger
    access: proxy
    uid: packdb-jaeger
    url: <QUERY_URL>/jaeger
    editable: true
    jsonData:
      httpHeaderName1: X-API-Key
      httpHeaderName2: X-PackDB-Grafana-Query
      tlsSkipVerify: false
    secureJsonData:
      httpHeaderValue1: "${PACKDB_GRAFANA_READER_API_KEY}"
      httpHeaderValue2: "true"

Apply in the Grafana UI

Open Connections → Data sources → Add new data source and create an entry for each datasource you need from the table. Select No Authenticationin the authentication-method dropdown, then enter the table's headers under Authentication → HTTP headers using the protected Value fields. The API-key header provides authentication. For Tempo's service graph, select the actual metrics datasource entry; the UI assigns its UID for you.

Select Save & test for each entry. Saved secret fields show “configured”; they do not reveal the credential.

Grafana Cloud

Grafana Cloud needs a reachable HTTPS query endpoint or an explicitly configured private connection. An address available only inside your container network will not be reachable from Cloud.

PackDB derives workspace scope from the API key, so normally omit X-Scope-OrgID. If Cloud's Loki datasource reports claim_header_mismatch, add that HTTP header with the same organization ID shown on your PackDB API keys page, not the Grafana stack ID. The matching header preserves the key's existing scope.

When provisioning by file, merge this additional header slot into the affected datasource. Keep its existing headers and other settings in both mappings, and replace the placeholder with that organization ID.

jsonData:
  httpHeaderName3: X-Scope-OrgID
secureJsonData:
  httpHeaderValue3: "<WORKSPACE_ORGANIZATION_ID>"

3. Verify the read workflows in Explore

Choose a time range containing known telemetry. Save & test checks connectivity; also verify discovery and actual results for each signal. An empty result alone does not prove the setup works.

1. Prometheus: use Metrics browser to discover a metric, labels, and label values. Run a selector for a known metric with query type Both to check instant and range results. For the Quickstart sample, use demo_metric{service_name="curl-demo"}. Test your dashboard's rate, aggregation, and histogram queries against the corresponding counters and buckets.
2. Loki: use Label browser to choose a service, then Show logs. Add a line filter matching a known log message. Check a metric query such as sum(count_over_time({service_name="YOUR_SERVICE"}[5m])) and confirm the graph contains samples.
3. Tempo: use Search to discover service/tag values and find traces, then run the equivalent TraceQL predicate, for example { resource.service.name = "YOUR_SERVICE" && duration > 1ms }. Open a returned trace ID and verify the span waterfall. Select Service Graph and confirm the service metrics and graph render through the configured Prometheus datasource. The graph needs traces that produce service relationships in the selected range.

This setup covers polling query workflows. Loki Live/WebSocket tailing and Loki-managed rule APIs are not supported. Tempo streaming and full TraceQL metrics pipelines are not supported. Tempo's Service Graph uses Prometheus metrics instead. Trace-to-logs, exemplars, and other cross-signal links need separate correlation configuration and are not enabled by this example.

To import an existing dashboard, go to Dashboards → New → Import, provide its JSON or grafana.com ID, and select the corresponding PackDB datasource. Verify the queries it uses against PackDB's supported query features. Use Query inspector to investigate errors and missing data before relying on the dashboard.