Telemetrie und Logging

Diese Seite beschreibt den aktuell belegten Observability-Schnitt im Workspace. Sie trennt bewusst Telemetrie, Logging, Monitoring, Audit und SIEM, weil der derzeit verifizierte Android-plus-Cloud-Pfad noch keine vollstaendige produktisierte Telemetrie-Pipeline mit Run-Compare bereitstellt.

Achtung

Nicht als aktueller Runtime-Stand belegt sind heute unter anderem:

• eine separate Telemetrie-Plane mit eigener API oder eigenem Store
• ein durchgaengiger Run-Compare-Schnitt ueber die heute belegten app_launch-, status_refresh-, alert_read-, device_register-, event_submit-, incident_read- und job_read-Slices hinaus
• eine dedizierte Compare-UI oder Compare-API jenseits der kleinen CLI-Berichte ueber App- und Backend-Logzeilen
• feste externe Aufbewahrungsfristen fuer Telemetriedaten
• lokale AES-256-Logverschluesselung auf dem Android-Geraet
• ein eigener Metrics- oder /healthz-Endpoint

Was heute wirklich verifiziert ist

• Android ist die einzige runtime-verifizierte Device-Plattform im aktuellen Workspace.
• Der aktuell belegte Android-MVP nutzt POST /devices, POST /events, GET /status, GET /alerts, GET /incidents, GET /jobs, GET /jobs/{id}, GET /traces/{id} und GET /traces/{id}/steps gegen lokales superheld-cloud.
• Der verifizierte lokale Geraetepfad laeuft ueber USB-Tablet plus adb reverse tcp:8080 tcp:8080 gegen http://127.0.0.1:8080.
• Der Backend-Prozess schreibt Basis-Startmeldungen, Store-Fallbacks und Persistenzfehler nach stdout oder stderr.
• Fuer den Android-Gold-Flow app_launch existiert jetzt ein erster lokaler Telemetrie-Slice: die App persistiert und zeigt in der Konfigurationskarte Latest app launch run, Window, Result, Device, Tenant und App version; derselbe Start loggt lokal nach logcat unter SuperheldTelemetry eine comparebare Zeile telemetry flow=app_launch ... method=APP path=/main_activity ... backend_version=app_local.
• Fuer den Android-Gold-Flow status_refresh existiert jetzt ein kleiner gemeinsamer Telemetrie-Slice: die App sendet X-Superheld-Flow, X-Superheld-Run-Id, X-Superheld-App-Version, X-Superheld-Tenant-Id und X-Superheld-Device-Id, der Backend-Read-Pfad echoet X-Superheld-Run-Id und X-Superheld-Backend-Version, emittiert bei strukturierten Fehlern zusaetzlich X-Superheld-Error-Code, und dieselbe run_id erscheint im lokalen Backend-Log fuer /status, bei Fehlern inklusive error_code=....
• Fuer den Android-Read-Pfad alert_read nutzt die App denselben Header-Satz jetzt als eigenen Slice fuer GET /alerts; die Alert-Karte zeigt Latest alert run, Window, Result, Backend version und bei Fehlern ein dediziertes Error code, und dieselbe run_id erscheint im lokalen Backend-Log fuer /alerts.
• Fuer den Android-Gold-Flow device_register nutzt die App denselben Header-Satz jetzt auch auf POST /devices; die Registrierungskarte zeigt Latest registration run, Window, Result, Backend version und bei Fehlern ein dediziertes Error code, und dieselbe run_id erscheint im lokalen Backend-Log fuer /devices.
• Fuer den Android-Gold-Flow event_submit nutzt die App denselben Header-Satz jetzt auch auf POST /events; die Event-Karte zeigt Latest event run, Window, Result, Backend version und bei Fehlern ein dediziertes Error code, und dieselbe run_id erscheint im lokalen Backend-Log fuer /events.
• Fuer den Android-Gold-Flow incident_read nutzt die App denselben Header-Satz jetzt als eigenen Slice fuer GET /incidents und den nachgeladenen letzten sichtbaren Incident ueber GET /incidents/{id}; die Incident-Karte zeigt Latest incident run, Window, Result, Backend version und bei Fehlern ein dediziertes Error code, und dieselbe run_id erscheint im lokalen Backend-Log fuer beide Incident-Reads.
• Fuer den Android-Job-/Trace-Pfad job_read nutzt die App denselben Header-Satz jetzt als eigenen Slice fuer GET /jobs, den nachgeladenen letzten sichtbaren Job ueber GET /jobs/{id} sowie bei vorhandener trace_id fuer GET /traces/{id} und GET /traces/{id}/steps; die Job-Karte zeigt Latest job run, Window, Result, Backend version und bei Fehlern ein dediziertes Error code, und dieselbe run_id erscheint im lokalen Backend-Log fuer die Job- und Trace-Reads.
• Erste kleine Run-Compare-Berichte existieren jetzt ueber go run ./cmd/telemetrycompare: ein verifizierter lokaler Vergleich des app-lokalen Gold-Flows app_launch stellte aus exportierten logcat-Zeilen app-launch-772767fb-f8dd-42b1-81d4-1558fac5b636 gegen app-launch-efcaa925-326b-47f7-af08-03d52bedbd09 gegenueber und machte fuer APP /main_activity den Delta-Wechsel von 385ms auf 366ms sichtbar; der verifizierte lokale Vergleich des Gold-Flows status_refresh stellte status-refresh-d8a9ae69-972f-45de-818f-3541d79e92c4 gegen status-refresh-5c829384-e399-4b81-aee8-9c931389e08b aus derselben server.log gegenueber und machte den Wechsel von GET /status 200 success auf 403 failure mit error_code=insufficient_scope und dem Delta von 183µs auf 83µs sichtbar, waehrend im selben Fehlerrun alert_read, incident_read und job_read unter eigenen run_id-Werten weiter 200 success blieben; ein weiterer verifizierter lokaler Vergleich des Read-Slices alert_read stellte alert-read-942bc64f-6cac-4daa-909e-efa64112c556 gegen alert-read-90df8959-d5b9-41de-9dd5-46bc9db48c86 gegenueber und machte auf GET /alerts den Wechsel von 200 success auf 403 failure mit error_code=insufficient_scope sichtbar; ein weiterer verifizierter lokaler Vergleich des Gold-Flows device_register stellte device-register-05aa2ac5-fc1c-432a-8735-64375aea2844 gegen device-register-83ba260e-6db7-4103-a401-2492a59e7518 gegenueber und machte auf POST /devices den Wechsel von 201 success auf 403 failure mit error_code=insufficient_scope sichtbar; ein weiterer verifizierter lokaler Vergleich des Gold-Flows event_submit stellte event-submit-76e907bb-731e-43e6-ae96-d7dff8c8acbc gegen event-submit-114e32c8-ac30-4325-95c5-71a7c364ec6d gegenueber und machte auf POST /events den Wechsel von 202 success auf 403 failure mit error_code=insufficient_scope sichtbar; ein weiterer verifizierter lokaler Vergleich des Gold-Flows incident_read stellte incident-read-ea31daf4-67d0-4a4b-8511-373c4c78bb70 gegen incident-read-89ec180d-b38c-4416-bafc-a3efc04ecd1a gegenueber und machte den Wechsel von GET /incidents 200 success plus nachgeladenem GET /incidents/{id} auf 403 failure mit error_code=insufficient_scope sichtbar; ein weiterer verifizierter lokaler Vergleich des Job-/Trace-Slices job_read stellte job-read-750be845-48f0-4344-9e29-2702a0ffd2ee gegen job-read-e2d9a9ca-a82b-4bff-8ceb-ba22954039ae gegenueber und machte den Wechsel von erfolgreichem GET /jobs plus nachgeladenem GET /jobs/{id}, GET /traces/{id} und GET /traces/{id}/steps auf GET /jobs 403 failure mit error_code=insufficient_scope sichtbar, waehrend die nachgelagerten Reads im Fehlerrun als not present erschienen; derselbe CLI-Schnitt kann die automatische Run-Auswahl optional auf denselben tenant_id, device_id, app_version, dieselbe backend_version, denselben result oder denselben error_code eingrenzen. Verifiziert ist dieser neue Filterpfad bereits fuer status_refresh-Laeufe mit result=failure plus error_code=unauthorized sowie fuer device_register-Laeufe mit result=failure plus error_code=insufficient_scope.
• Token- und Job-Review-Audits sind ueber GET /tokens/audit, GET /tokens/{id}/audit, GET /jobs/audit und GET /jobs/{id}/audit tenant-scoped lesbar.
• Webhooks und GET /events sind die aktuell belegten Export- und Integrationspfade fuer event-zentrierte externe Systeme.

