Logging Specification

Structured logging format and categories for the Stella Ops Release Orchestrator.

Audience: Operators and developers who consume Release Orchestrator logs or wire them into a log-aggregation pipeline. Status: Planned — this is the reference logging contract for the module. Source: Stella Ops Orchestrator Architecture advisory, section 13.2. Related: Metrics · Tracing · Alerting · Operations Overview

Overview

The Release Orchestrator emits structured JSON logs with a consistent envelope, correlation IDs, and context propagation across every component. Logs carry W3C trace context (trace_id/span_id) so a single request can be followed across the metrics, logs, and traces signals — see Tracing for the propagation model.

Structured Log Format

JSON Schema

{
  "timestamp": "2026-01-09T14:32:15.123Z",
  "level": "info",
  "module": "promotion-manager",
  "message": "Promotion approved",
  "context": {
    "tenant_id": "uuid",
    "promotion_id": "uuid",
    "release_id": "uuid",
    "environment": "prod",
    "user_id": "uuid"
  },
  "details": {
    "approvals_count": 2,
    "gates_passed": ["security", "approval", "freeze"],
    "decision": "allow"
  },
  "trace_id": "abc123",
  "span_id": "def456",
  "duration_ms": 45
}

Log Levels

Level	Usage
`error`	Errors requiring attention; failures that impact functionality
`warn`	Potential issues; degraded functionality; approaching limits
`info`	Significant events; state changes; audit-relevant actions
`debug`	Detailed debugging info; request/response bodies
`trace`	Very detailed tracing; internal state; performance profiling

Log Categories

Category	Examples
`api`	Request received, response sent, validation errors
`promotion`	Promotion requested, approved, rejected, completed
`deployment`	Deployment started, task assigned, completed, failed
`security`	Gate evaluation, vulnerability found, policy violation
`agent`	Agent registered, heartbeat, task execution
`workflow`	Workflow started, step executed, completed
`integration`	Integration tested, resource discovered, webhook received

Logging Examples

API Request

{
  "timestamp": "2026-01-09T14:32:15.123Z",
  "level": "info",
  "module": "api",
  "message": "Request received",
  "context": {
    "tenant_id": "uuid",
    "user_id": "uuid"
  },
  "details": {
    "method": "POST",
    "path": "/api/v1/promotions",
    "status": 201,
    "duration_ms": 125
  },
  "trace_id": "abc123",
  "span_id": "def456"
}

Promotion Event

{
  "timestamp": "2026-01-09T14:32:15.123Z",
  "level": "info",
  "module": "promotion-manager",
  "message": "Promotion approved",
  "context": {
    "tenant_id": "uuid",
    "promotion_id": "uuid",
    "release_id": "uuid",
    "environment": "prod",
    "user_id": "uuid"
  },
  "details": {
    "approvals_count": 2,
    "gates_passed": ["security", "approval", "freeze"],
    "decision": "allow"
  },
  "trace_id": "abc123",
  "span_id": "def456",
  "duration_ms": 45
}

Security Gate Failure

{
  "timestamp": "2026-01-09T14:32:15.123Z",
  "level": "warn",
  "module": "security",
  "message": "Security gate blocked promotion",
  "context": {
    "tenant_id": "uuid",
    "promotion_id": "uuid",
    "release_id": "uuid",
    "environment": "prod"
  },
  "details": {
    "gate_name": "security-gate",
    "reason": "Critical vulnerability found",
    "vulnerabilities": {
      "critical": 1,
      "high": 3
    }
  },
  "trace_id": "abc123",
  "span_id": "def456"
}

Sensitive Data Masking

The following fields are automatically masked in logs:

Field Type	Masking Strategy
Passwords	Not logged
API Keys	First 4 and last 4 chars only
Tokens	Hash only
PII	Redacted
Credentials	Not logged

Example

{
  "message": "Authentication succeeded",
  "details": {
    "api_key": "sk_l...abcd",
    "token_hash": "sha256:abc123..."
  }
}

Correlation IDs

All logs include correlation IDs for request tracing:

Field	Description
`trace_id`	W3C Trace Context trace ID
`span_id`	Current operation span ID
`correlation_id`	Business-level correlation (optional)

Log Aggregation

Recommended log aggregation setup:

# Fluent Bit configuration
[INPUT]
    Name   tail
    Path   /var/log/stella/*.log
    Parser json

[FILTER]
    Name   nest
    Match  *
    Operation lift
    Nested_under context

[OUTPUT]
    Name   opensearch
    Match  *
    Host   opensearch.example.com
    Index  stella-logs