Lokales App-Logging (Variante A): OpenTelemetry → JSON-Lines-Datei, Dev-Mode-UI zum Aktivieren/Einsehen/Teilen (Default: aus)

## Kontext & Motivation

Wir wollen Logs lokal auf dem Gerät sammeln (Datenminimierung) und Nutzer:innen im Dev-Mode-Screen das Aktivieren, Einsehen und manuelle Teilen der Logs ermöglichen. Es werden keine Logs automatisch an Server gesendet. Das erfüllt das Prinzip der Datenminimierung (Art. 5(1)(c) DSGVO: „…angemessen, erheblich und auf das für die Zwecke notwendige Maß beschränkt…“).  ￼

## Entscheidung (Vorschlag)

Variante A: OpenTelemetry-Logs (JS) mit eigenem lokalen Exporter, der JSON-Lines (NDJSON) in rotierende Dateien schreibt. Vorteile:
	•	Standardisierte Log-API/Modell (später erweiterbar auf OTLP/HTTP, falls jemals gewünscht).  ￼
	•	Einfaches, stream-freundliches Format (JSON-Lines) – robust für Datei-Append, leicht zu parsen/teilen.  ￼
	•	Keine Netzwerkabhängigkeit, volle Offline-Funktionalität.

## Scope
	•	In-Scope
	•	OTel-Logger-Pipeline (Provider → Batch-Processor → lokaler Datei-Exporter).  ￼
	•	Dev-Mode-Screen: Logging aktivieren/deaktivieren, anzeigen, Datei teilen.
	•	Log-Rotation + Retention (Größe/Zeit).
	•	Grundlegende PII-Redaktion/Whitelist.
	•	Out-of-Scope
	•	Server-Upload, Remote-Collectors, Alerting.

⸻

## Architektur & Design

### High-Level
```
App Code ──► LogService (Port)
           └── OTel Adapter (LoggerProvider + BatchProcessor)
                 └── FileLogExporter (JSONL via react-native-fs)
                       └── /AppData/Logs/*.jsonl (rotierend)
Dev-Mode-UI ─► toggelt LogService, liest Datei(en), Share-Sheet
```
### Design-Prinzipien
	•	Separation of Concerns: UI kennt nur LogService (Port). OTel + FS sind Adapter.
	•	Dependency Inversion: App-Code loggt über LogService-Interface; OTel/FS austauschbar.
	•	Feature Flag / Runtime-Toggle: Logging aus per Default; nur manuell aktivierbar im Dev-Mode-Screen.
	•	Security & Privacy by Design: Whitelist-Attribute, PII-Redaktion, lokale Speicherung, kurze Retention; keine automatischen Exporte. OWASP-Guidelines gegen „Sensitive Data in Logs“.  ￼

⸻

## Technische Details

### Libraries
	•	OpenTelemetry Logs (JS): @opentelemetry/api-logs, @opentelemetry/sdk-logs.  ￼
	•	Filesystem: react-native-fs (oder gepflegte Forks, falls nötig).  ￼
	•	Teilen: Core-API Share (Text) und/oder react-native-share (Dateien/URLs).  ￼

### Dateipfade & Backup-Exklusion (iOS)
	•	Logs unter …/Library/Application Support/Logs/ oder …/Documents/Logs/.
	•	Bei iOS: Ordner mit NSURLIsExcludedFromBackupKey anlegen, um iCloud-Backup auszuschließen. (RNFS unterstützt Flag bei mkdir).  ￼

### Datenformat
	•	JSON-Lines (.jsonl): ein LogRecord pro Zeile, robust für Append/Streaming.  ￼
	•	Optional spätere OTLP/HTTP JSON-Kompatibilität, falls Export gewünscht.  ￼

⸻

## UI/UX (Dev-Mode-Screen)
	•	Schalter „Lokales Logging aktivieren“ (Default aus).
	•	Liste mit letzten N Einträgen (Level, Zeit, Kurztext; Tap für Details).
	•	Buttons: „Teilen“ (öffnet Share-Sheet mit Logdatei), „Löschen“, „Export als ZIP“ (optional).

⸻

## Beispiel-Implementierung (Ausschnitt)

