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#

MetrykaTypOpis
vclu_uptime_secondsgaugeCzas działania vCLU w sekundach
vclu_memory_bytesgaugeZużycie pamięci w bajtach
vclu_memory_mbgaugeZużycie pamięci w megabajtach
vclu_goroutinesgaugeLiczba goroutines Go
vclu_gc_runs_totalcounterŁączna liczba cykli GC

Lua runtime#

MetrykaTypOpis
vclu_lua_executions_totalcounterŁączna liczba wykonań skryptów Lua
vclu_lua_errors_totalcounterŁączna liczba błędów Lua
vclu_lua_timers_activegaugeAktywne timery
vclu_lua_timers_fired_totalcounterŁączna liczba odpalonych timerów

Protokół CLU#

MetrykaTypOpis
vclu_commands_received_totalcounterOdebrane komendy CLU
vclu_commands_executed_totalcounterWykonane komendy CLU
vclu_commands_errors_totalcounterBłędy komend CLU
vclu_commands_rategaugeKomendy na minutę

Pluginy#

MetrykaTypOpis
vclu_plugins_activegaugeLiczba aktywnych pluginów
vclu_plugin_http_requests_totalcounterRequesty HTTP pluginów
vclu_plugin_http_errors_totalcounterBłędy HTTP pluginów

MQTT#

MetrykaTypOpis
vclu_mqtt_connectedgaugeStatus połączenia (1=połączony, 0=rozłączony)
vclu_mqtt_published_totalcounterOpublikowane wiadomości
vclu_mqtt_received_totalcounterOdebrane wiadomości
vclu_mqtt_reconnects_totalcounterŁączna liczba reconnectów

HTTP Server#

MetrykaTypOpis
vclu_http_requests_totalcounterWszystkie requesty HTTP
vclu_http_requests_api_totalcounterRequesty API
vclu_http_requests_web_totalcounterRequesty stron WWW
vclu_http_errors_4xx_totalcounterBłędy 4xx
vclu_http_errors_5xx_totalcounterBłędy 5xx
vclu_http_requests_rategaugeRequesty na minutę

HomeKit#

MetrykaTypOpis
vclu_homekit_accessoriesgaugeLiczba akcesorii HomeKit
vclu_homekit_pairedgaugeStatus parowania (1=sparowany)
vclu_homekit_requests_totalcounterWszystkie requesty HomeKit
vclu_homekit_get_totalcounterRequesty GET HomeKit
vclu_homekit_set_totalcounterRequesty SET HomeKit
vclu_homekit_events_totalcounterWysłane eventy HomeKit

MCP (AI)#

MetrykaTypOpis
vclu_mcp_requests_totalcounterWszystkie wywołania narzędzi MCP
vclu_mcp_errors_totalcounterBłędy MCP
vclu_mcp_active_sessionsgaugeAktualnie przetwarzane requesty MCP

Konfiguracja#

Konfiguracja endpointu w .vclu.json:

{
  "metrics": {
    "enabled": true,
    "auth": false,
    "username": "",
    "password": ""
  }
}
PoleTypDomyślnieOpis
enabledbooltrueWłącz/wyłącz endpoint /metrics
authboolfalseWymagaj Basic Auth
usernamestring""Nazwa użytkownika (gdy auth: true)
passwordstring""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:

EndpointOpis
GET /api/statsBieżący snapshot metryk
GET /api/stats/timeseriesDane 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:

ParametrWartość
Interwał próbkowania1 minuta
Retencja24 godziny (1440 próbek)
Format przechowywaniaRing buffer

Śledzone serie czasowe:

SeriaJednostkaOpis
memory_usedMBZużycie pamięci
goroutinescountGoroutines Go
gc_pausemsPauzy GC
lua_exec_timemsŚredni czas wykonania Lua
timers_activecountAktywne timery
cmd_ratereq/minKomendy CLU na minutę
plugins_activecountAktywne pluginy
http_ratereq/minRequesty HTTP na minutę
homekit_accessoriescountAkcesoria HomeKit
homekit_pairedcountSparowane urządzenia

Strona /stats w interfejsie webowym vCLU wizualizuje te dane na wykresach.