appointment-booking-software/docs/universal-logger.md

UniversalLogger Documentation

Overview

The UniversalLogger is a comprehensive logging solution for the appointment booking platform that provides unified logging capabilities across both client-side (browser) and server-side (Node.js) environments. It features automatic client error forwarding to the server for centralized log management.

Architecture

Core Components

1. UniversalLogger Class (src/lib/logger/index.ts)

   • Environment-aware logging with automatic detection
   • Context-based log categorization
   • Consistent API across client and server environments

2. Winston Configuration (src/lib/logger/winston.ts)

   • Structured server-side logging with custom formatting
   • Environment-based log levels
   • Stack trace capture for errors

3. Client Error Forwarding API (src/routes/api/log/+server.ts)

   • HTTP endpoint for receiving client-side errors
   • Automatic context labeling for client logs
   • Error handling with fallback logging

Key Features

Environment Detection

The logger automatically detects the execution environment and adapts its behavior:

• Browser Environment: Uses console methods with emoji prefixes and forwards errors to server
• Server Environment: Uses Winston logger with structured formatting

Client Error Forwarding

Client-side errors are automatically forwarded to the server for centralized logging. This includes:

• Error messages and stack traces
• Current URL context
• User agent information
• Custom metadata
• Timestamps

Context System

The logger supports contextual categorization through the setContext() method:

const logger = createLogger("ComponentName");
logger.info("This log will be tagged with ComponentName context");

Usage

Basic Setup

import { createLogger } from "$lib/logger";

// Create a logger with context
const logger = createLogger("MyComponent");

Logging Methods

// Debug information (development only)
logger.debug("Debug message", { additionalData: "value" });

// General information
logger.info("User logged in", { userId: 123 });

// Warnings
logger.warn("Deprecated API usage", { api: "old-endpoint" });

// Errors (automatically forwarded to server when in browser)
logger.error("Failed to save data", { error: errorObject });

Request Logging

The logger automatically logs HTTP requests when integrated with SvelteKit hooks:

// Automatic request logging includes:
// - HTTP method and URL
// - Response status code
// - Response time
// - Error classification for 4xx/5xx status codes

Configuration

Environment Variables

• Development: Debug level logging enabled
• Production: Info level logging and above

Winston Configuration

The server-side Winston logger is configured with:

• Custom timestamp format (YYYY-MM-DD HH:mm:ss)
• Color-coded console output
• Stack trace capture for errors
• Structured metadata formatting

Integration Examples

SvelteKit Component

<script lang="ts">
  import { onMount } from "svelte";
  import { createLogger } from "$lib/logger";

  const logger = createLogger("HomePage");

  onMount(() => {
    logger.info("Page mounted successfully");

    try {
      // Some operation
    } catch (error) {
      logger.error("Operation failed", { error });
    }
  });
</script>

Server-Side Hooks

// src/hooks.server.ts
import { logger } from "$lib/logger";

export const handle = async ({ event, resolve }) => {
  const start = Date.now();
  const requestLogger = logger.setContext("REQUEST");

  try {
    const response = await resolve(event);
    const duration = Date.now() - start;

    requestLogger.info(`${event.request.method} ${event.url.pathname}`, {
      status: response.status,
      duration: `${duration}ms`,
    });

    return response;
  } catch (error) {
    requestLogger.error("Request failed", { error });
    throw error;
  }
};

Client Error Server Logging

One of the key features of the UniversalLogger is that client-side errors are automatically forwarded and logged on the server. This provides several benefits:

Centralized Error Tracking

All errors, whether occurring on the client or server, are logged in a single location on the server, making it easier to:

• Monitor application health
• Debug issues across the full stack
• Maintain audit trails
• Analyze error patterns

Rich Error Context

When client errors are forwarded to the server, they include:

• URL Context: The page where the error occurred
• User Agent: Browser and device information
• Timestamps: When the error occurred
• Stack Traces: Full error details
• Custom Metadata: Any additional context provided

Automatic Fallback

If the client cannot reach the server to forward an error, it falls back to local console logging, ensuring no errors are lost.

Performance Considerations

• Lazy Loading: Winston is only imported on the server side
• Async Error Forwarding: Client errors are sent asynchronously to avoid blocking UI
• Environment Optimization: Debug logs are only processed in development
• Structured Logging: Efficient JSON-based metadata handling

Dependencies

• winston: ^3.17.0 - Server-side structured logging
• SvelteKit: Environment detection and HTTP utilities
• Native APIs: Fetch API for client-server communication

Error Handling

The logger includes comprehensive error handling:

• Failed server requests for error forwarding don't crash the client
• Malformed log data is handled gracefully
• Winston errors are caught and logged to console as fallback
• Context switching errors are isolated and don't affect logging functionality

Best Practices

1. Use Descriptive Contexts: Set meaningful context names for different components
2. Include Relevant Metadata: Add structured data to help with debugging
3. Appropriate Log Levels: Use debug for development, info for important events, warn for recoverable issues, error for failures
4. Avoid Sensitive Data: Never log passwords, tokens, or personal information
5. Performance Awareness: Limit debug logging in production environments