Observability Standards

Forbidden Practices

• console.log is forbidden — use the structured logger
• No secrets in logs — passwords, tokens, API keys, database URLs
• No PII in debug/info logs — student emails, names only at warn+ level with justification
• No full request/response body logging in production
• No unstructured string concatenation for log messages

Logger Creation Pattern

import { createLogger } from '@zidney/logger';

// Service-level logger
const logger = createLogger('api');

// Request-scoped child logger (in middleware)
const requestLogger = logger.child({
  correlation_id: req.header('x-correlation-id') ?? generateId(),
  workspace_slug: resolvedTenant.slug,
  workspace_id: resolvedTenant.id,
  user_id: authenticatedUser?.id,
});

Correlation ID Propagation

The correlation ID must flow through:

Client Request (X-Correlation-Id header)
  → API middleware (extract or generate)
    → Domain function calls (passed via context)
      → Worker jobs (embedded in job payload)
        → Database queries (logged alongside query)

Rules:

• Generate correlation ID at API entry point if not provided
• Pass correlation ID in all Worker job payloads
• Include correlation ID in all error responses
• Never generate a new correlation ID mid-request

Log Levels

• Production: info level minimum
• Staging: debug level allowed
• Development: debug level default

Error Logging Pattern

try {
  await riskyOperation();
} catch (error) {
  logger.error({
    err: error,
    operation: 'riskyOperation',
    context: { relevant_id: '...' },
  }, 'Operation failed: brief description');
  
  // Re-throw or return error response
}

Always include:

• The error object (Pino serializes it)
• The operation name
• Relevant context (IDs, not full payloads)
• A human-readable message

Health Check Logging

Services must log at startup:

logger.info({
  version: process.env.APP_VERSION,
  environment: process.env.NODE_ENV,
  port: config.port,
}, 'Service started');

Metrics (Future-Ready)

When metrics collection is added, track:

• http_request_duration_seconds — histogram by route and status
• db_query_duration_seconds — histogram by operation type
• worker_job_duration_seconds — histogram by job type
• active_attempts — gauge per workspace
• submission_rate — counter per workspace
• cache_hit_ratio — gauge per cache domain

Verdict Protocol

VERDICT: PASS   — all log statements include mandatory fields
VERDICT: BLOCKED — missing mandatory log fields or forbidden practice detected