Monitoring XTDB with Grafana

XTDB provides tools and templates to facilitate the monitoring and observability of XTDB nodes. Metrics are exposed in the Prometheus format, which can be scraped by Prometheus and visualized in Grafana using XTDB’s pre-built dashboards.

Note

The XTDB cloud images come pre-configured with Prometheus metrics exposed - see the “Monitoring docs” for more information.

Prerequisites

You will need:

• A running Grafana instance
• Prometheus configured to scrape metrics from XTDB nodes
• Prometheus configured as a data source in Grafana

Refer to the official documentation for setup instructions:

• Grafana
• Prometheus
• Adding Prometheus as a Grafana datasource

Setting Up Grafana Dashboards

To import XTDB’s pre-built dashboards:

1. In Grafana, navigate to Dashboards → New → Import dashboard.
2. Upload the dashboard JSON file from the XTDB repository.
3. Select the Prometheus data source and click Import.

The following dashboards are available:

Cluster Monitoring Dashboard

Provides an overview of the entire XTDB cluster, including node health and performance.

Download the JSON template: here.

Node Debugging Dashboard

Focuses on individual XTDB nodes, showing metrics such as resource usage, performance, and health.

Download the JSON template: here.

Distributed Tracing with Tempo

XTDB supports distributed tracing using OpenTelemetry, which can be visualized in Grafana using Grafana Tempo as the tracing backend.

Prerequisites

You will need:

• A running Tempo instance configured to receive OTLP traces over HTTP.
• Tempo configured as a data source in Grafana.
• XTDB node configured with tracing enabled.

Refer to the Tempo documentation for setup instructions.

Configuring XTDB for Tracing

To enable tracing in your XTDB node, add the following to your node configuration:

tracer:
  enabled: true
  endpoint: "http://<tempo-host>:4318/v1/traces"

See the Tracing configuration reference for more details.

Viewing Traces in Grafana

Once XTDB is configured and sending traces to Tempo:

1. In Grafana, navigate to Explore.
2. Select the Tempo data source.
3. Use the query builder to search for traces by service name, operation, or other attributes.
4. Click on individual traces to view detailed span information.

Tracing provides detailed introspection into query execution, including:

• Per-query execution times for performance analysis.
• Information on which queries were executed, available through the xtdb.query span attributes.
• Lower-level operation timings, revealing how time is distributed across individual query operations.