### 1) OTel Setup + Datei-Exporter (TypeScript)
```ts
// logging/otel.ts
import * as logsAPI from '@opentelemetry/api-logs';
import { LoggerProvider, BatchLogRecordProcessor, ReadableLogRecord, LogRecordExporter } from '@opentelemetry/sdk-logs';
import { Resource } from '@opentelemetry/resources';
import RNFS from 'react-native-fs';

const LOG_DIR = `${RNFS.LibraryDirectoryPath ?? RNFS.DocumentDirectoryPath}/Logs`;
const LOG_FILE = `${LOG_DIR}/app-logs.jsonl`;

export async function ensureLogDir() {
  await RNFS.mkdir(LOG_DIR, { NSURLIsExcludedFromBackupKey: true }); // iOS: exclude from iCloud backup
}

class FileLogExporter implements LogRecordExporter {
  constructor(private path: string) {}
  export(batch: ReadableLogRecord[], done: (r:{code:number}) => void) {
    const lines = batch.map(r => JSON.stringify({
      ts: Date.now(),
      level: r.severityText ?? 'INFO',
      body: typeof r.body === 'string' ? r.body : String(r.body ?? ''),
      attrs: r.attributes ?? {},
      traceId: r.spanContext?.().traceId,
      spanId: r.spanContext?.().spanId,
    })).join('\n') + '\n';

    RNFS.appendFile(this.path, lines, 'utf8').then(
      () => done({ code: 0 }),
      () => done({ code: 1 })
    );
  }
  async shutdown() {}
}

let provider: LoggerProvider | null = null;
export async function startLocalLogging() {
  await ensureLogDir();
  provider = new LoggerProvider({ resource: new Resource({ 'service.name': 'my-rn-app' }) });
  provider.addLogRecordProcessor(new BatchLogRecordProcessor(new FileLogExporter(LOG_FILE)));
  logsAPI.logs.setGlobalLoggerProvider(provider);
}

export async function stopLocalLogging() {
  await provider?.shutdown();
  provider = null;
}

export const getLogger = () => logsAPI.logs.getLogger('app');
export const paths = { LOG_DIR, LOG_FILE };
```
OTel-Logs: LoggerProvider/Logger/Emit sind das vorgesehene Modell.  ￼

### 2) Dev-Mode-Screen (Toggle, View, Share)
```ts
// screens/DevLogsScreen.tsx
import React, { useEffect, useState } from 'react';
import { View, Text, Switch, FlatList, Button } from 'react-native';
import RNFS from 'react-native-fs';
import Share from 'react-native-share';
import { startLocalLogging, stopLocalLogging, getLogger, paths } from '../logging/otel';

export default function DevLogsScreen() {
  const [enabled, setEnabled] = useState(false);
  const [rows, setRows] = useState<any[]>([]);

  useEffect(() => {
    let id: any;
    if (enabled) {
      startLocalLogging().then(() => getLogger().emit({ severityText: 'INFO', body: 'Local logging enabled' }));
      id = setInterval(async () => {
        try {
          const txt = await RNFS.readFile(paths.LOG_FILE, 'utf8');
          const lines = txt.trim().split('\n').slice(-400).map(l => JSON.parse(l));
          setRows(lines.reverse());
        } catch {}
      }, 1500);
    } else {
      stopLocalLogging();
      setRows([]);
    }
    return () => { if (id) clearInterval(id); };
  }, [enabled]);

  const share = async () => {
    await Share.open({ url: 'file://' + paths.LOG_FILE, type: 'application/json', failOnCancel: false });
  };

  return (
    <View style={{ flex:1, padding:16, gap:12 }}>
      <View style={{ flexDirection:'row', justifyContent:'space-between', alignItems:'center' }}>
        <Text>Lokales Logging</Text>
        <Switch value={enabled} onValueChange={setEnabled} />
      </View>

      <Button title="Teilen (JSONL)" onPress={share} />
      <FlatList
        data={rows}
        keyExtractor={(_,i) => String(i)}
        renderItem={({item}) => <Text>{item.level} • {item.body}</Text>}
      />
    </View>
  );
}
```
Teilen via RN-Share/react-native-share.  ￼

### 3) Rotation & Retention (Skizze)
	•	Neue Datei pro Tag (app-logs-YYYY-MM-DD.jsonl) oder nach z. B. 2 MB.
	•	Beim App-Start: alte Dateien > 14 Tage löschen (konfigurierbar).

⸻

## Sicherheits- & Datenschutz-Leitplanken
	•	Default: aus; explizites Opt-In im Dev-Mode.
	•	Whitelist-Logging: Nur freigegebene Schlüssel/Attribute; keine PII, keine Tokens/Secrets; redigiere Muster (z. B. E-Mails, IBANs) vor dem Schreiben. (OWASP: „avoid logging sensitive data“)  ￼
	•	Speicherort: App-Sandbox, iOS ohne iCloud-Backup (Backup-Exklusion).  ￼
	•	Integrität/Schutz: Nur App-Zugriff; optional Verschlüsselung der Logdatei (Follow-Up).
	•	Löschbarkeit: „Alles löschen“-Button in der UI.
	•	Transparenz: Kurzer Hinweistext im Dev-Mode-Screen.

⸻

## Akzeptanzkriterien (DoD)
	1.	Logging ist standardmäßig deaktiviert; Status persistiert app-lokal (nur für Dev-Mode).
	2.	Bei aktiviertem Logging werden Events als JSON-Lines in Datei geschrieben; Datei existiert nur im aktivierten Zustand.  ￼
	3.	Dev-Mode-Screen zeigt die letzten N Einträge (mind. 400) ohne spürbare UI-Lags.
	4.	Share-Sheet kann aktuelle Logdatei erfolgreich teilen.  ￼
	5.	Rotation & Retention: max. Dateigröße/Tag; automatische Bereinigung nach konfigurierbarer Frist.
	6.	Keine PII/Secrets in Logs (statische Checks + Tests, OWASP-konform).  ￼
	7.	iOS-Logs sind von iCloud-Backups ausgeschlossen.  ￼

