Prometheus#
vCLU eksponuje endpoint /metrics w formacie Prometheus text exposition. Pozwala to na zbieranie metryk przez Prometheus, Grafana Agent lub dowolny system monitoringu kompatybilny z Prometheus.
Endpoint#
GET http://<vclu-ip>:8080/metrics
Endpoint jest domyślnie publiczny (nie wymaga uwierzytelnienia) - dzięki temu Prometheus może scrapować metryki bez konfiguracji Basic Auth.
Odpowiedź w formacie text/plain; version=0.0.4:
# HELP vclu_uptime_seconds Time since vCLU started in seconds
# TYPE vclu_uptime_seconds gauge
vclu_uptime_seconds 86400.00
# HELP vclu_memory_mb Current memory usage in megabytes
# TYPE vclu_memory_mb gauge
vclu_memory_mb 12.34
# HELP vclu_lua_executions_total Total Lua script executions
# TYPE vclu_lua_executions_total counter
vclu_lua_executions_total 5678
...
Metryki#
System#
| Metryka | Typ | Opis |
|---|
vclu_uptime_seconds | gauge | Czas działania vCLU w sekundach |
vclu_memory_bytes | gauge | Zużycie pamięci w bajtach |
vclu_memory_mb | gauge | Zużycie pamięci w megabajtach |
vclu_goroutines | gauge | Liczba goroutines Go |
vclu_gc_runs_total | counter | Łączna liczba cykli GC |
Lua runtime#
| Metryka | Typ | Opis |
|---|
vclu_lua_executions_total | counter | Łączna liczba wykonań skryptów Lua |
vclu_lua_errors_total | counter | Łączna liczba błędów Lua |
vclu_lua_timers_active | gauge | Aktywne timery |
vclu_lua_timers_fired_total | counter | Łączna liczba odpalonych timerów |
Protokół CLU#
| Metryka | Typ | Opis |
|---|
vclu_commands_received_total | counter | Odebrane komendy CLU |
vclu_commands_executed_total | counter | Wykonane komendy CLU |
vclu_commands_errors_total | counter | Błędy komend CLU |
vclu_commands_rate | gauge | Komendy na minutę |
Pluginy#
| Metryka | Typ | Opis |
|---|
vclu_plugins_active | gauge | Liczba aktywnych pluginów |
vclu_plugin_http_requests_total | counter | Requesty HTTP pluginów |
vclu_plugin_http_errors_total | counter | Błędy HTTP pluginów |
MQTT#
| Metryka | Typ | Opis |
|---|
vclu_mqtt_connected | gauge | Status połączenia (1=połączony, 0=rozłączony) |
vclu_mqtt_published_total | counter | Opublikowane wiadomości |
vclu_mqtt_received_total | counter | Odebrane wiadomości |
vclu_mqtt_reconnects_total | counter | Łączna liczba reconnectów |
HTTP Server#
| Metryka | Typ | Opis |
|---|
vclu_http_requests_total | counter | Wszystkie requesty HTTP |
vclu_http_requests_api_total | counter | Requesty API |
vclu_http_requests_web_total | counter | Requesty stron WWW |
vclu_http_errors_4xx_total | counter | Błędy 4xx |
vclu_http_errors_5xx_total | counter | Błędy 5xx |
vclu_http_requests_rate | gauge | Requesty na minutę |
HomeKit#
| Metryka | Typ | Opis |
|---|
vclu_homekit_accessories | gauge | Liczba akcesorii HomeKit |
vclu_homekit_paired | gauge | Status parowania (1=sparowany) |
vclu_homekit_requests_total | counter | Wszystkie requesty HomeKit |
vclu_homekit_get_total | counter | Requesty GET HomeKit |
vclu_homekit_set_total | counter | Requesty SET HomeKit |
vclu_homekit_events_total | counter | Wysłane eventy HomeKit |
MCP (AI)#
| Metryka | Typ | Opis |
|---|
vclu_mcp_requests_total | counter | Wszystkie wywołania narzędzi MCP |
vclu_mcp_errors_total | counter | Błędy MCP |
vclu_mcp_active_sessions | gauge | Aktualnie przetwarzane requesty MCP |
Konfiguracja#
Konfiguracja endpointu w .vclu.json:
{
"metrics": {
"enabled": true,
"auth": false,
"username": "",
"password": ""
}
}
| Pole | Typ | Domyślnie | Opis |
|---|
enabled | bool | true | Włącz/wyłącz endpoint /metrics |
auth | bool | false | Wymagaj Basic Auth |
username | string | "" | Nazwa użytkownika (gdy auth: true) |
password | string | "" | Hasło (gdy auth: true) |
Konfiguracja Prometheus#
prometheus.yml#
scrape_configs:
- job_name: 'vclu'
scrape_interval: 30s
static_configs:
- targets: ['192.168.1.100:8080']
labels:
instance: 'vclu-salon'
Z autoryzacją:
scrape_configs:
- job_name: 'vclu'
scrape_interval: 30s
basic_auth:
username: 'prometheus'
password: 'secret'
static_configs:
- targets: ['192.168.1.100:8080']
Wiele instancji vCLU#
scrape_configs:
- job_name: 'vclu'
scrape_interval: 30s
static_configs:
- targets:
- '192.168.1.100:8080'
- '192.168.1.101:8080'
- '192.168.1.102:8080'
labels:
env: 'production'
Grafana#
Przykładowe zapytania PromQL#
# Zuzycie pamieci (MB)
vclu_memory_mb
# Bledy Lua w ostatniej godzinie
increase(vclu_lua_errors_total[1h])
# Srednia liczba komend na minute (5 min)
avg_over_time(vclu_commands_rate[5m])
# HTTP error rate (%)
rate(vclu_http_errors_4xx_total[5m]) + rate(vclu_http_errors_5xx_total[5m])
/ rate(vclu_http_requests_total[5m]) * 100
# Czy MQTT jest polaczony
vclu_mqtt_connected == 1
# Tempo wiadomosci MQTT (msg/min)
rate(vclu_mqtt_published_total[5m]) * 60
# Uptime w dniach
vclu_uptime_seconds / 86400
Alerty#
# alert.rules.yml
groups:
- name: vclu
rules:
- alert: VCLUDown
expr: up{job="vclu"} == 0
for: 2m
labels:
severity: critical
annotations:
summary: "vCLU {{ $labels.instance }} jest niedostepny"
- alert: VCLUHighMemory
expr: vclu_memory_mb > 100
for: 5m
labels:
severity: warning
annotations:
summary: "vCLU {{ $labels.instance }} zuzywa >100MB pamieci"
- alert: VCLUMQTTDisconnected
expr: vclu_mqtt_connected == 0
for: 1m
labels:
severity: warning
annotations:
summary: "vCLU {{ $labels.instance }} stracil polaczenie MQTT"
- alert: VCLULuaErrors
expr: increase(vclu_lua_errors_total[5m]) > 10
labels:
severity: warning
annotations:
summary: "vCLU {{ $labels.instance }} - >10 bledow Lua w 5 minut"
API JSON (alternatywa)#
Oprócz formatu Prometheus, vCLU udostępnia te same metryki w formacie JSON:
| Endpoint | Opis |
|---|
GET /api/stats | Bieżący snapshot metryk |
GET /api/stats/timeseries | Dane historyczne (24h, próbki co 1 min) |
GET /api/stats/timeseries?since=<ms> | Dane przyrostowe od podanego timestampu |
Endpoint /api/stats wymaga uwierzytelnienia (sesja cookie).
Time series#
vCLU przechowuje dane historyczne w pamięci:
| Parametr | Wartość |
|---|
| Interwał próbkowania | 1 minuta |
| Retencja | 24 godziny (1440 próbek) |
| Format przechowywania | Ring buffer |
Śledzone serie czasowe:
| Seria | Jednostka | Opis |
|---|
memory_used | MB | Zużycie pamięci |
goroutines | count | Goroutines Go |
gc_pause | ms | Pauzy GC |
lua_exec_time | ms | Średni czas wykonania Lua |
timers_active | count | Aktywne timery |
cmd_rate | req/min | Komendy CLU na minutę |
plugins_active | count | Aktywne pluginy |
http_rate | req/min | Requesty HTTP na minutę |
homekit_accessories | count | Akcesoria HomeKit |
homekit_paired | count | Sparowane urządzenia |
Strona /stats w interfejsie webowym vCLU wizualizuje te dane na wykresach.