docs consolidation and others

docs/modules/telemetry/guides/logging.md

@@ -0,0 +1,49 @@
+# Logging Standards (DOCS-OBS-50-003)
+
+Last updated: 2025-12-15
+
+## Goals
+- Deterministic, structured logs for all services.
+- Keep tenant safety and redaction guarantees while enabling search, correlation, and offline analysis.
+
+## Log shape (JSON)
+Required fields:
+- `timestamp` (UTC ISO-8601)
+- `tenant`, `workload` (service name), `env`, `region`, `version`
+- `level` (`debug|info|warn|error|fatal`)
+- `category` (logger/category name), `operation` (verb/action)
+- `trace_id`, `span_id`, `correlation_id` (if external)
+- `message` (concise, no secrets)
+- `status` (`ok|error|fault|throttle`)
+- `error.code`, `error.message` (redacted), `retryable` (bool) when status != ok
+
+Optional but recommended:
+- `resource` (subject id/purl/path when safe), `http.method`, `http.status_code`, `duration_ms`, `host`, `pid`, `thread`.
+
+## Offline Kit / air-gap import fields
+When emitting logs for Offline Kit import/activation flows, keep field names stable:
+- Required scope key: `tenant_id`
+- Common keys: `bundle_type`, `bundle_digest`, `bundle_path`, `manifest_version`, `manifest_created_at`
+- Force activation keys: `force_activate`, `force_activate_reason`
+- Outcome keys: `result`, `reason_code`, `reason_message`
+- Quarantine keys: `quarantine_id`, `quarantine_path`
+
+## Redaction rules
+- Never log Authorization headers, tokens, passwords, private keys, full request/response bodies.
+- Redact to `"[redacted]"` and add `redaction.reason` (`secret|pii|policy`).
+- Hash low-cardinality identifiers when needed (`sha256` hex) and mark `hashed=true`.
+
+## Determinism & offline posture
+- Stable key ordering not required, but field set must be consistent per log type.
+- No external enrichment; rely on bundled metadata (service map, tenant labels).
+- All times UTC; newline-delimited JSON (NDJSON); LF line endings.
+
+## Sampling & rate limits
+- Info logs rate-limited per component (default 100/s); warn/error/fatal never sampled.
+- Structured audit logs (`category=audit`) are never sampled and must include `actor`, `action`, `target`, `result`.
+
+## Validation checklist
+- [ ] Required fields present and non-empty.
+- [ ] No secrets/PII; redaction markers recorded.
+- [ ] Correlation fields (`trace_id`, `span_id`) set when spans exist.
+- [ ] Log level matches outcome (errors use warn/error/fatal only).