Skip to content

[2026-02-05] Feature: Logging & Observability Uplift

Task Metadata

  • 📆 Date: 2026-02-05
  • 🚥 Status: Complete
  • Beads Issue: 2512_genai_food_tracking-ydp

Objective

Goal: Implement a robust logging and tracing framework across the frontend and backend to eliminate "black box" behavior during complex state transitions (Auth, Sync, Promotion).

  • Trigger: Multiple failures in Guest Mode promotion logic that were un-traceable due to insufficient logging and premature cleanup of debug statements.
  • Current Pain Points:
    • Service switching logic (LOCAL vs API) is opaque during re-renders.
    • Lambda logic for settings resolution (version conflicts) lacks client-side visibility.
    • User intent (latest settings) is being discarded by over-zealous backend safeguards.

Technical Strategy

We will focus on uplifting the frontend logic first to maximize visibility without requiring a backend redeploy. We will move away from ad-hoc console.log and implement a structured tracing pattern using the loglevel library.

  • The Lightweight Standard (loglevel):
    • Replace ad-hoc console.log with a singleton logger instance.
    • React Pattern: Export a singleton instance of loglevel from a central logger.ts utility.
    • Environment Control: Configure logger.setLevel('debug') in development and logger.setLevel('warn') in production. This ensures diagnostic traces are kept in code but remain silent for end-users unless explicitly enabled.
  • Frontend Tracing focus:
    • Implement a consistent [Component/Service] Action: { state } prefix.
    • Log payload and result for every service call (Meals & Settings) on the client side.
    • Capture and log all GraphQL errors and network-level responses from the existing backend without schema changes.
  • Auth Transition Monitoring:
    • Add persistent logging to ServiceProvider and usePromotion that explicitly records the why behind every service selection.
  • Preservation Rule:
    • Logging MUST NOT be removed until the feature is marked as Complete in the Master Plan and verified by the user.

Risk Analysis

  • Performance: loglevel is extremely lightweight and has minimal overhead even when active.
  • Security: Ensure no PII (emails, names) or tokens are logged. (Mitigation: Only log metadata, counts, and non-sensitive versions).
  • Files to Modify:
    • frontend/package.json (Add loglevel)
    • frontend/src/utils/logger.ts (New singleton)
    • frontend/src/providers/ServiceProvider.tsx
    • frontend/src/hooks/usePromotion.ts
    • frontend/src/services/ApiMealService.ts
    • frontend/src/services/LocalMealService.ts

Execution Plan

  • Step 0: Logging Infrastructure
    • Install loglevel in the frontend.
    • Create frontend/src/utils/logger.ts to export a configured singleton instance.
  • Step 1: Frontend Service Tracing
    • Replace existing logs with logger.debug in ApiMealService, LocalMealService, and their Settings counterparts.
    • Ensure updateUserTargets logs the exact payload and the resulting version from the server.
    • Log full GraphQL error responses to help diagnose backend safeguard rejections.
  • Step 2: Promotion Hook Hardening
    • Add "Stage" logging to usePromotion using logger.info: DETECTED_TRANSITION -> STARTING_CHECK -> PROMPTING_USER -> EXECUTING_SYNC.
  • Step 3: Service Provider Observability
    • Log every decision change with the full dependency set (user, isPromoting) to catch race conditions.
  • Verify: Demonstrate a complete trace of a successful (and a rejected) sync using frontend logs.

Execution Notes

  • Plan vs Implementation Audit (2026-02-11): Performed a checklist-driven comparison of this work log against the current codebase and closed the remaining drift.
    • Gap found: LocalSettingsService still used ad-hoc console.log.
      • Fix: Replaced with logger.debug and added request/result tracing for getUserTargets and updateUserTargets.
    • Service tracing parity: Added explicit request/result logging for LocalMealService.getMeals and network error logging in ApiMealService (graphqlWithTimeout timeout + reject path).
    • Settings observability parity: Added ApiSettingsService.getUserTargets request/result debug traces (including default fallback path).
  • Comparison Summary (Checklist Mapping):
    • Step 0: frontend/src/utils/logger.ts defines prefixed singleton + environment level control (VITE_LOG_LEVEL override).
    • Step 1: ApiMealService, LocalMealService, ApiSettingsService, and LocalSettingsService now emit consistent debug/error traces.
    • Step 2: frontend/src/hooks/usePromotion.ts logs all required stage transitions and both success/failure outcomes.
    • Step 3: frontend/src/providers/ServiceProvider.tsx logs decision changes with dependency context (hasUser, isPromoting, test mode).
  • Verification:
    • task test:frontend
    • task lint

User Approval & Key Learnings

Key Learnings

  • Work-log checkboxes can drift from implementation; periodic "plan vs code" audits prevent false in-progress state.
  • Network-layer failures must be logged separately from GraphQL payload errors to remove "silent fail" debugging gaps.