Technische Dokumentation

Logfileimport per Logimporter

Mit Hilfe des QuantumCast-Logimporter ist es möglich die Logfiles aller gängigen Streaming-Server an das Auswertungssystem zu übermitteln. Die Daten werden vor der Übermittlung anonymisiert und bereits so aufgearbeit, dass alle Datenschutzregelungn der DSGVO eingehalten werden.

Der QuantumCast-Logimporter ist eine Software, welche als eigenständiger Systemdienst auf selbstverwalteten Streaming-Servern installiert werden kann.

Hier steht jeweils die neueste Version zum Download bereit:

Der Logimporter unterstützt verschiedene Eingangsformen, Logformate und Ausgabemöglichkeiten. Die Konfiguration erfolgt über Parameter oder Environment-Variablen, die beim Programmaufruf angegeben werden müssen.

Dabei sind immer drei Bereiche nötig: “input” definiert, woher die Logs kommen (z.B. “tail” auf eine aktive Logdatei, eine einzelne vorhandene Logdatei einlesen oder mehrere), “parser” konfiguriert das zu parsende Logformat und “output” definiert wie die Daten ausgegeben werden (z.B. Ingest bei QuantumCast, Testausgabe auf Konsole).

Input, Parser und Output müssen zwingend immer beim Aufruf angegeben werden. Es muss immer ein “Origin” angegeben werden. Dieser ist eine individuelle Kennung, die Ihnen von QuantumCast mitgeteilt wird.

Der allgemeine Aufruf folgt diesem Muster:

logimporter input:file –path=”./logs/access.log” parser:icecast output:amqp –origin=xxx

Hint

In den Beispielen das xxx bei -origin=xxx durch den jeweiligen Origin-Wert ersetzen.

Mit –help kann nach jedem Plugin eine kurze Hilfe über mögliche Parameter angezeigt werden.

./logimporter -help

Input Plugins für Logfiles

Das Input-Plugin wird mit dem Prefix “input:” angegeben.

Es gibt folgende Inputs, von denen immer nur eines verwendet werden kann:

input:file –path=/pfad/zur/Datei

Vollständiges Einlesen einer einzelnen Datei. Es muss der Pfad zur Datei angegeben werden. Es können GZ-komprimierte Dateien verwendet werden. Diese müssen die Endung .gz haben.

input:fileglob –path=/pfad/zu/Dateien*.log

Vollständiges Einlesen mehrerer Dateien. Es muss ein Pfad mit Glob-Pattern angegeben werden. Es können GZ-komprimierte Dateien verwendet werden. Diese müssen die Endung .gz haben.

input:tail –path=/pfad/zur/Datei.log

Einlesen von Logzeilen einer Datei während sie geschrieben wird. Das Programm bleibt so lange aktiv, bis es manuell gestoppt wird und sendet automatisch neue Zeilen.

In der Regel werden rotierte Logfiles erkannt, wenn der Name gleich bleibt.

Weitere Flags für input:tail:

-whence=end oder start

Einlesen der Datei am Anfang oder Ende beginnen (Default ist Ende, um nur neue Zeilen einzulesen).

-polling

Polling statt fsnotify benutzen, um neue Daten zu ermitteln.

-scanheader

Sollte beim Tail von AIS-Logs verwendet werden, um Felderkonfiguration zu ermitteln, die in den ersten Zeilen der Datei angegeben werden.

Hint

Zur Überwachung des Inputs bietet sich die Nutzung des Healthcheck an.

Parser Plugins für Streaming-Server

Das Parser-Plugin wird mit dem Prefix “parser:” angegeben.

Es gibt folgende Parser, es kann immer nur einer verwendet werden:

parser:icecast

Logs haben Icecast-Format.

parser:ais

Logs haben AIS Sessionlog-Format.

-version=ais8

Es gibt verschiedene Formate, die normalerweise anhand der Felder am Anfang der Datei erkannt werden. Falls es Probleme bei der Erkennung gibt, kann hier ein Format vorgegeben werden.

Output Plugins für die Datenübermittlung

Das Output-Plugin wird mit dem Prefix “output:” angegeben.

Es gibt folgende Outputs, von denen immer nur eines verwendet werden kann:

output:amqp

Logs werden über AMQP Messages an QuantumCast übertragen. Dies ist der Standard und sollte nur geändert werden, wenn explizit von QuantumCast gefordert.

Weitere Flags für output:amqp:

-origin=xx

Pflichtfeld. Diese Kennung wird von QuantumCast mitgeteilt und wird benutzt, um Zugriffe über den Logimporter korrekt zuzuordnen.

-streamwatch

Optional. Damit wird eine zusätzliche Belieferung der QuantumCast Streamwatch aktiviert. Nur verwenden, wenn von QuantumCast expliziert angefordert.

output:noop

Testausgabe “dry run”. Es werden keine Daten gesendet, es kann aber geprüft werden, ob der Import funktioniert.

Weitere Flags für output:noop:

-output

Logzeilen werden testweise ausgegeben.

output:http

Logs werden über HTTP an einen Ingest-Endpunkt gesendet. Alternative, nur wenn AMQP nicht funktioniert und von QuantumCast angefordert wird.

Weitere Flags für output:http:

-origin=xx

Pflichtfeld. Diese Kennung wird von QuantumCast mitgeteilt und wird benutzt um Zugriffe über den Logimporter korrekt zuzuordnen.

-streamwatch

Optional. Damit wird eine zusätzliche Belieferung der QuantumCast Streamwatch aktiviert. Nur verwenden, wenn von QuantumCast expliziert angefordert.

Es empfiehlt sich, den Logimporter über ein Start-Script zu verwenden, z.B. ein Systemd Unit-File. Das Programm läuft dauerhaft und versucht selbständig Verbindungen neu aufzubauen. Log-Rotation wird automatisch erkannt, wenn der Dateiname gleichbleibt.

Beim AIS unbedingt das Session-Log verwenden und nicht das Access-Log. Nur das enthält die Dauer der Verbindung. Beim Icecast dagegen das Access-Log.

Beim Logimporter dann entsprechend immer den Typ der Datei angeben.

Hier ist ein Beispiel für eine systemd Unit-Datei logimporter.service

[Unit]
Description=QuantumCast Logimporter
Wants=network-online.target
After=network-online.target

[Service]
ExecReload=/bin/kill -HUP $MAINPID
ExecStart=/usr/local/bin/logimporter-linux-amd64 input:tail –path=/var/log/icecast/access.log parser:icecast output:amqp –origin=xxx
User=icecast
KillMode=process
KillSignal=SIGINT
LimitNOFILE=infinity
LimitNPROC=infinity
Restart=on-failure
RestartSec=2
StartLimitBurst=3
StartLimitIntervalSec=10
TasksMax=infinity

[Install]
WantedBy=multi-user.target

Angepasst an die jeweiligen Bedingungen werden muss:

  • Pfad zum Programm (hier /usr/local/bin/logimporter-linux-amd64)

  • Pfad zum Log (hier /var/log/icecast/access.log)

  • User (hier icecast)

Nachliefern von Daten im Fehlerfall

Es gibt seit Version v3.1.0 zwei neue Flags -after="YYYY-MM-DD HH:mm:ss und -before="YYYY-MM-DD HH:mm:ss um nur Logs vor oder nach einem angegebenen Datum zu senden. Beide Flags können auch kombiniert werden (also nur nach einem Zeitpunkt aber zwingend vor einem weiteren). Beides sind globale Flags und müssen vor dem Input angegeben werden.

Wenn der Zeitpunkt eines Fehlers ermittelt wurde (z.B. anhand lokaler Fehlermeldungen oder im Dashboard, wenn Graphen enden), muss die Datei des Tages mit dem -after Flag verwendet werden, um die fehlenden Daten nachzuliefern.

Wenn man weiß, ab wann es wieder funktioniert hat (z.B. weil man da neu gestartet hat), sollte dieser Zeitpunkt als -before angegeben werden.

Ein vollständiger Aufruf sieht so aus:

logimporter -after="2022-03-04 19:15:25" input:file –path="./logs/access-2022-03-04.log.gz" parser:icecast output:amqp –origin=xxx

Healthcheck

Wenn über das „-listen”-Flag eine Binding-Adresse/Port angegeben wird, startet der Importer einen HTTP-Server und aktiviert dort einen Endpunkt „/health”.

Beispiel:

-listen=127.0.0.1:8080 startet den HTTP-Server und bindet ihn an die IP 127.0.0.1 und den Port 8080. Mit http://127.0.0.1:8080/health kann der Healthcheck aufgerufen werden. Er liefert HTTP-Status 200 wenn alles ok ist. Wurden nicht genügend neue Logzeilen per Input Plugins für Logfiles im Interval „-alertInterval 300” (default 300s) verarbeitet, wird Status 500 zurückgegeben.

Wird für -listen die IP weggelassen, hört der Healthcheck auf alle IPs, die konfiguriert sind -listen :8080

Logfileimport per SFTP

Hier kann der Upload der Logfiles erfolgen:

SFTP-Host: logimport.quantumcast.cloud
Port: 2022

Benutzername und Passwort sind individuell pro Kunden und werden von QuantumCast zur Verfügung gestellt.

Die Logdateien müssen in den Hauptordner hochgeladen werden. Unterordner werden nicht unterstützt.

Die Dateien können unkomprimiert oder komprimiert (GZIP mit Dateiendung .gz) verarbeitet werden.

Sobald eine Datei verarbeitet wurde, wird sie automatisch in den Ordner “processed” verschoben.