Observability: optional OpenObserve/OTLP support via config

Coordinate with https://github.com/lost-rob0t/starintel-server/issues/128 and https://github.com/starintel-labs/starintel-infra/issues/78. Add optional operator-controlled OpenTelemetry/OTLP observability to StarIntel billing, with OpenObserve as a supported destination rather than a hard runtime dependency. ## Configuration/defaults - [ ] Add an optional observability block to the normal runtime/init configuration. - [ ] Default OFF. Missing config means no exporter initialization, no outbound observability traffic, and no required OpenObserve/collector service. - [ ] Configure endpoint/protocol, service/environment/stream identity, enabled signals, bounded batching/queue/timeouts, and auth only through runtime environment/secret references. - [ ] Exporter failure is non-fatal and MUST NOT change billing/accounting/idempotency semantics. ## Instrumentation - [ ] Instrument ledger/state-transition processing, verified webhook/event handling, provider-adapter latency/status, reconciliation jobs, entitlement projection, queue/backpressure where present, retries, and failures. - [ ] Metrics may include bounded operation/state-transition counts, latency, reconciliation counts, provider error classes, webhook validation outcomes, and service health. - [ ] Correlate traces/logs with internal operation/event references only where safe and necessary. ## Data-minimization boundary Use an explicit allow-list for exported attributes. By default, NEVER export: - customer email/name or other direct customer identity; - payment-method/card/PAN data; - provider API/webhook secrets, Authorization headers, or raw webhook bodies; - wallet addresses, seed/private-key material, or crypto transaction identifiers; - invoice/payment/provider identifiers that could expose customer activity unless separately reviewed; - entitlement/account identifiers that permit cross-system user tracking; - arbitrary billing metadata or exception payloads containing the above. Prefer low-cardinality operational fields such as operation kind, provider kind, normalized state/error class, duration bucket, counts, service/version/environment, and success/failure status. ## Tests/docs - [ ] Disabled mode proves zero observability network activity/exporter initialization. - [ ] Configured OTLP export test verifies endpoint/resource/stream handling with sanitized fixture data. - [ ] Exporter-down test proves canonical billing processing continues unchanged. - [ ] Redaction/allow-list fixtures prove sensitive billing/customer/provider fields cannot escape. - [ ] Document generic OTLP and OpenObserve examples. Docs: https://openobserve.ai/docs/ingestion/ ## Explicit exclusion This issue is operator-owned deployment observability only. Do not add anonymous usage analytics, product telemetry, customer tracking, persistent installation identifiers, or a StarIntel-operated global telemetry collector here. Product telemetry requires a separate explicit opt-in/privacy decision.

lost-rob0t commented

2026-08-26 07:51:45 +00:00

(Migrated from github.com)

Coordinate with https://github.com/lost-rob0t/starintel-server/issues/128 and https://github.com/starintel-labs/starintel-infra/issues/78.

Add optional operator-controlled OpenTelemetry/OTLP observability to StarIntel billing, with OpenObserve as a supported destination rather than a hard runtime dependency.

Configuration/defaults

Add an optional observability block to the normal runtime/init configuration.
Default OFF. Missing config means no exporter initialization, no outbound observability traffic, and no required OpenObserve/collector service.
Configure endpoint/protocol, service/environment/stream identity, enabled signals, bounded batching/queue/timeouts, and auth only through runtime environment/secret references.
Exporter failure is non-fatal and MUST NOT change billing/accounting/idempotency semantics.

Instrumentation

Instrument ledger/state-transition processing, verified webhook/event handling, provider-adapter latency/status, reconciliation jobs, entitlement projection, queue/backpressure where present, retries, and failures.
Metrics may include bounded operation/state-transition counts, latency, reconciliation counts, provider error classes, webhook validation outcomes, and service health.
Correlate traces/logs with internal operation/event references only where safe and necessary.

Data-minimization boundary

Use an explicit allow-list for exported attributes. By default, NEVER export:

customer email/name or other direct customer identity;
payment-method/card/PAN data;
provider API/webhook secrets, Authorization headers, or raw webhook bodies;
wallet addresses, seed/private-key material, or crypto transaction identifiers;
invoice/payment/provider identifiers that could expose customer activity unless separately reviewed;
entitlement/account identifiers that permit cross-system user tracking;
arbitrary billing metadata or exception payloads containing the above.

Prefer low-cardinality operational fields such as operation kind, provider kind, normalized state/error class, duration bucket, counts, service/version/environment, and success/failure status.

Tests/docs

Disabled mode proves zero observability network activity/exporter initialization.
Configured OTLP export test verifies endpoint/resource/stream handling with sanitized fixture data.
Exporter-down test proves canonical billing processing continues unchanged.
Redaction/allow-list fixtures prove sensitive billing/customer/provider fields cannot escape.
Document generic OTLP and OpenObserve examples.

Docs: https://openobserve.ai/docs/ingestion/

Explicit exclusion

This issue is operator-owned deployment observability only. Do not add anonymous usage analytics, product telemetry, customer tracking, persistent installation identifiers, or a StarIntel-operated global telemetry collector here. Product telemetry requires a separate explicit opt-in/privacy decision.

Rows
Columns

Observability: optional OpenObserve/OTLP support via config #6

Configuration/defaults

Instrumentation

Data-minimization boundary

Tests/docs

Explicit exclusion