Zum Inhalt springen
Trainingslager IT-Trainingslager

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 2

Erwartet (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. status und duration_ms sind jetzt echte Zahlen, keine Zeichenketten.
  • Am Code hat sich nichts geändert: slog trennt was geloggt wird vom Format. slog.NewJSONHandler statt slog.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
  • | json macht aus jedem Feld ein Label – wie | logfmt an Tag 7.
  • method="POST" filtert nach dem Label aus dem Parser. Es steht hinter | json, weil es das Label vorher nicht gibt.
  • line_format baut 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_ms nimmt den Wert des Feldes statt der Zahl der Zeilen. avg_over_time mittelt 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 1h

Erwartet (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.
  • instance hat noch mehr Werte, weil der Container darin steckt.
  • Stell dir vor, Alloy würde status oder path als 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 --wait

Erwartet (gekürzt):

Pulled: ghcr.io/grafana-community/helm-charts/loki:20.4.1
...
STATUS: deployed
REVISION: 2
  • rulerConfig.storage sagt dem Ruler, dass seine Regeln als Dateien unter /rules liegen. Dorthin schreibt der Sidecar aus Tag 7.
  • Ohne Mandanten heißt der einzige Mandant in Loki fake. Regeln liegen pro Mandant in einem Unterordner – darum folder: /rules/fake für den Sidecar.
  • alertmanager_url zeigt auf denselben Alertmanager wie Prometheus.
  • enable_api erlaubt, 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.yaml

Erwartet:

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-api

Erwartet (letzte Zeile):

deployment "notes-api" successfully rolled out

Nach etwa einer Minute:

amtool alert query alertname=NotesApiFaultsEnabled

Erwartet:

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_FORMAT

Erwartet:

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 -u

Erwartet:

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.2

Nach zwei Minuten:

amtool alert query alertname=NotesApiServerErrors

Erwartet:

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_id neben 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-labels gehört in jede regelmäßige Prüfung. Ein einziges falsches Label kann den Speicher eines Loki vervielfachen.