Structured Logging On Device

npx expo install @react-native-async-storage/async-storage expo-application expo-updates

// src/logging/types.ts
export type LogLevel = "debug" | "info" | "warn" | "error";
 
export type StructuredLog = {
  ts: string;              // ISO-8601
  level: LogLevel;
  event: string;           // stable snake_case name: feed_fetch_failed
  message?: string;
  data?: Record<string, string | number | boolean | null>;
};
 
export type LogBatchHeader = {
  sessionId: string;
  release: string;
  otaUpdateId: string;
  route?: string;
  platform: "ios" | "android";
};

// src/logging/buffer.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import type { StructuredLog } from "./types";
 
const STORAGE_KEY = "log_buffer_v1";
const MAX_LOGS = 200;
 
let memory: StructuredLog[] = [];
 
export async function appendLog(entry: StructuredLog) {
  memory.push(entry);
  if (memory.length > MAX_LOGS) {
    memory = memory.slice(-MAX_LOGS);
  }
  await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(memory));
}
 
export async function drainLogs(): Promise<StructuredLog[]> {
  const raw = await AsyncStorage.getItem(STORAGE_KEY);
  const logs: StructuredLog[] = raw ? JSON.parse(raw) : memory;
  memory = [];
  await AsyncStorage.removeItem(STORAGE_KEY);
  return logs;
}

// src/logging/logger.ts
import type { LogLevel, StructuredLog } from "./types";
import { appendLog } from "./buffer";
 
function write(level: LogLevel, event: string, data?: StructuredLog["data"], message?: string) {
  const entry: StructuredLog = {
    ts: new Date().toISOString(),
    level,
    event,
    message,
    data,
  };
  if (__DEV__) console[level === "debug" ? "log" : level](event, data ?? {});
  void appendLog(entry);
}
 
export const logger = {
  debug: (event: string, data?: StructuredLog["data"]) => write("debug", event, data),
  info: (event: string, data?: StructuredLog["data"]) => write("info", event, data),
  warn: (event: string, data?: StructuredLog["data"]) => write("warn", event, data),
  error: (event: string, data?: StructuredLog["data"], message?: string) =>
    write("error", event, data, message),
};

// src/logging/useLogShipping.ts
import { useEffect, useRef } from "react";
import { AppState, type AppStateStatus } from "react-native";
import * as Application from "expo-application";
import * as Updates from "expo-updates";
import { drainLogs } from "./buffer";
import { getSessionId } from "@/observability/session";
 
async function shipBatch(route?: string) {
  const logs = await drainLogs();
  if (logs.length === 0) return;
 
  const header = {
    sessionId: await getSessionId(),
    release: `${Application.nativeApplicationVersion}+${Application.nativeBuildVersion}`,
    otaUpdateId: Updates.updateId ?? "embedded",
    route,
    platform: require("react-native").Platform.OS,
  };
 
  await fetch(`${process.env.EXPO_PUBLIC_API_URL}/v1/logs/batch`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ header, logs }),
  });
}
 
export function useLogShipping(route?: string) {
  const appState = useRef(AppState.currentState);
 
  useEffect(() => {
    const sub = AppState.addEventListener("change", (next: AppStateStatus) => {
      if (appState.current.match(/inactive|background/) && next === "active") {
        void shipBatch(route);
      }
      if (next === "background") {
        void shipBatch(route); // flush before suspend - may not complete on iOS
      }
      appState.current = next;
    });
    return () => sub.remove();
  }, [route]);
}

// app/_layout.tsx
import { Stack } from "expo-router";
import { usePathname } from "expo-router";
import { useLogShipping } from "@/logging/useLogShipping";
 
export default function RootLayout() {
  const pathname = usePathname();
  useLogShipping(pathname);
  return <Stack />;
}

// src/api/client.ts - structured API errors
import { logger } from "@/logging/logger";
 
export async function apiGet<T>(path: string): Promise<T> {
  const start = Date.now();
  try {
    const res = await fetch(`${process.env.EXPO_PUBLIC_API_URL}${path}`);
    if (!res.ok) {
      logger.warn("api_request_failed", {
        path,
        status: res.status,
        durationMs: Date.now() - start,
      });
      throw new Error(`HTTP ${res.status}`);
    }
    logger.info("api_request_ok", { path, durationMs: Date.now() - start });
    return res.json();
  } catch (err) {
    logger.error("api_request_error", { path, durationMs: Date.now() - start });
    throw err;
  }
}

// Auth events - no tokens
import { logger } from "@/logging/logger";
 
export function logAuthEvent(event: "login_success" | "logout" | "refresh_failed", userId?: string) {
  logger.info(event, { userId: userId ? hashId(userId) : null });
}
 
function hashId(id: string) {
  return id.slice(0, 8) + "…"; // replace with real hash in production
}

// src/logging/buffer.ts - drop debug when trimming
function trim(logs: StructuredLog[]) {
  if (logs.length <= MAX_LOGS) return logs;
  const errors = logs.filter((l) => l.level !== "debug");
  return errors.slice(-MAX_LOGS);
}

// Include the same ids Sentry and OTel use
logger.info("checkout_started", {
  sessionId,
  release,
  otaUpdateId: Updates.updateId,
  traceId, // from opentelemetry-on-mobile when enabled
});