Technische Dokumentation¶
Logfileimport per Logimporter¶
Mit Hilfe des Audalaxy-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 Audalaxy-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:
Linux 64Bit: https://streamabc-sw.s3.eu-central-1.amazonaws.com/logimporter/logimporter-linux-amd64
Windows 64Bit: https://streamabc-sw.s3.eu-central-1.amazonaws.com/logimporter/logimporter.exe
MacOS: https://streamabc-sw.s3.eu-central-1.amazonaws.com/logimporter/logimporter-mac
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 Audalaxy, 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 Audalaxy 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 startEinlesen der Datei am Anfang oder Ende beginnen (Default ist Ende, um nur neue Zeilen einzulesen).
-pollingPolling statt fsnotify benutzen, um neue Daten zu ermitteln.
-scanheaderSollte 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 Audalaxy übertragen. Dies ist der Standard und sollte nur geändert werden, wenn explizit von Audalaxy gefordert.
Weitere Flags für output:amqp:
-origin=xx
Pflichtfeld. Diese Kennung wird von Audalaxy mitgeteilt und wird benutzt, um Zugriffe über den Logimporter korrekt zuzuordnen.
-streamwatchOptional. Damit wird eine zusätzliche Belieferung der Audalaxy Streamwatch aktiviert. Nur verwenden, wenn von Audalaxy 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:
-outputLogzeilen werden testweise ausgegeben.
output:http
Logs werden über HTTP an einen Ingest-Endpunkt gesendet. Alternative, nur wenn AMQP nicht funktioniert und von Audalaxy angefordert wird.
Weitere Flags für output:http:
-origin=xx
Pflichtfeld. Diese Kennung wird von Audalaxy mitgeteilt und wird benutzt um Zugriffe über den Logimporter korrekt zuzuordnen.
-streamwatchOptional. Damit wird eine zusätzliche Belieferung der Audalaxy Streamwatch aktiviert. Nur verwenden, wenn von Audalaxy 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=Audalaxy 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 Audalaxy 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.