Stage 6 · Operate
Logging Operations
Log Schema Design
Choosing stable JSON fields for severity, service, trace_id, user actions, and error classes.
Why Schema Matters
A consistent log schema ensures logs are queryable, correlatable, and parsable across all services. Without a schema, each team invents their own fields, making cross-service queries impossible and log analysis unreliable.
Required Fields
Every log entry must include a minimum set of fields. These fields enable filtering, correlation, and basic analysis. Do not make these fields optional or use different names across services.
{
"timestamp": "2024-01-15T10:30:00.123Z",
"level": "info",
"service": "api-gateway",
"message": "Request processed"
}| Field | Type | Format | Purpose |
|---|---|---|---|
| timestamp | string | ISO 8601 | When the event occurred |
| level | string | error|warn|info|debug | Severity classification |
| service | string | kebab-case | Which service produced the log |
| message | string | Free text | Human-readable description |
Optional Fields
Optional fields add context for specific log types. Include them when relevant but do not require them for every log entry. These fields should be consistent in naming when used.
{
"trace_id": "abc123def456",
"span_id": "789xyz",
"request_id": "req-001",
"user_id": "user-123",
"error_class": "PaymentDeclined",
"duration_ms": 45,
"method": "POST",
"path": "/api/v1/payments",
"status": 200
}Field Naming Conventions
| Convention | Example | Use |
|---|---|---|
| snake_case | trace_id | Standard for log fields |
| camelCase | traceId | Avoid in logs |
| kebab-case | api-gateway | Service names |
| dot.notation | http.method | OTel semantic conventions |
Schema Examples
{
"timestamp": "2024-01-15T10:30:00.123Z",
"level": "info",
"service": "api-gateway",
"trace_id": "abc123def456",
"request_id": "req-001",
"method": "POST",
"path": "/api/v1/users",
"status": 200,
"duration_ms": 45,
"user_agent": "Mozilla/5.0",
"client_ip": "10.0.0.1",
"message": "Request processed"
}Treat your log schema as a versioned contract. When you need to add new fields, increment the schema version. This ensures backward compatibility and lets you migrate services gradually.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.