Skip to content

Add snapshot diagnostics and opt-in audit and quota telemetry - #150

Closed
arkmish wants to merge 9 commits into
branch-3.6from
armishra/zk-iteration2
Closed

arkmish wants to merge 9 commits into
branch-3.6from
armishra/zk-iteration2

Conversation

@arkmish

@arkmish arkmish commented Sep 28, 2026

Copy link
Copy Markdown

Description

Add offline snapshot diagnostics and opt-in server observability on branch-3.6, while preserving client protocol, persistence formats, authentication decisions and quota enforcement.

  • Backport SnapshotComparer and SnapshotRecursiveSummary from upstream commits f90060b83da4bfcca58ada93a57fedb40a069387 and 05b215994f5e145c2758c4089828b57ba471b329, retaining provenance and compatible CLI behavior.
  • Add OfflineAuditExporter with validated snapshot-only node/namespace/session metadata, source identity checks, deterministic traversal, bounded output and atomic completion manifests. It exports no znode payloads and performs no transaction-log replay.
  • Extend audit records with opt-in payload lengths, truthful single/multi outcomes, TTL-create coverage and scalar session/authentication bindings. Preserve request buffers and isolate audit-reporting failures from valid client operations.
  • Add metadata-only quota_stats on the AdminServer, protected by an exact namespace allowlist that defaults empty.

Tests

Added SnapshotComparerTest, SnapshotRecursiveSummaryTest, OfflineAuditExporterTest, AuditHelperTest and SessionAuthAuditTest; extended CommandsTest, DataTreeTest, AuditEventTest, StandaloneServerAuditTest and Slf4JAuditLoggerTest.

The changed-surface Maven selection and relevant existing server regressions were rerun on JDK 11 with maven.compiler.release=8, surefire-forkcount=1, and a loopback RMI hostname for local JMX fixtures:

Tests run: 258, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

Coverage includes native compressed/corrupt snapshots, source/output aliases and limits, real CLI execution, byte-size boundaries, unknown owner encodings, transaction rollback, buffer preservation, sanitized identities, auth/session outcomes, quota metadata/ranges and bounded reads.

Native assembly/launcher checks and Java 8 API/bytecode compatibility checks passed. This is a targeted regression selection, not the full repository suite; an actual Java 8 VM and Windows launcher execution were not available.

  • Local code review completed

Automated per-task and cross-package source reviews were completed. Maintainer review and CI remain pending for this draft.

Changes that Break Backward Compatibility (Optional)

No protocol, stored-format, authentication/ACL decision or quota-enforcement change is introduced. Existing audit APIs and ordinary legacy formatting are retained.

  • zookeeper.audit.enhanced.enable defaults false and additionally requires existing audit enablement. Enhanced consumers must understand the versioned fields, per-binding cardinality and documented strict-consumer rollout boundary before enablement.
  • zookeeper.quotaStats.allowedNamespaces defaults to an empty JSON array; no namespace is implicitly approved.
  • Native tools reject malformed/unsupported input rather than silently choosing another snapshot. Snapshot-only output is not current-state, transaction-consistency, liveness or content-equality evidence.

Documentation (Optional)

Updated repository documentation:

  • zookeeper-docs/src/main/resources/markdown/zookeeperTools.md
  • zookeeper-docs/src/main/resources/markdown/zookeeperAuditLogs.md
  • zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md

All operational enablement remains explicit. This draft does not deploy or activate the new surfaces.

🤖 Generated with GitHub Copilot CLI

arkmish and others added 9 commits September 25, 2026 13:55
Restore Apache ZooKeeper's SnapshotComparer (ZOOKEEPER-3427, Michael Han), from f90060b, and SnapshotRecursiveSummary (ZOOKEEPER-4566, Szabolcs Bukros), from 05b2159.

Keep Java 8 and existing CLI/test dependencies. Add checksum-aware, closed-stream loading, explicit invalid-input exits, native launchers, snapshot-only semantics documentation, and synthetic CLI regression tests. Preserve size/count comparison, threshold behavior and inclusion of ephemeral znodes.

Verified 27 new CLI tests plus 11 existing snapshot tests, scoped Checkstyle and SpotBugs, Java 8 release compilation, and the built binary distribution launchers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Stream versioned node, namespace and true-session metadata without values or credential-bearing ACL IDs. Validate the selected source, enforce optional output budgets and publish a checksummed manifest atomically last.

Reuse the D1 native snapshot loader and expose iterative preorder traversal without changing the summary CLI. Keep capture and owner uncertainty explicit; do not replay transaction logs or infer recovery completeness.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Decode typed requests without changing their buffers, cover TTL writes, correlate multi members by position and distinguish atomic rollback from commit. Add safe enhanced ACL metadata, deletion identity and observable audit failures while retaining legacy logging defaults.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Use validated concrete built-in authentication providers for enhanced user extraction, redact custom and unknown identity representations, and preserve legacy behavior. Cover the registered default-getUserName leak with real client authentication.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Report audit failures through independently best-effort counter and diagnostic operations without recursive retries. Verify an applied write still receives success and multiple system deletions complete when both the audit sink and error counter fail.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Carry the captured enhanced mode into event construction without rereading the property. Preserve public delegating overloads and keep every multi parent/member on the same mode. Cover deterministic ACL off-to-on and multi mode transitions with subsequent genuine v2 emission.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Emit sanitized scalar auth_scheme/user bindings for valid attachments and actual authentication outcomes. Preserve C1 feature gates, mode snapshots and best-effort reporting; account explicitly for setup bindings in write-focused tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expose quota_stats through AdminServer with a default-empty exact-path JSON allowlist. Sample existing quota records without subtree traversal or write-path changes, report unavailable data explicitly, and cover validation, concurrent changes and restart behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document that the pinned local JOBS parser rejects unknown fields and staging quarantines those records. Require updating and validating the consumer before enabling additive v2 producer fields; leave runtime behavior unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@arkmish

arkmish commented Sep 28, 2026

Copy link
Copy Markdown
Author

Superseded by six focused draft PRs, with tests kept beside each feature:

The combined split branches produce exactly the same Git tree as this PR, including all tests, documentation and reviewed fixes. Every boundary was validated independently and the recombined changes passed the original changed-surface regression selection. The original armishra/zk-iteration2 branch is preserved; nothing is merged or deployed.

@arkmish arkmish closed this Sep 28, 2026
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.

1 participant