From majestic-engineer
Provides structured JSON logging patterns with correlation IDs, context propagation, log levels, and required fields for observability and production incident debugging.
npx claudepluginhub majesticlabs-dev/majestic-marketplace --plugin majestic-engineerThis skill uses the workspace's default tool permissions.
- Logs are optimized for **querying**, not writing — design with debugging in mind
Provides structured logging guidance: JSON logs, correlation IDs, data redaction, log levels, context, performance. For creation, diagnosis, review using reference patterns. Activates on log/logger mentions.
Provides guidelines for wide events logging—one context-rich event per request per service—for debugging and analytics. Use when writing, reviewing logs, or designing logging strategy.
Implements structured JSON logging with levels, correlation IDs, PII redaction, aggregation, and retention for Node.js, Go, Python apps. Migrates from console.log/printf.
Share bugs, ideas, or general feedback.
Always use key-value pairs (JSON), never string interpolation.
{
"event": "payment_failed",
"user_id": "123",
"reason": "insufficient_funds",
"amount": 99.99,
"timestamp": "2025-01-24T20:00:00Z",
"level": "error",
"service": "billing",
"request_id": "req_abc123"
}
Every log event MUST include:
| Field | Format | Example |
|---|---|---|
timestamp | ISO 8601 with timezone | 2025-01-24T20:00:00Z |
level | debug, info, warn, error | info |
event | snake_case, past tense | user_login_succeeded |
request_id or trace_id | UUID or prefixed ID | req_abc123 |
service | Service/app name | api-gateway |
environment | prod, staging, dev | prod |
Include these when available — they make logs queryable during incidents:
| Category | Fields |
|---|---|
| Identity | user_id, org_id, account_id |
| Tracing | request_id, trace_id, span_id |
| Domain | order_id, transaction_id, job_id |
Rule: Look for domain-specific identifiers that help isolate issues to specific entities.
| Level | When to Use | Example |
|---|---|---|
debug | Verbose local dev details, disabled in prod | Variable values, loop iterations |
info | Normal operations worth recording | User actions, job completions, deploys |
warn | Unexpected but handled | Retries triggered, fallbacks activated |
error | Failed, needs attention | Exceptions, failed requests, timeouts |
Anti-pattern: Don't log errors for expected conditions (wrong password = info, not error).
For distributed systems:
[Client] --request_id--> [API Gateway] --request_id--> [Service A] --request_id--> [Service B]
| | |
(logs) (logs) (logs)
↓ ↓ ↓
All queryable by single request_id
Async jobs: Store and restore original request context when processing background work.
| Log These | Skip These |
|---|---|
| Request entry/exit with duration | Sensitive data (passwords, tokens, PII, cards) |
| State transitions (created → paid → shipped) | Inside tight loops |
| External service calls with latency + status | Success cases with no debug value |
| Auth/authz events | Redundant infra logs (LB already captures) |
| Job starts, completions, failures | |
| Retry attempts, circuit breaker changes |
| Pattern | Example |
|---|---|
Field names: snake_case | user_id, not userId or user-id |
| Events: past tense verbs | payment_completed, not complete_payment |
| Domain prefixes when helpful | auth.login_failed, billing.invoice_created |
Team agreement: Define field names once, use consistently across all services.
| Concern | Solution |
|---|---|
| High-volume debug logs | Sampling in production |
| Hot path logging | Avoid or use async appenders |
| I/O overhead | Buffer and batch writes |
| Dynamic verbosity | Runtime-configurable log levels |
| Language | Library | Notes |
|---|---|---|
| Python | structlog | See majestic-data/etl-core-patterns |
| Ruby/Rails | Rails.event (8.1+), semantic_logger | See majestic-rails/dhh-coder/structured-events |
| Node.js | pino, winston with JSON formatter | |
| Go | slog (stdlib), zerolog | |
| Java | logback with JSON encoder |
| Scenario | Decision | Reason |
|---|---|---|
| User enters wrong password | info | Expected behavior, not an error |
| Payment gateway timeout | error + retry | Needs attention, affects user |
| Cache miss | debug | Only useful for performance analysis |
| User created account | info | Business event worth recording |
| Loop iteration 5000 of 10000 | Don't log | Creates noise, no debug value |
| External API returns 500 | warn or error | Depends on retry/fallback behavior |
| Background job started | info | Useful for job debugging |
| Background job failed after retries | error | Needs investigation |
When designing logs, verify you can answer:
Post-incident: Add the logs you wished you had.