Begriffe sauber trennen

Bereich	Heutiger belegter Stand
Telemetrie	Teilweise vorhanden. Ein app-lokaler Slice fuer app_launch sowie app-plus-cloud-Slices fuer status_refresh, alert_read, device_register, event_submit, incident_read und job_read sind belegbar; dazu kommen jetzt kleine CLI-Compare-Berichte ueber exportierte App-logcat-Zeilen fuer app_launch sowie ueber korrelierte Backend-Logzeilen fuer status_refresh, alert_read, device_register, event_submit, incident_read und job_read, deren automatische Run-Auswahl optional auf denselben Tenant, dasselbe Geraet, dieselbe App-/Backend-Version, denselben result oder denselben error_code eingegrenzt werden kann. Offen bleiben breitere Delta-Sichten und eine produktisierte Telemetrie-Plane.
Logging	Backend-Meldungen laufen ueber den Prozess-Output. Die Android-App zeigt Fehler fuer Konfiguration, Auth, Scope, Tenant und Netzwerk sichtbar im UI.
Monitoring	GET /status ist der leichtgewichtige Runtime-Check fuer den app-relevanten Schutzstatus. Eine separate Metrics- oder Health-Plane ist heute nicht belegt.
Audit	Token-Lifecycle und Job-Review-Entscheidungen laufen ueber hash-verknuepfte interne Audit-Logs und sind ueber die Audit-Endpunkte lesbar.
SIEM	Der aktuelle verifizierte Exportpfad ist event-zentriert: GET /events oder signierte Webhook-Auslieferung. Jobs, Incidents und Traces sind heute Operator-Reads, kein eigener SIEM-Exportstrom.

Operatoren-Schnellreferenz: Verifiziert vs. Zielarchitektur

Bereich	Verifizierte Endpunkte / Pfade	Noch Zielarchitektur
Audit	GET /tokens/audit, GET /tokens/{id}/audit, GET /jobs/audit, GET /jobs/{id}/audit — hash-verknuepft, tenant-scoped	Externer Audit-Export, Audit-Retention-SLA, Admin-/Operator-spezifische Audit-Views
Logging	Backend stdout/stderr mit telemetry flow= und tenant_hint_mismatch-Zeilen; Android logcat unter SuperheldTelemetry	Strukturiertes JSON-Log-Format, Log-Aggregation, Log-Rotation-Konfiguration, Log-Shipping
Monitoring	GET /status als leichtgewichtiger Runtime-Check	Separater /healthz- oder /readiness-Endpoint, Prometheus-Metrics, Alerting-Regeln, Dashboard-Templates
SIEM	GET /events (Cursor-Pagination) und signierte Webhooks (HMAC-SHA256, 3 Retries, 7-Tage-DLQ)	CEF-, LEEF-, OCSF-Formate, Cloud-seitige Threat-Intelligence-Anreicherung, IOC-Korrelation
Telemetrie	7 Gold-Flows mit run_id-Korrelation (App-Headers + Backend-Echo), CLI-Compare ueber cmd/telemetrycompare	Telemetrie-Storage-API, Compare-UI/Dashboard, Langzeit-Run-Historie, OpenTelemetry-Export

Fuer Details zu den verifizierten Pfaden pro Bereich siehe die Abschnitte weiter unten. Fuer die vollstaendige Spezifikation der Observability-Trennung siehe die Observability Separation Spec in superheld-architecture.

Aktueller Android-plus-Cloud-Korrelationspfad

Heute korrelierbare IDs im verifizierten MVP:

Feld	Wo es heute sichtbar ist	Zweck
tenant_id	Device-, Event-, Alert-, Incident-, Job- und Trace-Antworten	Tenant-Isolation und Operator-Korrelation
device_id	Device-Registrierung, Event-Payloads, Alerts, Incidents	Bezug zwischen Android-Geraet und Backend-Objekten
event_id	POST /events, GET /events, Alerts, manche Incident- oder Job-Eingaben	Korrelation des Event-Submit-Pfads
alert_id	GET /alerts	User-visible Alert-Referenz
incident_id	GET /incidents, GET /incidents/{id}	Security-Incident-Referenz
job_id	GET /jobs, GET /jobs/{id}	Asynchroner Workflow-Lauf
trace_id	GET /jobs, GET /jobs/{id}, GET /traces/{id}, GET /traces/{id}/steps	Feinste heute belegte Korrelation fuer den Job- und Trace-Pfad
run_id	Android-Konfigurationskarte fuer app_launch, Android-Statuskarte, Alert-, Registrierungs-, Event-, Incident- und Job-Karte, X-Superheld-Run-Id auf korrelierten Antworten, lokale App-logcat- und Cloud-Logzeilen	Korrelation einzelner app_launch-, status_refresh-, alert_read-, device_register-, event_submit-, incident_read- und job_read-Laeufe
app_version	Android-Konfigurationskarte, lokale App-logcat-Zeilen, X-Superheld-App-Version auf korrelierten Requests, lokale Cloud-Logzeilen	Vergleich verschiedener Android-Builds
backend_version	Android-Statuskarte, Alert-, Registrierungs-, Event-, Incident- und Job-Karte, X-Superheld-Backend-Version auf korrelierten Antworten, lokale Cloud-Logzeilen	Vergleich verschiedener Backend-Builds
started_at, finished_at, result	Android-Konfigurationskarte fuer app_launch, Android-Statuskarte, Alert-, Registrierungs-, Event-, Incident- und Job-Karte, lokale App-logcat- und Cloud-Logzeilen der verifizierten Gold-Flows	kleines Laufzeit- und Ergebnisfenster fuer die ersten Gold-Flows
error_code	Android-Statuskarte, Alert-, Registrierungs-, Event-, Incident- und Job-Karte bei Fehlerlaeufen, X-Superheld-Error-Code auf strukturierten API-Fehlerantworten, lokale Cloud-Logzeilen fehlgeschlagener korrelierter Requests	maschinenlesbarer Fehlergrund fuer Compare- und Troubleshooting-Sichten

Wichtig:

• Ein erster app-lokaler Slice gilt heute fuer app_launch; die ersten gemeinsamen App-plus-Cloud-Slices gelten derzeit fuer status_refresh, alert_read, device_register, event_submit, incident_read und job_read.
• Die App sendet tenant_id und device_id auf diesem Slice heute als Telemetrie-Header fuer die Korrelation; Autorisierung bleibt weiter tenant-gebunden ueber das API-Token.
• Erste CLI-Compare-Berichte sind jetzt ueber go run ./cmd/telemetrycompare -log <logfile> -flow <flow> fuer den app-lokalen Flow app_launch sowie fuer die backendgeloggten Flows status_refresh, alert_read, device_register, event_submit, incident_read und job_read belegt; ohne -run-a und -run-b vergleicht das Tool die letzten beiden sichtbaren Runs desselben Flows, optional eingegrenzt ueber -tenant-id, -device-id, -app-version, -backend-version, -result und -error-code.
• Das dedizierte error_code ist fuer diese verifizierten Gold-Flows jetzt als eigener Feldpfad belegbar; offene Arbeit bleibt die breitere Compare- oder Delta-Sicht ueber mehrere Laeufe, App-Versionen oder Releases hinweg.

Das heute wirklich kanonische Event-Objekt

Fuer den verifizierten Android-Write-Pfad ist das Event-Objekt aus POST /events die aktuell belastbare kanonische Event-Form. Es ist nicht automatisch gleichbedeutend mit einer vollstaendigen Produkt-Telemetrie-Pipeline.

{
  "event_id": "evt-android-demo-1",
  "type": "risk.event.created",
  "tenant_id": "tenant-local",
  "device_id": "android-device-1",
  "timestamp": "2026-03-17T01:10:00Z",
  "threat_category": "malicious_app",
  "confidence": 0.92,
  "action_taken": "warn",
  "policy_id": "pol_android_mvp_v1",
  "severity": "high",
  "description": "Suspicious Android app install observed",
  "indicators": ["package:com.example.sideload"]
}

Feld	Heutiger Status
event_id	Eindeutige Event-Referenz fuer Event-Submit, Event-Read und Folgeobjekte
type	Aktueller Workspace-Discriminator fuer Detection Events
tenant_id	Kanonisches Tenant-Feld fuer Autorisierung und Zustellung
device_id	Android-Geraetereferenz aus dem verifizierten Registrierungs- und Event-Pfad
timestamp	ISO-8601-Zeitstempel des Event-Objekts
threat_category, confidence, action_taken, policy_id, severity	Aktueller Detection-/Policy-Schnitt des Event-Pfads
description, indicators	Im aktuellen Android-Demo-Pfad mitgefuehrt und vom Backend akzeptiert

Retention und Persistenz im Ist-Stand

Die aktuellen Retention-Aussagen muessen sich an den belegten Runtime-Backends orientieren, nicht an frueheren Produktzielwerten.

Datentyp	Aktueller Stand
Security Events	Runtime-Store-abhaengig: in-memory, lokale JSON-Datei oder SQLite
Security Incidents	Runtime-Store-abhaengig: in-memory, lokale JSON-Datei oder SQLite
Token- und Job-Audit	Interne Audit-Logs im konfigurierten Runtime-Backend, aber ohne extern festgezurrte Retention-Garantie
Webhook-DLQ	7 Tage Retention im aktuellen Runtime-Vertrag
Telemetrie als eigener Produkttyp	Keine finalisierte externe Retention- oder Exportgarantie belegt

Lokale Operator-Sicht fuer den verifizierten MVP

Fuer den heute belegten Android-plus-Cloud-Pfad sind diese Sichten praktisch:

• GET /status fuer den app-relevanten Schutzstatus
• GET /alerts fuer die sichtbare erste Alert-Seite
• GET /incidents und GET /incidents/{id} fuer tenant-scoped Security-Incidents aus akzeptierten High-Severity-Alerting-Events oder Security-Monitor-Faellen
• GET /jobs und GET /jobs/{id} fuer den asynchronen Workflow-Zustand
• GET /traces/{id} und GET /traces/{id}/steps fuer die feinste heute verifizierte Job-Korrelation
• GET /events oder Webhooks fuer event-zentrierte Exportfaelle
• GET /tokens/audit und GET /jobs/audit fuer tenant-scoped Audit-Reads

Mehr Details fuer den lokalen Android-Cloud-Lauf: Lokales Android-Cloud-Ops-Runbook.

Was fuer eine breitere Run-Compare-Sicht noch fehlt

Die ersten kleinen Slices ueber app_launch, status_refresh, alert_read, device_register, event_submit, incident_read und job_read decken heute mindestens run_id, app_version, started_at, finished_at und result ab; die app-plus-cloud-Slices fuer status_refresh, alert_read, device_register, event_submit, incident_read und job_read zeigen zusaetzlich backend_version und bei Fehlern error_code. Verifizierte Compare-Berichte existieren jetzt fuer app-lokale app_launch-Runs sowie fuer backendgeloggte status_refresh-, alert_read-, device_register-, event_submit-, incident_read- und job_read-Runs und koennen ihre automatische Run-Auswahl optional auf denselben Tenant, dasselbe Geraet, dieselbe App-/Backend-Version, denselben result oder denselben error_code eingrenzen. Weiter offen bleiben fuer eine breitere Compare-Sicht mindestens:

• Delta-Berichte ueber mehrere Releases, Geraete oder Build-Kombinationen hinweg
• eine explizit dokumentierte Retention- und Exportstrategie fuer Telemetrie als eigenen Produkttyp

Solange diese Punkte offen sind, sollte die aktuelle Runtime trotz der ersten CLI-Compare-Berichte und der kleinen app_launch-, status_refresh-, alert_read-, device_register-, event_submit-, incident_read- und job_read-Slices nicht als fertige Telemetrie- oder Compare-Loesung beschrieben werden.

Verwandte Seiten

• API-Uebersicht
• Authentifizierung
• SIEM-Integration
• Lokales Android-Cloud-Ops-Runbook

Architektur-Spezifikationen

Die folgenden Spezifikationen in superheld-architecture definieren die Zielarchitektur und den verifizierten Stand fuer Observability und Telemetrie:

• specs/observability-separation.md — Klare Grenzen zwischen Audit, Logging, Monitoring, SIEM und Telemetrie mit verifiziertem Ist-Stand vs Zielarchitektur
• specs/telemetry-run-compare.md — Instrumentierungsmodell, Mindestfelder fuer Compare-Slices, Run-Compare-Ausgabeformat und verifizierte Abdeckung fuer alle sieben Gold-Flows