encore-logging

Encore.ts structured logging

Use encore.dev/log for application events that need structured fields or trace integration. Preserve an application's established field names and event conventions when they are consistent with this guidance.

Decide what to record

Add logs for information Encore cannot infer from infrastructure operations:

• Business state transitions
• Decisions and the inputs that determined them
• Retries, fallbacks, and degraded operation
• Failures at the boundary that decides whether to retry, recover, or abort
• External-system interactions that require domain context
• Security-relevant or administrative actions

Encore already traces API requests, database queries, service calls, cache operations, and Pub/Sub activity. Do not narrate that execution with logs such as request started, querying database, or request completed.

Use metrics for aggregate counts and levels. Use traces for call flow and timing. Use logs for the context needed to investigate an individual event.

Emit structured logs

Keep the message stable and put variable data in fields:

import log from "encore.dev/log";

log.info("order rejected", {
  event: "order.rejected",
  orderId,
  productId,
  reason: "insufficient_inventory",
  requestedQuantity,
  availableQuantity,
});

Avoid interpolating identifiers into the message. Stable messages can be grouped, while fields remain searchable.

For events used by dashboards, alerts, or automation, include a stable event field. Prefer <domain>.<past-tense-event>, such as payment.authorized or subscription.cancelled. Diagnostic logs do not require an event name.

Keep each field name and type consistent across events. Prefer numeric values with explicit units and enum-like values over formatted prose:

log.info("payment authorized", {
  event: "payment.authorized",
  amountMinorUnits: 14900,
  currency: "SEK",
});

Choose a level

• error: an unexpected failure prevented an operation from completing
• warn: the application recovered or continued in a degraded state
• info: a meaningful, relatively low-volume business event
• debug: diagnostic detail not required for normal operation
• trace: high-volume internal state