Add PPAF write-region bookmark to CosmosDiagnostics

[Abhijeet Mohanty (jeet1995)]

Description

Adds a compact per-attempt ppaf bookmark to CosmosDiagnostics:

"ppaf": {
  "currWriteRegion": "east us",
  "since": "2026-09-03T12:34:56.789Z"
}

When PPAF has no designated override, diagnostics emit "ppaf": {}.

The designated region and timestamp are captured in an immutable, package-private snapshot when response statistics are recorded. This prevents later failover transitions or manager cleanup from rewriting historical diagnostics and avoids retaining endpoint-manager or routing state.

The compact ppaf object replaces the previous verbose PPAF diagnostics shape for both direct and gateway attempts.

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
33 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Abhijeet Mohanty (jeet1995)]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
33 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

The PR is marked WIP and there is a small diagnostics serialization consistency issue to address before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates Azure Cosmos DB Java SDK diagnostics to emit a compact per-attempt Per-Partition Automatic Failover (PPAF) bookmark under the ppaf key, capturing the designated write region and the time it was designated, while ensuring historical diagnostics are immutable once recorded.

Changes:

• Replaced the previous verbose PPAF diagnostics shape with a compact ppaf object (empty object when no override is active).
• Introduced an immutable PerPartitionAutomaticFailoverDiagnostics snapshot that is captured and then attached to recorded response/gateway statistics.
• Added/updated unit tests validating empty/populated PPAF diagnostics and record-time snapshot immutability.

File summaries

File	Description
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/perPartitionAutomaticFailover/PerPartitionAutomaticFailoverInfoHolder.java	Stores and serializes a compact immutable PPAF diagnostics snapshot (ppaf) as {} or { currWriteRegion, since }.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/perPartitionAutomaticFailover/PerPartitionAutomaticFailoverDiagnostics.java	New immutable snapshot type holding currWriteRegion and since for diagnostics serialization.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/perPartitionAutomaticFailover/PartitionLevelAutomaticFailoverInfo.java	Adds since tracking and snapshots region/timestamp into the new immutable diagnostics object.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/ClientSideRequestStatistics.java	Records PPAF snapshots at response/gateway record time and emits them under the ppaf field name.
sdk/cosmos/azure-cosmos/CHANGELOG.md	Documents the new compact ppaf diagnostics bookmark behavior.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/GlobalPartitionEndpointManagerForPPAFUnitTests.java	Adds tests asserting {} for empty PPAF and stable region/timestamp snapshots across direct and gateway stats.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Abhijeet Mohanty (jeet1995)]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).