When the DNS service running on my home server silently crashed and my mobile app’s backend remained cut off from the outside world for hours, I realized I couldn’t leave monitoring at the level of “checking the browser every now and then.” A homelab monitoring infrastructure is built by bringing together the Uptime Kuma + Grafana duo to observe the health of your systems in real-time and catch potential outages before they grow. While Uptime Kuma is a lightweight and user-friendly tool that checks whether services are up (liveness), Grafana combines this data with historical trend analysis, system resource consumption, and advanced dashboards to provide complete observability. In this guide, I will explain step-by-step how to monitor all the services in your homelab environment from a single center, how to turn data into meaningful dashboards, and how to catch sneaky system errors.
Just because a server is up does not mean the services on it are working correctly. A machine responding to ping requests might be returning 500 errors to users because the database connection behind it has dropped. That is why we need to ask not just “is the server on,” but “are my services actually performing their function?” The integration of Uptime Kuma and Grafana combines the answers to both questions on a single screen, giving you complete control over your homelab or small-scale production infrastructure.
Why Uptime Kuma + Grafana is the Best Duo
The Uptime Kuma + Grafana combination is the most balanced monitoring solution, combining lightweight operation with deep analysis. If you try to use only Grafana and Prometheus, you have to configure Blackbox Exporter for a simple HTTP status check (uptime check), deal with complex YAML files, and reload Prometheus for every new service. Uptime Kuma, on the other hand, allows you to add a new HTTP, TCP, DNS, or gRPC check in seconds via its web interface. However, where Kuma falls short is long-term data retention, correlation, and advanced visualization.
When we include Grafana in this equation, we crown the practicality of Uptime Kuma with the unlimited visualization and metric consolidation power of Grafana. Uptime Kuma can export all the status data it collects in Prometheus format. This way, you can add the real-time availability status of your services to the Grafana dashboard where you collect hardware metrics such as CPU, RAM, and disk temperature of your homelab server. Seeing both the hardware load and the software response time on a single screen makes it significantly easier to find the root cause of a problem when a performance bottleneck occurs.
graph TD; A["Services (HTTP/TCP/DNS)"] --> B["Uptime Kuma (Status Check)"] B -->|Prometheus Metrics Endpoint| C["Prometheus (Metric Collector)"] D["System Metrics (Node Exporter)"] --> C C --> E["Grafana Dashboard"] B -->|Instant Notification| F["Telegram / Discord / Pushover"]
How to Set Up Uptime Kuma + Grafana Infrastructure with Docker Compose
When managing systems, instead of installing each service bare-metal one by one, I prefer to create an isolated and portable stack using Docker Compose. This approach gives me incredible flexibility if I want to migrate the homelab server tomorrow or if I need to reset the entire monitoring infrastructure. In our setup, we will combine Uptime Kuma, Prometheus (to collect metrics), and Grafana services in a single docker-compose.yml file.
The following configuration uses an isolated Docker network (bridge network) so that services can talk to each other securely, and includes volume definitions to make the data persistent:
version: '3.8'
networks:
monitoring:
driver: bridge
volumes:
uptime-kuma-data:
prometheus-data:
grafana-data:
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
volume:
- uptime-kuma-data:/app/data
ports:
- "3001:3001"
networks:
- monitoring
restart: always
prometheus:
image: prom/prometheus:latest
container_name: prometheus
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
- prometheus-data:/prometheus
ports:
- "9090:9090"
networks:
- monitoring
restart: always
grafana:
image: grafana/grafana:latest
container_name: grafana
volumes:
- grafana-data:/var/lib/grafana
ports:
- "3000:3000"
networks:
- monitoring
restart: alwaysAfter saving this file to a directory like /opt/monitoring on your server, we need to create a configuration file so that Prometheus can pull data from Uptime Kuma. Open a file named prometheus.yml next to the Docker Compose file and add the following basic settings.
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'prometheus'
static_configs:
- targets: ['localhost:9090']
- job_name: 'uptime-kuma'
metrics_path: '/metrics'
static_configs:
- targets: ['uptime-kuma:3001']How to Export Uptime Kuma Metrics to Grafana in Prometheus Format
After bringing up the infrastructure, we can move on to the stage of exporting the status data produced by Uptime Kuma to Grafana via Prometheus. Uptime Kuma offers the /metrics endpoint active by default, but you may want to check this for security reasons or configuration requirements. Go to http://<server-ip>:3001 in your browser to complete the initial setup steps.
After entering the Uptime Kuma interface, click on your profile picture in the top right and go to Settings > API & Keys (or directly to the “Prometheus” section in the search bar of the settings menu, depending on the installed version). Verify here that the Prometheus integration is active and whether it requires any authentication (auth). If everything is fine, when you go to http://<server-ip>:3001/metrics in your browser, you should see Prometheus-formatted metric lines like this:
# HELP monitor_status Monitor Status (1 = UP, 0 = DOWN, 2 = PENDING)
# TYPE monitor_status gauge
monitor_status{id="1",name="Home-DNS",type="dns",url="192.168.1.1"} 1
# HELP monitor_response_time Monitor Response Time (ms)
# TYPE monitor_response_time gauge
monitor_response_time{id="1",name="Home-DNS",type="dns",url="192.168.1.1"} 12Now, to pull this data into Prometheus, run the docker compose up -d command in the terminal to start the entire stack. Go to the Prometheus interface (http://<server-ip>:9090) and check the Status > Targets menu. If you see the green UP status next to the uptime-kuma target, it means the metric collection process has started successfully. On the Grafana side, all we need to do is add Prometheus as a Data Source and point it to the http://prometheus:9090 address.
How to Design a Dashboard on Grafana
Once the data starts flowing into Prometheus, we can design a meaningful dashboard on Grafana that summarizes the system status at a single glance. Log in to the Grafana interface (http://<server-ip>:3000) with the default admin/admin credentials and update your password. Follow the path Connections > Data Sources from the left menu, click the “Add data source” button, and select Prometheus. Type http://prometheus:9090 in the URL field and click the “Save & test” button at the bottom to verify the connection.
Instead of designing a panel from scratch, you can use ready-made templates prepared by the community for Uptime Kuma. The ready-made dashboards with ID 14191 or 15234 in the Grafana Dashboard library are perfect for this job. To create a new dashboard, click the + icon in the top right, select Import, type one of these IDs in the ID field, and load it.
If you want to design your own custom panel, the most critical PromQL (Prometheus Query Language) queries you can use are:
1. Instant Status of Services (Stat Panel)
You can use the following query for a summary panel showing how many services in the system are up and how many are down:
monitor_status == 1You can match the result of this query with the “Stat” visualization in Grafana and define color thresholds so that it is green (UP) if the value is 1, and red (DOWN) if it is 0.
2. Average Response Times (Graph Panel)
To monitor network latency or fluctuations in response times of services, run this query in the “Time Series” panel:
monitor_response_timeThanks to this graph, you can analyze, for example, why the response time of the gateway device in your local network increases every evening, the peering problems of your internet service provider (ISP), or the disk load on the server.
How to Build a Notification Infrastructure for Outages
The biggest mistake of monitoring systems is that they only show a problem on the screen when it occurs; because nobody stares at a dashboard screen 24 hours a day. Uptime Kuma has an incredibly flexible notification engine for this. Telegram, Discord, Pushover, Slack, Webhook, and even local SMS gateway integrations are supported out of the box.
My most preferred method in the homelab environment is to receive instant notifications via the Telegram Bot API. I follow these steps to set this up:
- Talk to
@BotFatheron Telegram to create a new bot and copy the API Token it gives you. - Learn your own chat ID so the bot can send you messages (you can use
@userinfobotfor this). - Go to the Settings > Notification section in the Uptime Kuma interface and click the “Setup Notification” button.
- Select Telegram as the Notification Type, and fill in the Bot Token and Chat ID fields.
- Click the “Test” button to verify that the test message arrives on your phone.
[Home-DNS] [🔴 Down]
Connection timeout.
Time: 2026-07-05 14:32:10 UTCThe biggest advantage of setting up notifications via Uptime Kuma is that you can make precise service-based adjustments directly without dealing with Grafana’s complex alerting rules. For example, to avoid getting notifications for temporary network fluctuations, you can set the “Retries” value to 2 or 3. This way, a notification will only drop to your phone if the service fails in 3 consecutive checks.
Which Sneaky Pitfalls Should You Watch Out For When Monitoring a Homelab?
When you start monitoring systems, there are some sneaky pitfalls that can crash the system itself or mislead you due to misconfigurations. In my 20 years of field experience, I have seen many scenarios where the monitoring system itself became a source of problems. You should be on guard against these three pitfalls when designing your homelab environment:
1. The Curse of DNS Negative Caching
When Uptime Kuma monitors a service, it resolves the domain name (FQDN). If your local DNS server (e.g., Pi-hole or AdGuard Home) temporarily crashes, Uptime Kuma cannot resolve the domain name and marks the service as “Down.” Even if the DNS server comes back up, because the DNS resolvers in the system cache the negative response (negative caching), your services may continue to appear “Down” for a long time even though they are actually running.
Solution: When monitoring critical services on Uptime Kuma, prefer to perform TCP port checks directly via static IP addresses instead of domain names, or ensure that the Uptime Kuma container uses a reliable external DNS (such as 1.1.1.1) directly as its DNS server.
2. Disk Space Fires (Docker Log Bloat)
When Prometheus is left with its default settings, it may try to store the metrics it collects on disk forever. Homelab servers usually use SSDs with limited capacity. If you do not limit Prometheus’s data retention policy, the disk will fill up within a few months and all your Docker containers will crash with a No space left on device error.
Solution: To keep Prometheus’s disk usage under control, add the following command parameters (args) to the prometheus service in the Docker Compose file:
command:
- '--config.file=/etc/prometheus/prometheus.yml'
- '--storage.tsdb.path=/prometheus'
- '--storage.tsdb.retention.time=15d' # Keep data for only 15 days
- '--storage.tsdb.retention.size=5GB' # Disk usage should not exceed 5 GB3. Not Being Able to Monitor the Monitoring System Itself (Who Watches the Watchmen?)
If you are monitoring all your services with Uptime Kuma inside your homelab server, what happens when the server loses power or your internet connection drops completely? The answer is simple: nothing happens. You get no notifications on your phone because the system that would send the notification has also lost power. This situation is called a “Single Point of Failure” (SPOF) in system architecture.
Solution: To truly measure external world accessibility and realize that your homelab has completely lost its internet connection, set up a secondary Uptime Kuma running on a very cheap or free-tier external VPS (Virtual Private Server). This external server should monitor the external IP address of your home router or your dynamic DNS (DDNS) address. The moment the internet drops at home, the external server will notice this and send you a “Home Internet Down” notification via Telegram.
Conclusion
The integration of Uptime Kuma and Grafana is one of the most practical investments in the homelab world that eliminates the “I thought it was working” delusion. Thanks to this setup, you not only see the instant status of services, but you also discover your hardware limits by performing historical performance analysis.
As a next step, you can install Node Exporter on your homelab server to export CPU temperature, fan speeds, and disk health status (smartctl) to Prometheus and integrate them into this Grafana dashboard you have prepared. Remember, an unmonitored system is an unmanaged system.