Structured logging

Logs explain what happened. Add the IDs needed to investigate it.

Cloud writes each event to the process console. It also stores a structured copy for the operations interface.

Create a logger

import { logger } from "@k2b/cloud/services";

const log = logger("inventory:stock");

log.info("Stock adjusted", {
  itemId,
  warehouseId,
  delta,
});

A logger exposes debug, info, warn, and error. Pass a short message first. Pass structured metadata second.

Name sources as app or app:area. A stable source lets operators filter events without parsing messages:

const importLog = logger("inventory:import");
const stockLog = logger("inventory:stock");

Choose a level

Do not log the same failure at every layer. Log it where you can add useful context.

Add safe metadata

Prefer IDs, counts, durations, state names, and bounded error messages:

try {
  await reserveStock(itemId, quantity);
} catch (error) {
  log.error("Stock reservation failed", {
    itemId,
    quantity,
    error: error instanceof Error ? error.message : "Unknown failure",
  });
  throw error;
}

Cloud redacts metadata keys containing terms such as password, secret, token, cookie, authorization, apiKey, privateKey, or session.

Do not log request bodies, credentials, or personal records. Redaction is only a safety net.

Metadata must be JSON-serializable. Do not pass circular objects, BigInt values, request objects, or full error objects.

Log delivery

Logging is fire-and-forget:

• the console receives the event immediately;
• the database insert runs asynchronously;
• a persistence failure is reported to the process console;
• the application operation is not failed because log storage is unavailable.

Logs are not a business record. Store important domain events in the domain database or a durable workflow.

The broader logging service exported from /services supports Cloud's admin and operations surfaces. Application code should normally depend only on logger().

To log failed HTTP requests, add middleware.logger(). See Request middleware.

Use Tracing when several events belong to one operation. Use Audit events when a record must show who performed a security-relevant action.