logging-observability

Files (1)

• SKILL.md

SKILL.md (first lines)

# Logging and Observability

## Structured Logging

Always use structured logging (JSON format) instead of unstructured text. Structured logs are machine-parseable, searchable, and can be aggregated across services.

### Standard Log Entry Format

```json
{
  "timestamp": "2024-03-15T14:30:22.123Z",
  "level": "INFO",
  "message": "Order processed successfully",
  "service": "order-service",
  "version": "1.4.2",
  "correlationId": "req-abc123",
  "userId": "user-456",
  "orderId": "ord-789",
  "durationMs": 234,
  "environment": "production"
}
```

### Required Fields

Every log entry must include:

| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | ISO 8601 string | When the event occurred (UTC) |
| `level` | string | Log severity level |
| `message` | string | Human-readable description of the event |
| `service` | string | Name of the service emitting the log |

### Recommended Fields

| Field | Type | Description |
|-------|------|-------------|
| `correlationId` | string | Request or trace identifier for cross-service correlation |
| `version` | string | Application version or commit hash |
| `environment` | string | Deployment environment (production, staging, etc.) |
| `userId` | string | Authenticated user identifier (if applicable) |
| `durationMs` | number | Operation duration in milliseconds |
| `error` | object | Error details when level is ERROR |

### Implementation Examples

```javascript
// Node.js with pino
const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  formatters: { level: (label) => ({ level: label.toUpperCase() }) },
  timestamp: pino.stdTimeFunctions.isoTime,
  base: { service: 'order-service', version: process.env.APP_VERSION || 'unknown' },
});

logger.info({ orderId: 'ord-789', durationMs: 234 }, 'Order processed successfully');
logger.error({ err, orderId: 'ord-789' }, 'Failed to process order');
```

```python
# Python with structlog
import structlog
structlog.configure(processors=[
    structlog.processors.TimeStamper(fmt="iso"),
    structlog.processors.add_log_level,
    structlog.processors.JSONRenderer(),
])
logger = structlog.get_logger(service="order-service")
logger.info("order_processed", order_id="ord-789", duration_ms=234)
```

## Log Levels Usage Guide

Choose the correct log level based on the audience and urgency:

| Level | When to Use | Examples | Audience |
|-------|-------------|----------|----------|
| **ERROR** | Something failed and requires attention. The operation could not complete. | Unhandled exception, database connection lost, payment processing failed, external API returned 5xx | On-call engineer (triggers alert) |
| **WARN** | Something unexpected happened but the operation continued. May need attention soon. | Deprecated API used, retry succeeded after failure, cache miss on hot path, connection pool near limit | Engineering team (review in daily triage) |
| **INFO** | Normal operational events worth recording. The happy path. | Request handled, order created, user logged in, migration completed, deploy started | Operations team (dashboard monitoring) |
| **DEBUG** | Detailed information useful for diagnosing issues. Not enabled in production by default. | SQL query with parameters, HTTP request/response details, cache hit/miss, algorithm intermediate steps | Developers (enabled during investigation) |
| **TRACE** | Very fine-grained detail. Rarely used outside local development. | Function entry/exit, loop iterations, variable state at each step | Developers (local debugging only) |

### Level Selection Rules

- If it means waking someone up at 3 AM, it is **ERROR**.
- If it means something is degraded but not broken, it is **WARN**.
- If it is the normal outcome of a user or system action, it is **INFO**.
- If it would help debug a problem but is too noisy for production, it is **DEBUG**.
- If you would only want it while stepping through code, it is **TRACE**.

## What to Log and What NOT to Log

### Log These Events

| Category | Events |
|----------|--------|
| Requests | Incoming HTTP requests (method, path, status, duration). API calls to external services. |
| Authentication | Login success, login failure, logout, session expiry, MFA challenge. |
| Authorization | Access denied events with user, resource, and required permission. |
| Errors | Unhandled exceptions, failed operations, timeout events, circuit breaker trips. |
| State Changes | Record creation/update/deletion, status transitions, configuration changes. |
| Performance | Slow queries (above threshold), response time percentiles, queue depth. |
| Business Events | Order placed, payment processed, subscription changed, export completed. |

### Never Log These

| Category | Reason | Alternative |
|----------|--------|-------------|
| Passwords | Credential exposure | Log event type only ("login_attempt") |
| API keys and tokens | Credential exposure | Log last 4 characters at most |
| Credit card numbers | PCI compliance violation | Log last 4 digits only |
| Social Security Numbers | PII regulation violation | Log event type only |
| Session tokens | Session hijacking risk | Log session ID prefix or hash |
| Personal health data | HIPAA violation | Log event type with anonymized reference |
| Full request bodies with sensitive fields | Data exposure | Log sanitized version or field names only |

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources