Skip to content

docs(auditlog_ng): update user-guide - #329

Merged
jplbrun merged 7 commits into
mainfrom
docs/update-auditlog_ng-guide
Sep 14, 2026
Merged

jplbrun merged 7 commits into
mainfrom
docs/update-auditlog_ng-guide

Conversation

@jplbrun

@jplbrun jplbrun commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Disclaimer: Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

Description

Reworks the auditlog_ng user guide (src/sap_cloud_sdk/core/auditlog_ng/user-guide.md) so it follows the conventions used by the other module user guides, and corrects several statements that did not match the actual client behavior.

Structure aligned to the house convention

  • Retitled to # Audit Log NG User Guide and merged the redundant Overview into the single intro paragraph.
  • Renamed Prerequisites → Installation, added a Quick Start section (minimal create_client(tenant=...) → build event → send() → close()), and grouped the walkthrough, full example, one-off sends, serialization table, and auto-injection under a single Usage section.
  • Normalized headings to Title Case, removed the ✅/❌ emoji from the config tables in favor of plain Yes/No, and dropped the duplicate import block and the module-specific Running the Unit Tests section.

Corrected content (verified against the code)

  • Validation section replaced with an Error Handling section that lists the exceptions send() actually raises: ValidationError on schema failure (subclass of AuditLogNGError), ValueError for an invalid common.tenant_id, and RuntimeError on a closed client. The previous text incorrectly claimed a tenant_id UUID check and used the wrong exception types.
  • Fixed the config-path description to reflect the real precedence (config= → tenant → explicit kwargs).
  • Matched the validation regex shown in the docs ([a-zA-Z0-9._/~-]) to the pattern compiled in config.py.

Recommended setup updated

  • Automatic tenant/user injection now documents bootstrap(app) as the recommended way to wire IAS context + telemetry for new apps, with StarletteIASTelemetryMiddleware retained under a Legacy subsection for apps not yet on bootstrap().

Related Issue

N/A

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Code refactoring
  • Dependency update

How to Test

  1. Open src/sap_cloud_sdk/core/auditlog_ng/user-guide.md and read it top to bottom

Checklist

  • I have read the Contributing Guidelines
  • I have verified that my changes solve the issue
  • I have added/updated automated tests to cover my changes
  • All tests pass locally
  • I have verified that my code follows the Code Guidelines
  • I have updated documentation (if applicable)
  • I have added type hints for all public APIs
  • My code does not contain sensitive information (credentials, tokens, etc.)
  • I have followed Conventional Commits for commit messages

Breaking Changes

N/A

Additional Notes

None

- fold Overview into intro; drop duplicate section
- normalize headings to Title Case; drop stray trailing colon
- replace ✅/❌ with plain Yes/No in config tables
- correct config-path precedence ordering (config > tenant > kwargs)
- fix Validation section: ValidationError for schema failures,
  RuntimeError for closed client; remove nonexistent tenant_id
  UUID-validation claim
- remove duplicate Import section and idiosyncratic
  'Running the Unit Tests' section
@jplbrun
jplbrun force-pushed the docs/update-auditlog_ng-guide branch from 3375af8 to 1a77994 Compare September 11, 2026 22:23
@jplbrun
jplbrun marked this pull request as ready for review September 14, 2026 12:35
@jplbrun
jplbrun requested a review from a team as a code owner September 14, 2026 12:35
Comment thread uv.lock
@jplbrun
jplbrun merged commit ddc7e55 into main Sep 14, 2026
10 checks passed
@jplbrun
jplbrun deleted the docs/update-auditlog_ng-guide branch September 14, 2026 17:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants