logging-best-practices

作者: neondatabase

專注於廣泛事件(標準日誌行)的日誌記錄最佳實踐,以實現強大的除錯與分析功能

npx skills add https://github.com/neondatabase/mcp-server-neon --skill logging-best-practices

Logging Best Practices Skill

Version: 1.0.0

Purpose

This skill provides guidelines for implementing effective logging in applications. It focuses on wide events (also called canonical log lines) - a pattern where you emit a single, context-rich event per request per service, enabling powerful debugging and analytics.

When to Apply

Apply these guidelines when:

  • Writing or reviewing logging code
  • Adding console.log, logger.info, or similar
  • Designing logging strategy for new services
  • Setting up logging infrastructure

Core Principles

1. Wide Events (CRITICAL)

Emit one context-rich event per request per service. Instead of scattering log lines throughout your handler, consolidate everything into a single structured event emitted at request completion.

const wideEvent: Record<string, unknown> = {
  method: 'POST',
  path: '/checkout',
  requestId: c.get('requestId'),
  timestamp: new Date().toISOString(),
};

try {
  const user = await getUser(c.get('userId'));
  wideEvent.user = { id: user.id, subscription: user.subscription };

  const cart = await getCart(user.id);
  wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };

  wideEvent.status_code = 200;
  wideEvent.outcome = 'success';
  return c.json({ success: true });
} catch (error) {
  wideEvent.status_code = 500;
  wideEvent.outcome = 'error';
  wideEvent.error = { message: error.message, type: error.name };
  throw error;
} finally {
  wideEvent.duration_ms = Date.now() - startTime;
  logger.info(wideEvent);
}

2. High Cardinality & Dimensionality (CRITICAL)

Include fields with high cardinality (user IDs, request IDs - millions of unique values) and high dimensionality (many fields per event). This enables querying by specific users and answering questions you haven't anticipated yet.

3. Business Context (CRITICAL)

Always include business context: user subscription tier, cart value, feature flags, account age. The goal is to know "a premium customer couldn't complete a $2,499 purchase" not just "checkout failed."

4. Environment Characteristics (CRITICAL)

Include environment and deployment info in every event: commit hash, service version, region, instance ID. This enables correlating issues with deployments and identifying region-specific problems.

5. Single Logger (HIGH)

Use one logger instance configured at startup and import it everywhere. This ensures consistent formatting and automatic environment context.

6. Middleware Pattern (HIGH)

Use middleware to handle wide event infrastructure (timing, status, environment, emission). Handlers should only add business context.

7. Structure & Consistency (HIGH)

  • Use JSON format consistently
  • Maintain consistent field names across services
  • Simplify to two log levels: info and error
  • Never log unstructured strings

Anti-Patterns to Avoid

  1. Scattered logs: Multiple console.log() calls per request
  2. Multiple loggers: Different logger instances in different files
  3. Missing environment context: No commit hash or deployment info
  4. Missing business context: Logging technical details without user/business data
  5. Unstructured strings: console.log('something happened') instead of structured data
  6. Inconsistent schemas: Different field names across services

Guidelines

Wide Events (rules/wide-events.md)

  • Emit one wide event per service hop
  • Include all relevant context
  • Connect events with request ID
  • Emit at request completion in finally block

Context (rules/context.md)

  • Support high cardinality fields (user_id, request_id)
  • Include high dimensionality (many fields)
  • Always include business context
  • Always include environment characteristics (commit_hash, version, region)

Structure (rules/structure.md)

  • Use a single logger throughout the codebase
  • Use middleware for consistent wide events
  • Use JSON format
  • Maintain consistent schema
  • Simplify to info and error levels
  • Never log unstructured strings

Common Pitfalls (rules/pitfalls.md)

  • Avoid multiple log lines per request
  • Design for unknown unknowns
  • Always propagate request IDs across services

References:

來自 neondatabase 的更多技能

add-neon-docs
neondatabase
當使用者要求新增關於Neon的文件、文檔、參考資料或安裝文件時,使用此技能。新增Neon最佳實踐參考連結…
better-env
neondatabase
為代理和人類提供更好的環境變數管理,具備完整型別安全、基於命令列的遠端環境同步,以及環境驗證功能。…
claimable-postgres
neondatabase
即時 Postgres 資料庫,適用於本地開發、展示、原型設計與測試環境。無需註冊帳號。資料庫在 72 小時後到期,除非認領至 Neon 帳號。
claimable-postgres
neondatabase
使用 Neon 的 Claimable Postgres(pg.new)快速建立即時 Postgres 資料庫,適用於本地開發、示範、原型設計及測試環境。
neon
neondatabase
Neon平台概述,涵蓋Postgres、Auth、Data API,以及新服務:物件儲存、計算函數和AI閘道。每當提及「Neon」時,用於概述如何操作Neon及入門方式。否則,個別功能即為觸發條件:「物件儲存」或「S3相容儲存」、「無伺服器函數」、「背景任務」或「在資料庫附近執行程式碼」、「AI閘道」、「LLM代理」、「模型路由」或「呼叫LLM」→...
apidevelopmentdatabase
neon-ai-gateway
neondatabase
一個API和一個憑證,即可存取前沿與開源LLM,內建於你的Neon分支中,並由Databricks提供支援。當使用者想要呼叫LLM、新增…時使用。
neon-auth
neondatabase
為你的應用程式設定 Neon Auth。配置驗證、建立驗證路由,並生成 UI 元件。在為 Next.js 加入驗證功能時使用,…
neon-auth
neondatabase
Add authentication to a new app. Use for "add auth", "add login", Neon Auth (Managed Better Auth), identity routing, sign-up, sign-in, password reset, email OTP, magic links, organizations, phone OTP, OAuth, OAuth server for MCP or third-party OAuth clients, passkeys, MFA, trusted domains, invalid domain, and @neon/auth. No existing identity: default to Managed Better Auth. Keep working Better Auth, Clerk, Supabase Auth, or another IdP. User asked to migrate from Supabase Auth: Managed...
apidevelopmentsecurity