aiskillstore/react-observability

React Observability

Problem Statement

Silent failures are debugging nightmares. Code that returns early without logging, error messages that lack context, and missing observability make production issues impossible to diagnose. Write code as if you'll debug it at 3am with only logs.

---

Pattern: No Silent Early Returns

Problem: Early returns without logging create invisible failure paths.

// WRONG - silent death
const saveData = (id: string, value: number) => {
  if (!validIds.has(id)) {
    return;  // ❌ Why did we return? No one knows.
  }
  // ... save logic
};

// CORRECT - observable
const saveData = (id: string, value: number) => {
  if (!validIds.has(id)) {
    logger.warn('[saveData] Dropping save - invalid ID', {
      id,
      value,
      validIds: Array.from(validIds),
    });
    return;
  }
  // ... save logic
};

Rule: Every early return should log why it's returning, with enough context to diagnose.

---

Pattern: Error Message Design

Problem: Error messages that don't help diagnose the issue.

// BAD - no context
throw new Error('Data not found');

// BAD - slightly better but still useless at 3am
throw new Error('Data not found. Please try again.');

// GOOD - diagnostic context included
throw new Error(
  `Data not found. ID: ${id}, ` +
  `Available: ${Object.keys(data).length} items, ` +
  `Last fetch: ${lastFetchTime}. This may indicate a caching issue.`
);

Error message template:

throw new Error(
  `[${functionName}] ${whatFailed}. ` +
  `Context: ${relevantState}. ` +
  `Possible cause: ${hypothesis}.`
);

What to include:

| Element | Why | |---------|-----| | Function/location | Where the error occurred | | What failed | The specific condition that wasn't met | | Relevant state | Values that help diagnose | | Possible cause | Your best guess for the fix |

---

Pattern: Structured Logging

Problem: Console.log statements that are hard to parse and search.

// BAD - unstructured
console.log('saving data', id, value);
console.log('current state', data);

// GOOD - structured with context object
logger.info('[saveData] Saving data', {
  id,
  value,
  existingCount: Object.keys(data).length,
});

Logging levels:

| Level | Use for | |-------|---------| | error | Exceptions, failures that need immediate attention | | warn | Unexpected conditions that didn't fail but might indicate problems | | info | Important business events (user actions, flow milestones) | | debug | Detailed diagnostic info (state dumps, timing) |

Wrapper for consistent logging:

// utils/logger.ts
const LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const;
type LogLevel = typeof LOG_LEVELS[number];

const currentLevel: LogLevel = process.env.NODE_ENV === 'development' ? 'debug' : 'warn';

function shouldLog(level: LogLevel): boolean {
  return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(currentLevel);
}

export const logger = {
  debug: (message: string, context?: object) => {
    if (shouldLog('debug')) {
      console.log(`[DEBUG] ${message}`, context ?? '');
    }
  },
  info: (message: string, context?: object) => {
    if (shouldLog('info')) {
      console.log(`[INFO] ${message}`, context ?? '');
    }
  },
  warn: (message: string, context?: object) => {
    if (shouldLog('warn')) {
      console.warn(`[WARN] ${message}`, context ?? '');
    }
  },
  error: (message: string, context?: object) => {
    if (shouldLog('error')) {
      console.error(`[ERROR] ${message}`, context ?? '');
    }
  },
};

---

Pattern: Sensitive Data Handling

Problem: Logging sensitive data to console or error reporting.

// utils/secureLogger.ts
const SENSITIVE_KEYS = ['password', 'token', 'ssn', 'creditCard', 'apiKey', 'secret'];

function redactSensitive(obj: object): object {
  const redacted = { ...obj };
  for (const key of Object.keys(redacted)) {
    if (SENSITIVE_KEYS.some(s => key.toLowerCase().includes(s))) {
      redacted[key] = '[REDACTED]';
    } else if (typeof redacted[key] === 'object' && redacted[key] !== null) {
      redacted[key] = redactSensitive(redacted[key]);
    }
  }
  return redacted;
}

export const secureLogger = {
  info: (message: string, context?: object) => {
    const safeContext = context ? redactSensitive(context) : undefined;
    logger.info(message, safeContext);
  },
  // ... other levels
};

---

Pattern: Flow Tracing

Problem: Multi-step operations where it's unclear how far execution got.

async function checkoutFlow(cartId: string) {
  const flowId = `checkout-${Date.now()}`;

  logger.info(`[checkoutFlow:${flowId}] Starting`, { cartId });

  try {
    logger.debug(`[checkoutFlow:${flowId}] Step 1: Validating cart`);
    await validateCart(cartId);

    logger.debug(`[checkoutFlow:${flowId}] Step 2: Processing payment`);
    await processPayment(cartId);

    logger.debug(`[checkoutFlow:${flowId}] Step 3: Confirming order`);
    await confirmOrder(cartId);

    logger.info(`[checkoutFlow:${flowId}] Completed successfully`);
  } catch (error) {
    logger.error(`[checkoutFlow:${flowId}] Failed`, {
      error: error.message,
      stack: error.stack,
      cartId,
    });
    throw error;
  }
}

Benefits:

• Can search logs by flowId to see entire flow
• Know exactly which step failed
• Timing visible via timestamps

---

Pattern: State Snapshots for Debugging

Problem: Need to understand state at specific points in complex flows.

function snapshotState(label: string) {
  const state = useStore.getState();
  logger.debug(`[StateSnapshot] ${label}`, {
    itemCount: Object.keys(state.items).length,
    activeFeatures: Array.from(state.features),
    loading: state.loading,
  });
}

// Usage in flow
async function complexFlow() {
  snapshotState('Before load');
  await loadData(id);
  snapshotState('After load');
  await processData();
  snapshotState('After process');
}

---

Pattern: Assertion Helpers

Problem: Conditions that "should never happen" but need visibility when they do.

// utils/assertions.ts
export function assertDefined<T>(
  value: T | null | undefined,
  context: string
): asserts value is T {
  if (value === null || value === undefined) {
    const message = `[Assertion Failed] Expected defined value: ${context}`;
    logger.error(message, { value });
    throw new Error(message);
  }
}

export function assertCondition(
  condition: boolean,
  context: string,
  debugInfo?: object
): asserts condition {
  if (!condition) {
    const message = `[Assertion Failed] ${context}`;
    logger.error(message, debugInfo);
    throw new Error(message);
  }
}

// Usage
assertDefined(user, `User not found: ${userId}`);
assertCondition(
  items.length > 0,
  `No items found`,
  { searchQuery, filters }
);

---

Pattern: Production Error Reporting

Problem: Errors in production with no visibility.

// Integration with error reporting service (Sentry example)
import * as Sentry from '@sentry/react';

export function captureError(
  error: Error,
  context?: Record<string, unknown>
) {
  logger.error(error.message, { ...context, stack: error.stack });

  if (process.env.NODE_ENV === 'production') {
    Sentry.captureException(error, {
      extra: context,
    });
  }
}

// Usage
try {
  await riskyOperation();
} catch (error) {
  captureError(error, {
    userId,
    action: 'checkout',
    cartItems: cart.items.length,
  });
  throw error;
}

---

Pattern: React Error Boundaries

Problem: Unhandled errors crash the entire app.

import { Component, ErrorInfo, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
  error?: Error;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    logger.error('[ErrorBoundary] Caught error', {
      error: error.message,
      stack: error.stack,
      componentStack: errorInfo.componentStack,
    });

    captureError(error, { componentStack: errorInfo.componentStack });
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? <DefaultErrorFallback error={this.state.error} />;
    }
    return this.props.children;
  }
}

---

Checklist: Adding Observability

When writing new code:

• [ ] All early returns have logging with context
• [ ] Error messages include diagnostic information
• [ ] Multi-step operations have flow tracing
• [ ] Sensitive data is redacted before logging
• [ ] State snapshots available for debugging complex flows
• [ ] Production errors are captured with context

When debugging existing code:

• [ ] Add logging to suspect early returns
• [ ] Add state snapshots before and after async operations
• [ ] Check for silent catches that swallow errors
• [ ] Verify error messages have enough context

---

Quick Debugging Template

Add this temporarily when debugging async/state issues:

const DEBUG = true;

function debugLog(label: string, data?: object) {
  if (DEBUG) {
    console.log(`[DEBUG ${Date.now()}] ${label}`, data ?? '');
  }
}

// In your flow
debugLog('Flow start', { inputs });
debugLog('After step 1', { state: getState() });
debugLog('After step 2', { state: getState() });
debugLog('Flow end', { result });

Remove before committing, or gate behind a flag.