⸻

## Testplan
	•	Unit:
	•	FileLogExporter schreibt valide JSON-Lines (pro Zeile valides JSON).
	•	Redaktions-/Whitelist-Funktionen (PII-Muster).
	•	Integration:
	•	Toggle → Start/Stop-Pipeline; Append-Pfad; Rotation.
	•	Share-Flow (Mock/CI mit File-URL).
	•	E2E (Device/Simulator):
	•	UI-Responsiveness bei 1k/5k Zeilen.
	•	iOS: Ordner mit NSURLIsExcludedFromBackupKey angelegt.  ￼
	•	Static/Policy:
	•	Linter-Regel verbietet logger-Aufrufe mit „verbotenen Keys“ (PWD, token, …).
	•	CI-Job scannt Log-Fixtures auf PII-Muster.

⸻

## Risiken & Gegenmaßnahmen
	•	RNFS-Maintenance: Upstream schwankte teils; ggf. gepflegten Fork evaluieren.  ￼
	•	Performance: Batch-Größe/Flush-Interval feinjustieren; UI zeigt nur letzte N Einträge.
	•	Fehlkonfiguration (PII): Whitelist-Ansatz + Tests + Code Reviews (OWASP).  ￼

⸻

## Alternativen
	•	SQLite-Storage: bessere Queries, aber höherer Aufwand.
	•	Ohne OTel: Custom-Logger; schneller, aber weniger standardkonform/korrigierbar.
	•	Collector on-device: Overkill für unseren Use-Case.

⸻

## Aufgaben (Checklist)
	•	logging/ Modul (Port LogService, Adapter OtelLogService)
	•	FileLogExporter + Rotation + Retention
	•	Dev-Mode-Screen (Toggle, List, Share, Clear)
	•	PII-Whitelist + Redaktions-Helper + Tests (Unit/Integration)
	•	iOS: NSURLIsExcludedFromBackupKey beim Log-Ordner setzen  ￼
	•	Android/iOS-Permissions/Manifeste prüfen (keine unnötigen Berechtigungen)
	•	CI: JSONL-Lint + PII-Pattern-Scan
	•	Docs: Kurze Developer-Readme „Wie loggen“ + Troubleshooting

⸻

## Referenzen (Auswahl)
	•	OpenTelemetry Logs API/Spezifikationen.  ￼
	•	OTLP Spezifikation & HTTP/JSON-Konfiguration.  ￼
	•	JSON-Lines (NDJSON) Format.  ￼
	•	React Native Share / react-native-share.  ￼
	•	react-native-fs & iOS Backup-Exklusion.  ￼
	•	DSGVO Datenminimierung.  ￼
	•	OWASP (keine sensitiven Daten in Logs, Mobile-Leitlinien).  ￼


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Lokales App-Logging (Variante A): OpenTelemetry → JSON-Lines-Datei, Dev-Mode-UI zum Aktivieren/Einsehen/Teilen (Default: aus) #1639

Kontext & Motivation

Entscheidung (Vorschlag)

Scope

Architektur & Design

High-Level

Design-Prinzipien

Technische Details

Libraries

Dateipfade & Backup-Exklusion (iOS)

Datenformat

UI/UX (Dev-Mode-Screen)

Beispiel-Implementierung (Ausschnitt)

1) OTel Setup + Datei-Exporter (TypeScript)

2) Dev-Mode-Screen (Toggle, View, Share)

3) Rotation & Retention (Skizze)

Sicherheits- & Datenschutz-Leitplanken

Akzeptanzkriterien (DoD)

Testplan

Risiken & Gegenmaßnahmen

Alternativen

Aufgaben (Checklist)

Referenzen (Auswahl)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Lokales App-Logging (Variante A): OpenTelemetry → JSON-Lines-Datei, Dev-Mode-UI zum Aktivieren/Einsehen/Teilen (Default: aus) #1639

Description

Kontext & Motivation

Entscheidung (Vorschlag)

Scope

Architektur & Design

High-Level

Design-Prinzipien

Technische Details

Libraries

Dateipfade & Backup-Exklusion (iOS)

Datenformat

UI/UX (Dev-Mode-Screen)

Beispiel-Implementierung (Ausschnitt)

1) OTel Setup + Datei-Exporter (TypeScript)

2) Dev-Mode-Screen (Toggle, View, Share)

3) Rotation & Retention (Skizze)

Sicherheits- & Datenschutz-Leitplanken

Akzeptanzkriterien (DoD)

Testplan

Risiken & Gegenmaßnahmen

Alternativen

Aufgaben (Checklist)

Referenzen (Auswahl)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions