Skip to main content
skill CX Codex

encore-logging — Claude Code skill for Encore.ts structured logs

The encore-logging skill guides an agent through structured logging in Encore.ts with encore.dev/log, covering message style, levels and fields.

Apache-2.0 168 installs ★ 30 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add encoredev/skills --skill encore-logging -a claude-code
Open on GitHub

What encore-logging does

The skill sets rules for calls like log.info and log.error from encore.dev/log: the message text stays fixed while variable data goes into fields. Events read by dashboards or alerts get a stable event field shaped as <domain>.<past-tense-event>, such as payment.authorized.

It also covers which severity level fits a given situation, from error down to trace, and where to record a failure: at the layer that decides whether to retry or recover, not at every layer the error passes through. For fields repeated across one operation, the skill points to log.with() so logs don't restate context Encore already attaches, like service, endpoint, trace ID and user ID.

Encore does not redact log fields on its own, so the skill is explicit about keeping tokens, cookies, authorization headers and full request or response bodies out of logged data.

What it helps with

  • pick a severity level for a business event
  • move variable data into fields instead of the message text
  • avoid duplicating context Encore already attaches to a trace
  • keep tokens, cookies and payment data out of logs
  • cut log volume in loops and Pub/Sub subscribers

Example prompts for the agent

  • Add structured logging to this order handler following encore-logging rules
  • Check what log level fits this payment failure case
  • Reduce the log volume in this Pub/Sub subscriber

How to install encore-logging

1Skills CLI (Vercel)

npx skills add encoredev/skills --skill encore-logging -a claude-code

2Manually: put the files in place

~/.claude/skills/logging/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/logging/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about encore-logging

How do I install encore-logging in Claude Code?

Run npx skills add encoredev/skills --skill encore-logging -a claude-code or npx skills add encoredev/skills --skill logging -a claude-code. The skill lands at ~/.claude/skills/logging/SKILL.md.

What does the encore-logging skill do?

It sets rules for structured logging in Encore.ts through encore.dev/log: what to log, which severity level fits, how to format messages and fields, when to share context with log.with(), and how to keep sensitive data out of logs.

Does this skill redact sensitive fields for me?

No, Encore doesn't redact log fields on its own, and the sensitive API option only hides data in traces, not in log calls, so the skill tells you to exclude tokens and personal data manually.

Source text

SKILL.md · Apache-2.0
---
name: encore-logging
description: Add or improve structured logging in Encore.ts using `encore.dev/log`. Covers log placement, levels, stable messages and fields, errors, contextual loggers, sensitive data, and log volume.
when_to_use: >-
  User is adding, changing, or reviewing application logs in an Encore.ts service. Mentions structured logging, `encore.dev/log`, `log.info`, `log.error`, log fields, log levels, noisy or duplicate logs, production debugging, or what to log. Trigger phrases: "add logging", "improve these logs", "which log level", "structured log fields", "reduce log volume", "log this error".
---

# 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:

```typescript
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:

```typescript
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

Expected outcomes such as validation failures, missing resources, rejected logins, or declined payments are not `error` events. Use their business meaning to choose a level.

The default minimum level is `trace`. Configure `log_level` in `encore.app` before adding `debug` or `trace` calls to frequently executed code.

## Record errors once

`error` and `warn` accept the original error as their first argument:

```typescript
try {
  await chargeCustomer(customerId, amount);
} catch (err) {
  log.error(err, "payment authorization failed", {
    customerId,
    amountMinorUnits: amount,
    currency,
  });
  throw err;
}
```

Passing the original error preserves its type, message, stack trace, and cause. Converting it to a string discards that information.

Log a propagated failure at the layer that owns the recovery decision and has the domain context to describe its impact. A lower layer should log only when it handles or suppresses the error, retries, detects an invariant violation, or holds context that propagation will lose.

## Add shared context

Use `log.with()` when several events from one domain operation share fields:

```typescript
const logger = log.with({ importId, tenantId });

logger.info("user import completed", { succeededCount, failedCount });
logger.warn("user import row rejected", { rowNumber, reason: "invalid_email" });
```

Encore already attaches the service, endpoint, trace ID, and authenticated user ID to request logs. Do not add duplicate copies.

## Protect sensitive data

Encore does not redact log fields. Never log credentials, tokens, session identifiers, cookies, authorization headers, secret configuration, payment details, or complete request and response objects.

Prefer internal identifiers over personal data. Use a stable non-reversible fingerprint when correlation requires a value that should not be stored.

The `sensitive` API option redacts request and response payloads from traces; it does not redact values passed to `log`.

## Control volume

Summarize batches and long-running operations with outcomes, counts, and durations. Avoid one log per item unless each failure requires investigation.

Log selected metadata from large values rather than complete provider responses, records, configuration objects, arrays, or document bodies. Bound previews and review them for sensitive data before logging.

When reviewing an existing application, check loops, Pub/Sub subscribers, middleware, and frequently called helpers first. A small number of these call sites often produces most of the log volume.

See the [Encore.ts logging guide](https://encore.dev/docs/ts/observability/logging) and [`encore.dev/log` API reference](https://encore.dev/docs/ts/runtime/log).

© encoredev · Apache-2.0 · encoredev/skills

Similar skills

All skills for Backend and APIs →

From the same set31

The whole set →
encore-go-secret encore-go-secret is a Claude Code skill for loading Encore Go secrets through a package-level secrets struct. It covers API keys, passwords, and signing credentials. CX Codex +1 362installs encore-go-pubsub encore-go-pubsub guides asynchronous messaging in Encore Go with topics and subscriptions. Use it for background handlers, event fan-out, and service-to-service messages. CX Codex +1 360installs encore-go-bucket encore-go-bucket — a skill for Encore Go object storage via objects.NewBucket. Upload, download, list, and delete files; generate signed URLs for direct client access. CX Codex +1 359installs encore-go-webhook This skill guides Encore Go webhook handlers with raw HTTP access, signature checks, and Pub/Sub handoff for events from outside services. CX Codex +1 358installs encore-go-cron encore-go-cron teaches the agent to declare recurring work in Encore Go with cron.NewJob. Useful when a job should run on a timer instead of a request. CX Codex +1 357installs encore-go-cache encore-go-cache — a skill that shows the agent how to cache in Redis from Encore Go services: typed keyspaces, TTLs, atomic counters. CX Codex +1 355installs encore-architecture encore-architecture guides service boundaries, data ownership, and communication design for Encore.go and Encore.ts projects. CX Codex +1 167installs encore-go-logging The encore-go-logging Claude Code skill helps add and review structured logs in Encore.go services. It activates for work on log levels, event fields, errors, and noisy output. CX Codex +1 136installs

Project sponsors

Companies that keep this analytics open