Tag 8: Strukturierte Logs und Log-Alarme
Ziel: notes-api schreibt JSON, du zerlegst und formatierst es mit LogQL, misst die Kardinalität deiner Streams und lässt Loki selbst Alarme auslösen. · Dauer: ca. 60 min · Voraussetzung: Tag 7
Briefing
- Strukturierte Logs sind Logs mit festen Feldern statt freiem Text. JSON ist das verbreitetste Format: Jedes Werkzeug kann es lesen, kein Feld geht beim Zerlegen verloren.
- Jede Kombination von Labels ist in Loki ein eigener Stream. Wenige Streams mit vielen Zeilen sind billig, viele Streams mit wenigen Zeilen teuer. Die Zahl der Streams heißt Kardinalität.
- Loki hat einen Ruler: Er wertet LogQL-Regeln regelmäßig aus und schickt Alarme an denselben Alertmanager wie Prometheus.
- So erfasst du, was keine Metrik zählt – etwa eine Warnung, die nur einmal beim Start im Log steht.
notes-api ── JSON ──► Alloy ──► Loki ── Ruler (Regeln aus ConfigMaps)
│
▼
Alertmanager ──► alarm-echo
Drill 1: JSON statt Text
logging.go kennt beide Formate. Die Umgebungsvariable
entscheidet:
kubectl -n app set env deploy/notes-api NOTES_LOG_FORMAT=json
kubectl -n app rollout status deploy/notes-api
kubectl -n app logs deploy/notes-api --tail 2Erwartet (gekürzt):
deployment "notes-api" successfully rolled out
{"time":"2026-11-05T09:17:08.338477173Z","level":"INFO","msg":"request","method":"GET...
{"time":"2026-11-05T09:17:08.840240332Z","level":"INFO","msg":"request","method":"GET...
- Dieselben Felder wie vorher, nur als JSON.
statusundduration_mssind jetzt echte Zahlen, keine Zeichenketten. - Am Code hat sich nichts geändert:
slogtrennt was geloggt wird vom Format.slog.NewJSONHandlerstattslog.NewTextHandler– mehr ist es nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Zerlegen und formatieren
logcli query --quiet --limit 3 -o raw --since 1m \
'{app="notes-api"} | json | method="POST"
| line_format "{{.method}} {{.path}} {{.status}} {{.duration_ms}}ms"'Erwartet (die Zeiten weichen ab):
POST /notes 201 14ms
POST /notes 201 3ms
POST /notes 201 1ms
| jsonmacht aus jedem Feld ein Label – wie| logfmtan Tag 7.method="POST"filtert nach dem Label aus dem Parser. Es steht hinter| json, weil es das Label vorher nicht gibt.line_formatbaut die Zeile neu, mit Go-Templates wie in den Annotationen der Alarme. Für einen Bericht oder ein Grafana-Panel bleibt nur, was zählt.
Aus Feldern lassen sich auch Zahlen machen. Die mittlere Dauer von
GET /notes in Millisekunden:
logcli instant-query --quiet \
'avg(avg_over_time({app="notes-api"} | json | method="GET"
| unwrap duration_ms [5m]))'Erwartet (ungefähr):
[
{
"metric": {},
"value": [
1793870229.83,
"8.65991902834008"
]
}
]
unwrap duration_msnimmt den Wert des Feldes statt der Zahl der Zeilen.avg_over_timemittelt ihn über fünf Minuten.- Nach ein paar Minuten liefert dieselbe Zahl auch Prometheus. Das Histogramm aus Tag 1 ist dafür viel billiger – Logs auszuwerten heißt, jede Zeile zu lesen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Kardinalität
Wie viele Streams hat Loki für den Namespace app?
logcli series --quiet --analyze-labels '{namespace="app"}' --since 1hErwartet (die Zahlen weichen ab):
Total Streams: 27
Unique Labels: 7
Label Name Unique Values Found In Streams
instance 27 27
pod 14 27
container 5 27
service_name 3 27
app 3 27
job 1 27
namespace 1 27
- 27 Streams für drei Anwendungen in einer Stunde. Der Treiber ist
pod: Jeder Rollout erzeugt neue Pod-Namen und damit neue Streams. Die alten wachsen nicht mehr, bleiben aber bis zur Retention im Index. instancehat noch mehr Werte, weil der Container darin steckt.- Stell dir vor, Alloy würde
statusoderpathals Label setzen: Jeder neue Wert vervielfacht die Streams. Mit einer Benutzer-ID wären es Millionen.
Darum gilt in Loki: Labels beschreiben, woher eine Zeile kommt. Was in ihr steht, bleibt im Text und wird beim Abfragen geparst.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Der Ruler
Der Ruler läuft in Loki schon mit, kennt aber weder Regeln noch
Alertmanager. Ergänze loki.yaml – hier die ganze Datei:
cd ~/obs-lab
cat > loki.yaml <<'EOF'
deploymentMode: Monolithic
loki:
auth_enabled: false
commonConfig:
replication_factor: 1
storage:
type: filesystem
schemaConfig:
configs:
- from: "2026-01-01"
store: tsdb
object_store: filesystem
schema: v13
index:
prefix: index_
period: 24h
limits_config:
retention_period: 72h
compactor:
retention_enabled: true
delete_request_store: filesystem
rulerConfig:
storage:
type: local
local:
directory: /rules
rule_path: /var/loki/rules-temp
alertmanager_url: http://kps-alertmanager.monitoring:9093
enable_api: true
wal:
dir: /var/loki/ruler-wal
singleBinary:
replicas: 1
persistence:
size: 2Gi
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {memory: 512Mi}
read: {replicas: 0}
write: {replicas: 0}
backend: {replicas: 0}
gateway: {enabled: false}
chunksCache: {enabled: false}
resultsCache: {enabled: false}
lokiCanary: {enabled: false}
test: {enabled: false}
sidecar:
rules:
folder: /rules/fake
EOF
helm upgrade loki oci://ghcr.io/grafana-community/helm-charts/loki --version 20.4.1 \
-n monitoring -f loki.yaml --waitErwartet (gekürzt):
Pulled: ghcr.io/grafana-community/helm-charts/loki:20.4.1
...
STATUS: deployed
REVISION: 2
rulerConfig.storagesagt dem Ruler, dass seine Regeln als Dateien unter/rulesliegen. Dorthin schreibt der Sidecar aus Tag 7.- Ohne Mandanten heißt der einzige Mandant in Loki
fake. Regeln liegen pro Mandant in einem Unterordner – darumfolder: /rules/fakefür den Sidecar. alertmanager_urlzeigt auf denselben Alertmanager wie Prometheus.enable_apierlaubt, die geladenen Regeln abzufragen.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Ein Alarm aus dem Log
faults.go schreibt beim Start einmal
faults enabled, wenn eine Störung eingestellt ist. Eine
Metrik dafür gibt es nicht – aber eine Logzeile:
cat > notes-log-rules.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: notes-api-log-rules
namespace: monitoring
labels:
loki_rule: "1"
data:
notes-api.yaml: |
groups:
- name: notes-api.logs
rules:
- alert: NotesApiFaultsEnabled
expr: |
sum by (namespace) (count_over_time(
{app="notes-api"} | json | msg="faults enabled" [10m])) > 0
labels:
severity: info
annotations:
summary: notes-api läuft mit eingebauten Störungen
EOF
kubectl apply -f notes-log-rules.yamlErwartet:
configmap/notes-api-log-rules created
- Das Format ist dasselbe wie bei Prometheus: Gruppen, Regeln,
expr, Labels, Annotationen. Nur die Abfrage ist LogQL. - Die Zeile steht einmal pro Pod im Log.
[10m]hält den Alarm zehn Minuten nach dem letzten Start aktiv. Danach erlischt er, auch wenn die Störung noch eingestellt ist.
Nach einer Minute kennt der Ruler die Regel:
curl -s localhost:30310/prometheus/api/v1/rules \
| jq -c '.data.groups[].rules[] | [.name, .state, .health]'Erwartet:
["NotesApiFaultsEnabled","inactive","ok"]
Unter /prometheus/api/v1/rules antwortet Loki im selben
Format wie Prometheus. Darum zeigt Grafana Regeln aus beiden an
derselben Stelle.
Jetzt eine kleine Störung:
kubectl -n app set env deploy/notes-api NOTES_DELAY=50ms
kubectl -n app rollout status deploy/notes-apiErwartet (letzte Zeile):
deployment "notes-api" successfully rolled out
Nach etwa einer Minute:
amtool alert query alertname=NotesApiFaultsEnabledErwartet:
Alertname Starts At Summary...
NotesApiFaultsEnabled 2026-11-05 09:19:23 UTC notes-api läuft mit eingebauten Störu...
Den Alarm hat nicht Prometheus ausgelöst, sondern Loki. Für den Alertmanager macht das keinen Unterschied – auch alarm-echo bekommt ihn.
Störung zurücknehmen:
kubectl -n app set env deploy/notes-api NOTES_DELAY-Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kubectl -n app set env deploy/notes-api --list | grep LOG_FORMATErwartet:
NOTES_LOG_FORMAT=json
NOTES_LOG_FORMAT=json
Einmal für notes-api, einmal für den Init-Container
migrate – set env ändert alle Container. JSON
bleibt ab jetzt eingeschaltet.
kubectl -n monitoring logs deploy/alarm-echo | grep '^{' \
| jq -r '.json.alerts[].labels.alertname' | sort -uErwartet:
NotesApiDown
NotesApiErrors
NotesApiFaultsEnabled
NotesApiSlow
Alle Alarme dieses Buchs bisher, drei aus Prometheus, einer aus Loki.
Challenge
Schreibe eine zweite Log-Regel NotesApiServerErrors:
Sie soll feuern, wenn notes-api in fünf Minuten mehr als 20 Zeilen mit
level ERROR schreibt. Löse sie mit
NOTES_ERROR_RATE=0.2 aus.
Hinweis: Eine ConfigMap darf mehrere Regeln enthalten. Ändere die Datei und wende sie erneut an.
Lösung
cat > notes-log-rules.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: notes-api-log-rules
namespace: monitoring
labels:
loki_rule: "1"
data:
notes-api.yaml: |
groups:
- name: notes-api.logs
rules:
- alert: NotesApiFaultsEnabled
expr: |
sum by (namespace) (count_over_time(
{app="notes-api"} | json | msg="faults enabled" [10m])) > 0
labels:
severity: info
annotations:
summary: notes-api läuft mit eingebauten Störungen
- alert: NotesApiServerErrors
expr: |
sum by (namespace) (count_over_time(
{app="notes-api"} | json | level="ERROR" [5m])) > 20
labels:
severity: warning
annotations:
summary: "notes-api: {{ $value }} Fehlerzeilen in 5 Minuten"
EOF
kubectl apply -f notes-log-rules.yaml
kubectl -n app set env deploy/notes-api NOTES_ERROR_RATE=0.2Nach zwei Minuten:
amtool alert query alertname=NotesApiServerErrorsErwartet:
Alertname Starts At Summary...
NotesApiServerErrors 2026-11-05 09:22:23 UTC notes-api: 178 Fehlerzeilen in 5 Minut...
Zurücknehmen:
kubectl -n app set env deploy/notes-api NOTES_ERROR_RATE-Metrik oder Log? NotesApiErrors aus Tag 4 misst dasselbe genauer und billiger. Log-Regeln lohnen sich für Ereignisse, die keine Metrik kennt.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Log-Format festlegen: Ein gemeinsames JSON-Schema für alle Anwendungen – Feldnamen für Zeit, Level, Nachricht, Trace-ID – spart in jeder Abfrage einen Sonderfall. OpenTelemetry definiert dafür die Semantic Conventions.
- Structured Metadata: Loki 3 kann Felder wie
trace_idneben der Zeile speichern, ohne sie zu Labels zu machen. Sie sind filterbar, erhöhen aber die Kardinalität nicht. - Kosten im Blick:
logcli series --analyze-labelsgehört in jede regelmäßige Prüfung. Ein einziges falsches Label kann den Speicher eines Loki vervielfachen.