Wizualizacja logów nginx w Grafanie

W tym artykule opisuję, jak na podstawie logów serwera Nginx stworzyć interaktywną wizualizację geograficzną zapytań — z podziałem na miasta i kraje — oraz jak zliczać liczbę odwiedzin z poszczególnych lokalizacji. Do realizacji tego celu użyłem następującego stosu technologicznego:

moduł libnginx-mod-http-geoip2 do Nginx — umożliwia wzbogacanie logów o dane geolokalizacyjne;
Grafana Alloy — agent zbierający i przesyłający logi;
VictoriaMetrics Logs (VictoriaLogs) — backend do przechowywania i odpytywania logów;
Grafana — narzędzie do tworzenia dashboardów i wizualizacji;
bazy danych GeoIP od MaxMind (GeoLite2-Country.mmdb i GeoLite2-City.mmdb) — zawierają mapowanie adresów IP na lokalizacje geograficzne.

Całość działa na maszynach wirtualnych lub kontenerach LXC w środowisku Proxmox, choć konfiguracja jest w pełni przenośna i nie wymaga konkretnego hypervisora.

Konfiguracja nginx

Zaczynamy od zainstalowania modułu libnginx-mod-http-geoip2. Na Debianie wystarczy jedna komenda:

apt install libnginx-mod-http-geoip2

Następnie ze strony https://www.maxmind.com pobieramy bazy GeoIP — GeoLite2-Country.mmdb oraz GeoLite2-City.mmdb — i kopiujemy je do katalogu konfiguracyjnego Nginx (np. /etc/nginx). Do pobrania baz konieczne jest założenie bezpłatnego konta na stronie MaxMind. Modyfikujemy plik nginx.conf, dodając konfigurację baz mmdb oraz nowy format logów w postaci JSON. Format ten zawiera m.in. pola z danymi GeoIP, co pozwoli nam później na filtrowanie i agregację zapytań według lokalizacji:

http {

...

        geoip2 /etc/nginx/GeoLite2-Country.mmdb {
                $geoip2_country_code default=PL source=$remote_addr country iso_code;
                $geoip2_country_name source=$remote_addr country names en;
        }

        geoip2 /etc/nginx/GeoLite2-City.mmdb {
                $geoip2_city_name city names en;
                $geoip2_location_latitude location latitude;
                $geoip2_location_longitude location longitude;
                $geoip2_city_geoname_id city geoname_id;
        }

log_format json_analytics escape=json '{'
    '"msec": "$msec", ' # request unixtime in seconds with a milliseconds resolution
    '"connection": "$connection", ' # connection serial number
    '"connection_requests": "$connection_requests", ' # number of requests made in connection
    '"pid": "$pid", ' # process pid
    '"request_id": "$request_id", ' # the unique request id
    '"request_length": "$request_length", ' # request length (including headers and body)
    '"remote_addr": "$remote_addr", ' # client IP
    '"remote_user": "$remote_user", ' # client HTTP username
    '"remote_port": "$remote_port", ' # client port
    '"time_local": "$time_local", '
    '"time_iso8601": "$time_iso8601", ' # local time in the ISO 8601 standard format
    '"request": "$request", ' # full path no arguments if the request
    '"request_uri": "$request_uri", ' # full path and arguments if the request
    '"args": "$args", ' # args
    '"status": "$status", ' # response status code
    '"body_bytes_sent": "$body_bytes_sent", ' # the number of body bytes exclude headers sent to a client
    '"bytes_sent": "$bytes_sent", ' # the number of bytes sent to a client
    '"http_referer": "$http_referer", ' # HTTP referer
    '"http_user_agent": "$http_user_agent", ' # user agent
    '"http_x_forwarded_for": "$http_x_forwarded_for", ' # http_x_forwarded_for
    '"http_host": "$http_host", ' # the request Host: header
    '"server_name": "$server_name", ' # the name of the vhost serving the request
    '"request_time": "$request_time", ' # request processing time in seconds with msec resolution
    '"upstream": "$upstream_addr", ' # upstream backend server for proxied requests
    '"upstream_connect_time": "$upstream_connect_time", ' # upstream handshake time incl. TLS
    '"upstream_header_time": "$upstream_header_time", ' # time spent receiving upstream headers
    '"upstream_response_time": "$upstream_response_time", ' # time spent receiving upstream body
    '"upstream_response_length": "$upstream_response_length", ' # upstream response length
    '"upstream_cache_status": "$upstream_cache_status", ' # cache HIT/MISS where applicable
    '"ssl_protocol": "$ssl_protocol", ' # TLS protocol
    '"ssl_cipher": "$ssl_cipher", ' # TLS cipher
    '"scheme": "$scheme", ' # http or https
    '"request_method": "$request_method", ' # request method
    '"server_protocol": "$server_protocol", ' # request protocol, like HTTP/1.1 or HTTP/2.0
    '"pipe": "$pipe", ' # "p" if request was pipelined, "." otherwise
    '"gzip_ratio": "$gzip_ratio",'
    '"geoip_country_code": "$geoip2_country_code",'
    '"geoip_country_name": "$geoip2_country_name",'
    '"geoip_city_name": "$geoip2_city_name",'
    '"geoip_location_latitude": $geoip2_location_latitude,'
    '"geoip_location_longitude": $geoip2_location_longitude,'
    '"geoip_city_geoname_id": "$geoip2_city_geoname_id"'
'}';

...

Kluczowe są pola na końcu formatu: geoip_location_latitude, geoip_location_longitude i geoip_city_name. To właśnie one zostaną użyte do rysowania punktów na mapie w Grafanie. Następnie konfigurujemy logi dla konkretnego wirtualnego hosta. W tym przykładzie prowadzę dwa pliki logów — jeden w klasycznym formacie (do ewentualnego debugowania) i jeden w formacie JSON:

server {
  ...

  access_log /var/log/nginx/access-example.com-ssl.log;
  access_log /var/log/nginx/access-example.com-ssl-json.log json_analytics;

  ...
}

Po zapisaniu zmian przeładowujemy Nginx komendą nginx -s reload lub systemctl reload nginx.

Grafana Alloy

Grafana Alloy to agent do zbierania i przesyłania telemetrii — metryk, logów oraz śladów (traces). W naszym przypadku będziemy go używać wyłącznie do zbierania logów z pliku i przesyłania ich do VictoriaLogs przez kompatybilne API Loki. Instalacja na Debianie/Ubuntu:

sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

sudo apt-get update

sudo apt-get install alloy

Następnie konfigurujemy Alloy, wskazując pliki logów do śledzenia i adres docelowy VictoriaLogs. Plik konfiguracyjny znajduje się domyślnie w /etc/alloy/config.alloy:

logging {
  level = "warn"
}

prometheus.exporter.unix "default" {
  include_exporter_metrics = true
  disable_collectors       = ["mdadm"]
}

prometheus.scrape "default" {
  targets = array.concat(
    prometheus.exporter.unix.default.targets,
    [{
      // Self-collect metrics
      job         = "alloy",
      __address__ = "127.0.0.1:12345",
    }],
  )

  forward_to = [
  // TODO: components to forward metrics to (like prometheus.remote_write or
  // prometheus.relabel).
  ]
}

local.file_match "local_files" {
  path_targets = [{"__path__" = "/var/log/nginx/*-json.log"}]
  sync_period = "5s"
}

loki.process "filter_logs" {
  stage.drop {
    source = ""
    expression  = ".*Connection closed by authenticating user root"
    drop_counter_reason = "noisy"
  }
  forward_to = [loki.write.grafana_loki.receiver]
}

loki.source.file "log_scrape" {
  targets    = local.file_match.local_files.targets
  forward_to = [loki.process.filter_logs.receiver]
  tail_from_end = true
}

loki.write "grafana_loki" {
  endpoint {
    url = "http://192.168.0.133:9428/insert/loki/api/v1/push"

    // basic_auth {
    //  username = "admin"
    //  password = "admin"
    // }
  }
}

Blok local.file_match zbiera wszystkie pliki pasujące do wzorca *-json.log w katalogu logów Nginx. Blok loki.process odfiltrowuje nadmiarowe logi (w tym przypadku próby logowania SSH), a blok loki.write wysyła wszystko do VictoriaLogs. Zastąp adres IP i port własnym adresem serwera. Po zapisaniu konfiguracji uruchom lub zrestartuj usługę:

Victoriametrics Logs (VictoriaLogs)

VictoriaMetrics to wysokowydajny system do przechowywania i odpytywania danych czasowych. W naszym przypadku korzystamy z VictoriaLogs — modułu do przechowywania logów w sposób zbliżony do Loki, ale z lepszą kompresją i wydajnością. Instaluję VictoriaMetrics z VictoriaLogs jako kontener LXC w środowisku Proxmox, korzystając z gotowego skryptu społeczności:

post-image

Skrypt automatycznie tworzy kontener LXC z zainstalowanym VictoriaMetrics i VictoriaLogs, skonfigurowanymi jako usługi systemd. Po uruchomieniu kontenera VictoriaLogs jest dostępny pod portem 9428, a endpointem do przyjmowania logów z Alloy jest /insert/loki/api/v1/push. Oczywiście VictoriaMetrics i VictoriaLogs można zainstalować w dowolny inny sposób — jako pakiet apt, kontener Docker lub binarnie. Dokumentacja jest dostępna na oficjalnej stronie projektu: https://docs.victoriametrics.com/victorialogs/

Grafana

Podobnie jak VictoriaMetrics, Grafanę instaluję jako kontener LXC w Proxmox. Domyślnie Grafana jest dostępna na porcie 3000. Kiedy oba serwisy działają, możemy przystąpić do tworzenia wizualizacji geograficznej logów.

Krok 1 — Dodanie źródła danych

Przechodzimy do menu Connections → Data Sources i dodajemy nowe źródło danych typu VictoriaLogs. W polu URL wpisujemy adres naszego serwera VictoriaLogs, np. http://192.168.0.133:9428.

post-image

Zapisujemy konfigurację przyciskiem Save & Test. Jeśli połączenie powiedzie się, zobaczymy komunikat o poprawnym nawiązaniu połączenia.

Krok 2 — Tworzenie dashboardu

Tworzymy nowy dashboard w menu Dashboards → New Dashboard. Dashboard będzie głównym miejscem, w którym zbierzemy wszystkie wizualizacje związane z ruchem na serwerze.

post-image

Krok 3 — Dodanie wizualizacji mapy

Na dashboardzie klikamy Add panel i wybieramy typ wizualizacji Geomap. Jest to wbudowany panel Grafany, który pozwala rysować punkty na mapie świata na podstawie par współrzędnych geograficznych (szerokość i długość).

post-image

Krok 4 — Konfiguracja zapytania

W sekcji Query wybieramy wcześniej dodane źródło danych i wpisujemy zapytanie w języku LogsQL (dialekt VictoriaLogs):

_stream:{filename="/var/log/nginx/access-example.com-ssl-json.log"} geoip_location_latitude:!"" geoip_location_longitude:!"" geoip_city_name:!""| fields geoip_location_latitude, geoip_location_longitude,geoip_city_name | rename geoip_location_latitude latitude, geoip_location_longitude longitude, geoip_city_name city| stats (_time, latitude, longitude,city) count() as hits

Zapytanie to:

filtruje logi z konkretnego pliku (zmień nazwę pliku na własną); odrzuca wpisy, dla których brakuje danych o lokalizacji (operatory :!""); wybiera tylko potrzebne pola i zmienia ich nazwy na latitude, longitude i city — wymagane przez panel Geomap; agreguje wyniki i zlicza liczbę zapytań (hits) per lokalizacja.

Po wklejeniu zapytania i zapisaniu panelu na mapie pojawią się punkty odpowiadające miastom, z których napłynęły zapytania. Rozmiar lub kolor punktu można powiązać z polem hits, aby od razu widać było, skąd pochodzi największy ruch.

post-image

Podsumowanie

Opisana konfiguracja pozwala w kilku krokach uzyskać pełną wizualizację geograficzną ruchu na serwerze Nginx — bez konieczności korzystania z zewnętrznych usług chmurowych. Cały stos (Nginx z GeoIP, Alloy, VictoriaLogs, Grafana) można uruchomić na własnej infrastrukturze, zachowując pełną kontrolę nad danymi. Warto pamiętać, że bazy GeoLite2 od MaxMind wymagają cyklicznego aktualizowania (np. raz w miesiącu), aby dane geolokalizacyjne pozostawały aktualne. Można to zautomatyzować za pomocą narzędzia geoipupdate dostępnego w repozytoriach Debiana.