How To Connect Uptime Kuma with Grafana

If you are already using Uptime Kuma to monitor your websites, homelab, APIs, servers or network services, connecting it with Grafana allows you to create professional dashboards. These can allow you to check and analyze historical performance much better in beautiful graphs, visualize uptime trends and even build more advanced alerts. This page details all the steps you need to follow to connect Uptime Kuma with Grafana using Prometheus.

As Grafana and Uptime Kuma are built for different purposes, it’s good to first get a quick understanding of what Grafana is and how they both work together.

What is Grafana and how does it work with Uptime Kuma

Grafana is an open-source observability tool that is widely used by enterprises and even homelab enthusiasts to monitor their infrastructure, applications, networks and servers. It does not collect the actual metrics itself; it connects to other data sources such as Prometheus, InfluxDB, Loki or MySQL.

It helps visualize raw monitoring data into easy-to-understand dashboards and graphs. This allows you to quickly identify any performance issues or service outages, which is important if you have strict SLA requirements.

When Grafana is used with Uptime Kuma, it allows you to:

  1. View the status of all your monitors from a single dashboard.
  2. Analyse historical uptime and response time trends over weeks or months.
  3. Track SSL/TLS certificate expiry dates as they are reported.
  4. Monitor response times with beautiful detailed graphs and latency statistics.
  5. You can also setup alerts based on your Prometheus metrics.

What you need to remember is that Grafana is not a replacement for Uptime Kuma. Instead, both of these complement each other. Uptime Kuma performs the monitoring by checking your servers or websites, APIs and Grafana visualizes the metrics collected by Prometheus.

Before you start:

1. Have Uptime Kuma installed and running, either via Docker or a non-docker method.

2. Grafana and Prometheus installed and configured.

3. Have the Uptime Kuma API key generated and ready, this can be found under Settings > API Keys > + Add API Key.

The ports are usually:

  • Uptime Kuma: 3001
  • Prometheus: 9090
  • Grafana: 3000

Verify the Metrics Endpoint is working

Uptime Kuma directly exposes Prometheus metrics.

Metrics endpoint is located at:

http://youripaddress:3001/metrics

You now need to add the API key you generated; enter that key in the password field and leave the username field empty. You should see a lot of metrics now in text format on the page.

Now Configure Prometheus

You need to find your Prometheus.yml file and add a new scrape job.

Below is an example scrape job for Uptime Kuma:

scrape_configs:

  - job_name: 'uptime-kuma'

    metrics_path: /metrics

    static_configs:
      - targets:
          - uptime-kuma:3001

If you are using Docker Compose, replace “uptime-kuma” with the Docker service name.

Once the file is saved, just restart Prometheus.

If you are using Docker:

docker restart prometheus

If you are using Linux:

sudo systemctl restart prometheus

Verify Prometheus is Scraping

Open Prometheus:

http://localhost:9090/targets

You should see the following and the state to be “UP”.

uptime-kuma

State: UP

Explore available Metrics

Open Grafana and click on Graph and just start typing uptime_kuma and you will see all of your metrics.

Common examples are:

uptime_kuma_monitor_status

uptime_kuma_response_time

uptime_kuma_cert_days_remaining

uptime_kuma_monitor_up

uptime_kuma_version

Note: The available metric names may vary a little depending on your version of Uptime Kuma. Always aim to have the latest version downloaded.

Finally, add Prometheus as a Data Source in Grafana

  1. Open Grafana, click on Connections > Data Sources > Add data source.
  2. Select “Prometheus”.
  3. Add the URL as you have setup Prometheus.
  4. Click on “Save and Test”.
  5. Should now see “Data source is working”.

Import Ready-Made Uptime Kuma Grafana Dashboards

Dashboard ID 18278 is beautiful and includes certificate expiry, total monitors, average response delay and online status.

Uptime Kuma Grafana Dashboard
Grafana dashboard showing Uptime Kuma metrics

Conclusion

Connecting Uptime Kuma to Grafana is straightforward once you understand the data flow.

  1. Uptime Kuma exposes Prometheus metrics at the /metrics address.
  2. Prometheus scrapes those metrics on a schedule and stores the time series.
  3. Grafana queries Prometheus to display dashboards, charts and alerts.

This architecture is scalable and has been production-proven for a while along with giving you detailed visibility into uptime, latency and SSL certificate health. It also makes it easier for you to see the historical trends.