Using Uptrace and Grafana Together

Uptrace exposes Prometheus-compatible and Tempo-compatible HTTP endpoints so you can add it as a data source in Grafana and query telemetry stored by Uptrace directly from your existing Grafana dashboards and trace views.

When to use Grafana with Uptrace

Grafana integration makes sense when:

• You have existing PromQL dashboards you want to keep without migration effort
• Your team is already familiar with Grafana's visualization layer
• You need to correlate Uptrace traces alongside metrics from other data sources in a single Grafana view

For new dashboards without existing Grafana investment, Uptrace's built-in dashboard builder is faster to configure and does not require a separate Grafana installation.

Prometheus metrics

Ingesting metrics

To reuse an existing Grafana Prometheus dashboard with Uptrace, send metrics via Prometheus remote write — this preserves original metric and label names exactly. See Prometheus ingest.

If you ingest via OTLP instead, metric and label names are transformed (dots replaced with underscores, labels flattened) and you will need to update dashboard queries to match the new names.

Adding the Prometheus data source

1. In Grafana, go to Connections → Data sources.
2. Click Add new data source and select Prometheus.
3. Set the Prometheus server URL:
   • Cloud: https://api.uptrace.dev/api/prometheus/<project_id>
   • Self-hosted: http://localhost:14318/api/prometheus/<project_id>
4. Under HTTP Headers, click Add header:
   • Header: Authorization
   • Value: Bearer <your_token>
5. Click Save & Test.

Or configure via datasource.yml:

apiVersion: 1
datasources:
  - name: Uptrace Prometheus
    type: prometheus
    access: proxy
    url: https://api.uptrace.dev/api/prometheus/<project_id>
    editable: true
    jsonData:
      httpHeaderName1: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'Bearer <your_token>'

Tempo traces

Adding the Tempo data source

1. In Grafana, go to Connections → Data sources.
2. Click Add new data source and select Tempo.
3. Set the URL:
   • Cloud: https://api.uptrace.dev/api/tempo/<project_id>
   • Self-hosted: http://localhost:14318/api/tempo/<project_id>
4. Under Custom HTTP Headers, click Add header:
   • Header: Authorization
   • Value: Bearer <your_token>
5. Click Save & Test.

Or configure via datasource.yml:

apiVersion: 1
datasources:
  - name: Uptrace Tempo
    type: tempo
    access: proxy
    url: https://api.uptrace.dev/api/tempo/<project_id>
    editable: true
    jsonData:
      httpHeaderName1: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'Bearer <your_token>'

Finding your project ID and token

• Project ID: visible in the URL of any project page (e.g. /projects/42) and in Project Settings → General.
• Auth token: go to User menu → Auth tokens to create or copy a token. Use a user token, not a project DSN — the Grafana data source authenticates as a user, not as a project.

Related

• Prometheus ingest — how to send Prometheus metrics to Uptrace
• PromQL compatibility — which PromQL functions and operators Uptrace supports
• Dashboards — Uptrace's built-in dashboard builder as an alternative