add release orchestrator docs and sprints gaps fills
This commit is contained in:
220
docs/modules/release-orchestrator/operations/logging.md
Normal file
220
docs/modules/release-orchestrator/operations/logging.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user