Define the StarIntel structured logging event contract #121

New issue

Open

opened 2026-08-25 09:22:13 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-25 09:22:13 +00:00

(Migrated from github.com)

Goal

Add a first-class structured logging contract to starintel-server so operational, audit, security, actor, ingest, lease, dispatch, dependency, and error events can be consumed consistently by syslog or future sinks.

Requirements

Define stable event envelope fields: timestamp, severity, service, component, event name, request/correlation ID, actor/target identity where safe, environment, duration, result/status, and schema version.
Keep payloads structured; avoid free-form message parsing as the primary contract.
Event classes at minimum: application, access, audit, security, deployment/worker-facing events where applicable, ingest, actor lifecycle, target/lease/dispatch, dependency health, and error.
Add correlation IDs across HTTP request -> actor/dispatch -> storage/broker interactions where the architecture supports it.
Explicit redaction/allowlist policy: never log Authorization headers, cookies, API keys, OAuth tokens, session secrets, passwords, raw request bodies, or sensitive document contents by default.
Bound string/payload sizes and sanitize control characters/newlines suitable for downstream syslog transport.
Logging failures must not crash normal application flow; audit events that require stronger guarantees must have explicitly documented semantics rather than accidental blocking.
Expose counters for dropped/suppressed logging events where practical.
Preserve backward-compatible human-readable local logs where useful while structured events become authoritative for machines.

Tests

Golden/fixture tests for representative event schemas.
Secret-redaction tests.
Oversized/malformed value tests.
Correlation propagation tests.
Prove logging-path failure does not change request/actor result unless an explicitly strict audit policy says otherwise.

Boundary

This issue defines and implements the event API/contract. Remote syslog transport is a separate issue.

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: research current logging/error/request paths in the repo; design and record the event contract; adversarial review + privacy/security threat model; autonomous decision gate; TDD-first implementation; exact-head unit/integration verification; push a focused branch and open/update a PR targeting master. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Add a first-class structured logging contract to `starintel-server` so operational, audit, security, actor, ingest, lease, dispatch, dependency, and error events can be consumed consistently by syslog or future sinks. ## Requirements - Define stable event envelope fields: timestamp, severity, service, component, event name, request/correlation ID, actor/target identity where safe, environment, duration, result/status, and schema version. - Keep payloads structured; avoid free-form message parsing as the primary contract. - Event classes at minimum: application, access, audit, security, deployment/worker-facing events where applicable, ingest, actor lifecycle, target/lease/dispatch, dependency health, and error. - Add correlation IDs across HTTP request -> actor/dispatch -> storage/broker interactions where the architecture supports it. - Explicit redaction/allowlist policy: never log Authorization headers, cookies, API keys, OAuth tokens, session secrets, passwords, raw request bodies, or sensitive document contents by default. - Bound string/payload sizes and sanitize control characters/newlines suitable for downstream syslog transport. - Logging failures must not crash normal application flow; audit events that require stronger guarantees must have explicitly documented semantics rather than accidental blocking. - Expose counters for dropped/suppressed logging events where practical. - Preserve backward-compatible human-readable local logs where useful while structured events become authoritative for machines. ## Tests - Golden/fixture tests for representative event schemas. - Secret-redaction tests. - Oversized/malformed value tests. - Correlation propagation tests. - Prove logging-path failure does not change request/actor result unless an explicitly strict audit policy says otherwise. ## Boundary This issue defines and implements the event API/contract. Remote syslog transport is a separate issue. ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: research current logging/error/request paths in the repo; design and record the event contract; adversarial review + privacy/security threat model; autonomous decision gate; TDD-first implementation; exact-head unit/integration verification; push a focused branch and open/update a PR targeting `master`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.