# Logging Specification

> Structured logging format and categories for the Release Orchestrator.

**Status:** Planned (not yet implemented)
**Source:** [Architecture Advisory Section 13.2](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
**Related Modules:** [Observability Overview](overview.md), [Tracing](tracing.md)

## Overview

The Release Orchestrator uses structured JSON logging with consistent format, correlation IDs, and context propagation for all components.

---

## Structured Log Format

### JSON Schema

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```yaml
# 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
```

---

## See Also

- [Observability Overview](overview.md)
- [Tracing](tracing.md)
- [Alerting](alerting.md)
- [Security Overview](../security/overview.md)