wide-event-logging

Files (4)

• SKILL.md
• ANALYTICS.md · references/
• BACKEND.md · references/
• FRONTEND.md · references/

SKILL.md (first lines)

# Wide Event Logging

Implement the "Wide Event" or "Canonical Log Line" pattern: emit ONE
context-rich JSON event per request instead of scattered log statements.

## Mental Model Shift

> Log what happened to this request, not what your code is doing.

Traditional logging produces 10-20 lines per request that are impossible to
correlate. Wide events produce ONE line with 30-50+ fields containing everything
needed to debug.

## Core Principles

1. **One Request, One Event**: Emit a single wide event at request end
2. **High Cardinality**: Include user_id, request_id, session_id, trace_id
3. **High Dimensionality**: Include 30-50+ fields covering all context
4. **Business Context**: Add subscription tier, cart value, feature flags
5. **Structured JSON**: Enable SQL-like queries, not grep

## Field Categories

Every wide event SHOULD include fields from these categories:

### Request Context (Required)

```json
{
  "request_id": "req_8bf7ec2d",
  "trace_id": "abc123def456",
  "timestamp": "2025-01-15T10:23:45.612Z",
  "method": "POST",
  "path": "/api/checkout",
  "status_code": 200,
  "duration_ms": 1247
}
```

### User Context (Required for authenticated requests)

```json
{
  "user_id": "user_456",
  "session_id": "sess_abc123",
  "subscription_tier": "premium",
  "account_age_days": 847,
  "lifetime_value_cents": 284700
}
```

### Business Context (Domain-specific)

```json
{
  "cart_id": "cart_xyz",
  "cart_item_count": 3,
  "cart_total_cents": 15999,
  "coupon_applied": "SAVE20",
  "payment_method": "card",
  "payment_provider": "stripe"
}
```

### Infrastructure Context

```json
{
  "service_name": "checkout-service",
  "service_version": "2.4.1",
  "deployment_id": "deploy_789",
  "region": "us-east-1",
  "hostname": "checkout-prod-3"
}
```

### Error Context (When errors occur)

```json
{
  "error_type": "PaymentError",
  "error_code": "card_declined",
  "error_message": "Card declined by issuer",
  "error_retriable": false,
  "stripe_decline_code": "insufficient_funds"
}
```

### Performance Context

```json
{
  "db_query_count": 3,
  "db_total_ms": 145,
  "cache_hit": true,
  "external_call_count": 2,
  "external_total_ms": 890
}
```

### Feature Flags

```json
{
  "feature_flags": {
    "new_checkout_flow": true,
    "express_payment": false
  }
}
```

## Implementation by Context

### Backend Services

See [references/BACKEND.md](references/BACKEND.md) for complete patterns
including:

- Middleware implementation (Express, Hono, Fastify)

From garnertb/skills, MIT.

More from garnertb/skills