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>:9081/metrics

Endpoint jest domyslnie publiczny (nie wymaga uwierzytelnienia) - dzieki temu Prometheus moze scrapowac metryki bez konfiguracji Basic Auth.

Odpowiedz 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 dzialania vCLU w sekundach
`vclu_memory_bytes`	gauge	Zuzycie pamieci w bajtach
`vclu_memory_mb`	gauge	Zuzycie pamieci w megabajtach
`vclu_goroutines`	gauge	Liczba goroutines Go
`vclu_gc_runs_total`	counter	Laczna liczba cykli GC

Lua runtime#

Metryka	Typ	Opis
`vclu_lua_executions_total`	counter	Laczna liczba wykonan skryptow Lua
`vclu_lua_errors_total`	counter	Laczna liczba bledow Lua
`vclu_lua_timers_active`	gauge	Aktywne timery
`vclu_lua_timers_fired_total`	counter	Laczna liczba odpalonych timerow

Protokol 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	Bledy komend CLU
`vclu_commands_rate`	gauge	Komendy na minute

Pluginy#

Metryka	Typ	Opis
`vclu_plugins_active`	gauge	Liczba aktywnych pluginow
`vclu_plugin_http_requests_total`	counter	Requesty HTTP pluginow
`vclu_plugin_http_errors_total`	counter	Bledy HTTP pluginow

MQTT#

Metryka	Typ	Opis
`vclu_mqtt_connected`	gauge	Status polaczenia (1=polaczony, 0=rozlaczony)
`vclu_mqtt_published_total`	counter	Opublikowane wiadomosci
`vclu_mqtt_received_total`	counter	Odebrane wiadomosci
`vclu_mqtt_reconnects_total`	counter	Laczna liczba reconnectow

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	Bledy 4xx
`vclu_http_errors_5xx_total`	counter	Bledy 5xx
`vclu_http_requests_rate`	gauge	Requesty na minute

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	Wyslane eventy HomeKit

Konfiguracja#

Konfiguracja endpointu w .vclu.json:

{
  "metrics": {
    "enabled": true,
    "auth": false,
    "username": "",
    "password": ""
  }
}

Pole	Typ	Domyslnie	Opis
`enabled`	bool	`true`	Wlacz/wylacz endpoint `/metrics`
`auth`	bool	`false`	Wymagaj Basic Auth
`username`	string	`""`	Nazwa uzytkownika (gdy `auth: true`)
`password`	string	`""`	Haslo (gdy `auth: true`)

Konfiguracja Prometheus#

prometheus.yml#

scrape_configs:
  - job_name: 'vclu'
    scrape_interval: 30s
    static_configs:
      - targets: ['192.168.1.100:9081']
        labels:
          instance: 'vclu-salon'

Z autoryzacja:

scrape_configs:
  - job_name: 'vclu'
    scrape_interval: 30s
    basic_auth:
      username: 'prometheus'
      password: 'secret'
    static_configs:
      - targets: ['192.168.1.100:9081']

Wiele instancji vCLU#

scrape_configs:
  - job_name: 'vclu'
    scrape_interval: 30s
    static_configs:
      - targets:
          - '192.168.1.100:9081'
          - '192.168.1.101:9081'
          - '192.168.1.102:9081'
        labels:
          env: 'production'

Grafana#

Przykladowe 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)#

Oprocz formatu Prometheus, vCLU udostepnia te same metryki w formacie JSON:

Endpoint	Opis
`GET /api/stats`	Biezacy snapshot metryk
`GET /api/stats/timeseries`	Dane historyczne (24h, probki 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 pamieci:

Parametr	Wartosc
Interwal probkowania	1 minuta
Retencja	24 godziny (1440 probek)
Format przechowywania	Ring buffer

Sledzone serie czasowe:

Seria	Jednostka	Opis
`memory_used`	MB	Zuzycie pamieci
`goroutines`	count	Goroutines Go
`gc_pause`	ms	Pauzy GC
`lua_exec_time`	ms	Sredni czas wykonania Lua
`timers_active`	count	Aktywne timery
`cmd_rate`	req/min	Komendy CLU na minute
`plugins_active`	count	Aktywne pluginy
`http_rate`	req/min	Requesty HTTP na minute
`homekit_accessories`	count	Akcesoria HomeKit
`homekit_paired`	count	Sparowane urzadzenia

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