purpose and motivation

Signed-off-by: Hilmar Falkenberg <hilmar.falkenberg@sap.com>

Author: hilmarf

docs/ideal-setup.md

@@ -1,10 +1,29 @@
 # Guidance Document: Reliable Audit Logging with OpenTelemetry
 
-This document describes the recommended 3-tier architecture (Client SDK → OpenTelemetry Collector → Final Storage Sink) for highly reliable
-audit log delivery. It focuses on minimizing data loss, ensuring long retention, and keeping operational complexity under control.
+This guidance paper explains recommended practices and an operational architecture for building a highly reliable audit logging pipeline
+using OpenTelemetry (OTel). Its primary goal is to help architects, platform engineers and application developers design audit log delivery
+that minimizes data loss, supports long retention, and remains operationally manageable.
+
+Purpose and motivation:
+
+- Provide concise, actionable recommendations for each layer of the pipeline (Client SDK → Collector → Final Storage) so teams can make
+  consistent design choices across environments.
+- Emphasize durability and predictable retention over low latency: audit logs often have legal and compliance requirements where losing
+  events is unacceptable and duplicates are preferable to missing data.
+- Reduce operational complexity by recommending focused components (dedicated collector pipelines, node‑local buffering where appropriate,
+  and clear monitoring/alerting points) rather than mixing audit logs with high‑volume telemetry.
+
+Audience:
+
+- Platform and SRE teams building or operating OTel collection and processing infrastructure.
+- Application and SDK developers who implement audit logging clients and integrations.
+- Security, compliance, and data governance teams evaluating retention and immutable storage requirements.
 
 ## Scope & Goals
 
+In scope: reliable delivery patterns, buffering strategies (client vs. agent), collector configuration recommendations, monitoring and
+runbooks, and guidance for final sink durability and compliance controls.
+
 Primary goals:
 
 - No audit event loss ("at least once" delivery – duplicates acceptable, loss is not).
@@ -14,6 +33,9 @@ Primary goals:
 
 Non-goals:
 
+Out of scope: vendor‑specific implementation details for every storage backend, full legal retention policy text, and high‑performance
+telemetry optimizations that trade durability for throughput.
+
 - Ultra low latency for audit logs (latency is secondary to durability).
 - Mixing audit and high-volume debug/info logs in the same pipeline.