К основному содержанию
скилл CX Codex

encore-logging — скилл для Claude Code: структурные логи в Encore.ts

Скилл encore-logging учит агента расставлять структурные логи в Encore.ts через encore.dev/log: что писать, с каким уровнем и какими полями.

Apache-2.0 168 установок ★ 30 обновлён 2026-10-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add encoredev/skills --skill encore-logging -a claude-code
Открыть на GitHub

Что делает encore-logging

Скилл задаёт правила для log.info, log.error и других вызовов encore.dev/log: сообщение остаётся неизменным текстом, а переменные данные уходят в поля. Для событий, которые читают дашборды и алерты, добавляется стабильное поле event в формате <домен>.<событие в прошедшем времени>, например payment.authorized.

Отдельно описан выбор уровня — error, warn, info, debug, trace — и момент, где логировать ошибку: на том слое, который принимает решение о повторе или восстановлении, а не на каждом промежуточном. Для повторяющихся полей внутри одной операции скилл предлагает log.with(), чтобы не дублировать контекст, который Encore уже прикрепляет сам — сервис, эндпоинт, trace ID, ID пользователя.

Encore не редактирует поля логов автоматически, и скилл прямо запрещает писать в них токены, cookie, заголовки авторизации и полные объекты запроса-ответа.

Какие задачи решает

  • выбрать уровень логирования для бизнес-события
  • вынести переменные данные в поля вместо текста сообщения
  • не задвоить контекст, который Encore уже добавляет к трейсу
  • убрать из логов токены, cookie и платёжные данные
  • снизить объём логов в циклах и Pub/Sub-обработчиках

Примеры запросов агенту

  • Добавь структурные логи в этот обработчик заказа по правилам encore-logging
  • Проверь, на каком уровне логировать ошибку оплаты в этом сервисе
  • Сократи объём логов в этом Pub/Sub-подписчике

Как установить encore-logging

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/logging/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об encore-logging

Как установить encore-logging в Claude Code?

Выполните npx skills add encoredev/skills --skill encore-logging -a claude-code или npx skills add encoredev/skills --skill logging -a claude-code. Скилл окажется в ~/.claude/skills/logging/SKILL.md.

Что делает скилл encore-logging?

Он задаёт правила структурного логирования в Encore.ts через encore.dev/log: какие события логировать, какой уровень выбрать, как оформлять сообщение и поля, когда заводить общий логгер через log.with() и как не раскрыть чувствительные данные.

Нужно ли дополнительно настраивать редактирование логов?

Да, Encore не редактирует поля логов сам, и опция API sensitive скрывает данные только в трейсах, а не в вызовах log, поэтому исключать токены и персональные данные нужно вручную по правилам скилла.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
review-logging-patterns HugoRCD Скилл review-logging-patterns для Claude Code проверяет логи и ошибки в TypeScript и JavaScript. Он предлагает внедрить evlog и подключается к задачам настройки или ревью логирования. CX Codex +1 767установок logging-best-practices aj-geddes Скилл logging-best-practices для настройки логирования: уровни, JSON-формат, контекст, защита PII и централизованный сбор логов. CX Codex +1 744установок logging codewithmukesh Скилл logging для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode: покрывает сквозные части observability в .NET 10 — health check эндпоинты, correlation ID и стратегию уровней логирования. CX Codex +1 4 000установок go-logging cxuu Скилл go-logging для Claude Code: правила логирования в Go — уровни, структурные поля, контекст запроса. Наводит порядок в логах растущего Go-проекта. CX Codex +1 1 100установок logging-observability wshaddix Скилл logging-observability настраивает структурированные логи, корреляцию запросов и журналирование HTTP в ASP.NET Core Razor Pages. Нужен при сборке наблюдаемости приложения. CX Codex +1 550установок 181-java-observability-logging Juan Antonio Breña Moral Скилл 181-java-observability-logging для Claude Code помогает внедрять и улучшать логирование Java. Он включается по запросам настроить, пересмотреть или добавить поддержку логов. CX Codex +1 325установок

Из того же набора31

Весь набор →
encore-go-secret Скилл encore-go-secret для Claude Code подключает секреты Encore Go через поля package-level структуры secrets. Срабатывает для API-ключей и других приватных учётных данных. CX Codex +1 362установок encore-go-pubsub Скилл encore-go-pubsub для Claude Code описывает асинхронный обмен сообщениями в Encore Go через topics и subscriptions. Помогает публиковать события и обрабатывать их в фоне. CX Codex +1 360установок encore-go-bucket Скилл encore-go-bucket для Claude Code и Codex: работа с объектным хранилищем Encore Go через objects.NewBucket. Загружает, скачивает, удаляет файлы и генерирует подписанные URL для прямого доступа клиентов. CX Codex +1 359установок encore-go-webhook Скилл encore-go-webhook помогает принимать webhook-события в Encore Go через raw HTTP, проверять подписи и передавать обработку в Pub/Sub. CX Codex +1 358установок encore-go-cron Скилл encore-go-cron для Claude Code учит агента объявлять периодические задачи в Encore Go через cron.NewJob. Задаёт расписание вместо обработки входящего запроса. CX Codex +1 357установок encore-go-cache Скилл encore-go-cache учит агента писать кэш в Redis из Go-сервисов на Encore: типизированные keyspaces, TTL, атомарные счётчики. CX Codex +1 355установок encore-architecture Скилл encore-architecture помогает спроектировать или разделить сервисы в приложениях на Encore.go и Encore.ts. Подходит для выбора границ сервисов, моделей данных и Pub/Sub. CX Codex +1 167установок encore-go-logging Скилл encore-go-logging для Claude Code помогает добавлять и разбирать структурированные логи в сервисах Encore.go. Включается при работе с уровнями логирования, полями событий и объёмом логов. CX Codex +1 136установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой