diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md index e1010a0242..9507f1c7d8 100644 --- a/OpenTelemetryPlan/09-data-collection-reference.md +++ b/OpenTelemetryPlan/09-data-collection-reference.md @@ -346,51 +346,51 @@ Join a transaction's work to its ledger with `{span.current_ledger_seq=}`. #### Consensus Attributes -| Attribute | Type | Set On | Description | -| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| `consensus_ledger_id` | string | `consensus.round` | Previous ledger hash (used for deterministic trace ID) | -| `ledger_seq` | int64 | `consensus.round`, `consensus.ledger_close`, `consensus.accept`, `consensus.validation.send`, `consensus.accept.apply` | Ledger sequence number | -| `consensus_mode` | string | `consensus.round`, `consensus.proposal.send`, `consensus.ledger_close` | Node mode via `toDisplayString()`: `"Proposing"`, `"Observing"`, etc. | -| `consensus_round` | int64 | `consensus.proposal.send` | Consensus round number | -| `proposers` | int64 | `consensus.proposal.send`, `consensus.accept` | Number of proposers in the round | -| `round_time_ms` | int64 | `consensus.accept`, `consensus.accept.apply` | Total consensus round duration in milliseconds | -| `proposing` | boolean | `consensus.validation.send` | Whether this node was a proposer | -| `consensus_state` | string | `consensus.accept.apply` | Consensus outcome: `"finished"` or `"moved_on"` | -| `close_time` | int64 | `consensus.accept.apply` | Agreed-upon ledger close time (epoch seconds) | -| `close_time_correct` | boolean | `consensus.accept.apply` | Whether validators reached agreement on close time | -| `close_resolution_ms` | int64 | `consensus.accept.apply` | Close time rounding granularity in milliseconds | -| `parent_close_time` | int64 | `consensus.accept.apply` | Parent ledger's close time (epoch seconds) | -| `close_time_self` | int64 | `consensus.accept.apply` | This node's proposed close time | -| `close_time_vote_bins` | string | `consensus.accept.apply` | Histogram of close time votes from validators | -| `resolution_direction` | string | `consensus.accept.apply` | Resolution change: `"increased"`, `"decreased"`, or `"unchanged"` | -| `converge_percent` | int64 | `consensus.establish` | Convergence percentage threshold | -| `establish_count` | int64 | `consensus.establish` | Number of establish iterations completed | -| `proposers_agreed` | int64 | `consensus.establish` | Number of proposers that agreed on this round | -| `avalanche_threshold` | int64 | `consensus.update_positions` | Avalanche threshold for dispute resolution | -| `start_reason` | string | `consensus.phase.open` | Entry path: `"initial"` or `"recovered"` | -| `previous_close_agree` | bool | `consensus.phase.open` | Whether the prior ledger's close time was agreed | -| `peer_positions_at_open` | int64 | `consensus.phase.open` | Positions held after buffered proposals are replayed | -| `early_close_triggered` | bool | `consensus.phase.open` | Round skipped the timer because peers had already closed | -| `tx_sets_acquired` | int64 | `consensus.phase.open` | Peer transaction sets held at close, excluding our own | -| `close_reason` | string | `consensus.phase.open` | `"anomaly"`, `"others_closed"`, `"idle"`, or `"normal"` | -| `proposers_validated` | int64 | `consensus.phase.open` | Trusted validators of the previous ledger, at close | -| `close_time_avalanche_state` | string | `consensus.establish` | Terminal regime: `"init"`, `"mid"`, `"late"`, or `"stuck"` | -| `close_time_threshold` | int64 | `consensus.update_positions` | Close time agreement threshold | -| `have_close_time_consensus` | boolean | `consensus.update_positions` | Whether close time consensus has been reached | -| `agree_count` | int64 | `consensus.check` | Number of proposers that agree with our position | -| `disagree_count` | int64 | `consensus.check` | Number of proposers that disagree with our position | -| `threshold_percent` | int64 | `consensus.check` | Required agreement threshold percentage | -| `consensus_result` | string | `consensus.check` | Check result: `"yes"`, `"no"`, or `"expired"` | -| `quorum` | int64 | `consensus.check` | Required quorum for validation | -| `validation_count` | int64 | `consensus.check` | Number of validations received | -| `trace_strategy` | string | `consensus.round` | Trace sampling strategy used for this round | -| `consensus_round_id` | int64 | `consensus.round` | Deterministic round identifier (previous ledger seq + 1) | -| `mode_old` | string | `consensus.mode_change` | Previous consensus mode | -| `mode_new` | string | `consensus.mode_change` | New consensus mode | -| `tx_id` | string | `consensus.update_positions` | Disputed transaction ID | -| `dispute_our_vote` | boolean | `consensus.update_positions` | Our vote on the disputed transaction | -| `dispute_yays` | int64 | `consensus.update_positions` | Number of proposers voting to include | -| `dispute_nays` | int64 | `consensus.update_positions` | Number of proposers voting to exclude | +| Attribute | Type | Set On | Description | +| ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| `consensus_ledger_id` | string | `consensus.round` | Previous ledger hash (used for deterministic trace ID) | +| `ledger_seq` | int64 | `consensus.round`, `consensus.ledger_close`, `consensus.accept`, `consensus.validation.send`, `consensus.accept.apply` | Ledger sequence number | +| `consensus_mode` | string | `consensus.round`, `consensus.proposal.send`, `consensus.ledger_close` | Node mode via `toDisplayString()`: `"Proposing"`, `"Observing"`, etc. | +| `consensus_round` | int64 | `consensus.proposal.send` | Consensus round number | +| `proposers` | int64 | `consensus.proposal.send`, `consensus.accept` | Number of proposers in the round | +| `round_time_ms` | int64 | `consensus.accept`, `consensus.accept.apply` | Total consensus round duration in milliseconds | +| `proposing` | boolean | `consensus.validation.send` | Whether this node was a proposer | +| `consensus_state` | string | `consensus.accept.apply` | Consensus outcome: `"finished"` or `"moved_on"` | +| `close_time_ripple_epoch_s` | int64 | `consensus.accept.apply` | Agreed-upon ledger close time (Ripple epoch seconds) | +| `close_time_correct` | boolean | `consensus.accept.apply` | Whether validators reached agreement on close time | +| `close_resolution_ms` | int64 | `consensus.accept.apply` | Close time rounding granularity in milliseconds | +| `parent_close_time_ripple_epoch_s` | int64 | `consensus.accept.apply` | Parent ledger's close time (Ripple epoch seconds) | +| `close_time_self_ripple_epoch_s` | int64 | `consensus.accept.apply` | This node's proposed close time (Ripple epoch seconds) | +| `close_time_vote_bins` | string | `consensus.accept.apply` | Histogram of close time votes from validators | +| `resolution_direction` | string | `consensus.accept.apply` | Resolution change: `"increased"`, `"decreased"`, or `"unchanged"` | +| `converge_percent` | int64 | `consensus.establish` | Convergence percentage threshold | +| `establish_count` | int64 | `consensus.establish` | Number of establish iterations completed | +| `proposers_agreed` | int64 | `consensus.establish` | Number of proposers that agreed on this round | +| `avalanche_threshold` | int64 | `consensus.update_positions` | Avalanche threshold for dispute resolution | +| `start_reason` | string | `consensus.phase.open` | Entry path: `"initial"` or `"recovered"` | +| `previous_close_agree` | bool | `consensus.phase.open` | Whether the prior ledger's close time was agreed | +| `peer_positions_at_open` | int64 | `consensus.phase.open` | Positions held after buffered proposals are replayed | +| `early_close_triggered` | bool | `consensus.phase.open` | Round skipped the timer because peers had already closed | +| `tx_sets_acquired` | int64 | `consensus.phase.open` | Peer transaction sets held at close, excluding our own | +| `close_reason` | string | `consensus.phase.open` | `"anomaly"`, `"others_closed"`, `"idle"`, or `"normal"` | +| `proposers_validated` | int64 | `consensus.phase.open` | Trusted validators of the previous ledger, at close | +| `close_time_avalanche_state` | string | `consensus.establish` | Terminal regime: `"init"`, `"mid"`, `"late"`, or `"stuck"` | +| `close_time_threshold` | int64 | `consensus.update_positions` | Close time agreement threshold | +| `have_close_time_consensus` | boolean | `consensus.update_positions` | Whether close time consensus has been reached | +| `agree_count` | int64 | `consensus.check` | Number of proposers that agree with our position | +| `disagree_count` | int64 | `consensus.check` | Number of proposers that disagree with our position | +| `threshold_percent` | int64 | `consensus.check` | Required agreement threshold percentage | +| `consensus_result` | string | `consensus.check` | Check result: `"yes"`, `"no"`, or `"expired"` | +| `quorum` | int64 | `consensus.check` | Required quorum for validation | +| `validation_count` | int64 | `consensus.check` | Number of validations received | +| `trace_strategy` | string | `consensus.round` | Trace sampling strategy used for this round | +| `consensus_round_id` | int64 | `consensus.round` | Deterministic round identifier (previous ledger seq + 1) | +| `mode_old` | string | `consensus.mode_change` | Previous consensus mode | +| `mode_new` | string | `consensus.mode_change` | New consensus mode | +| `tx_id` | string | `consensus.update_positions` | Disputed transaction ID | +| `dispute_our_vote` | boolean | `consensus.update_positions` | Our vote on the disputed transaction | +| `dispute_yays` | int64 | `consensus.update_positions` | Number of proposers voting to include | +| `dispute_nays` | int64 | `consensus.update_positions` | Number of proposers voting to exclude | **Tempo query**: `{span.consensus_mode="Proposing"}` to find rounds where node was proposing. @@ -398,15 +398,15 @@ Join a transaction's work to its ledger with `{span.current_ledger_seq=}`. #### Ledger Attributes -| Attribute | Type | Set On | Description | -| --------------------- | ------- | ------------------------------------------------------------- | ------------------------------------------------ | -| `ledger_seq` | int64 | `ledger.build`, `ledger.validate`, `ledger.store`, `tx.apply` | Ledger sequence number | -| `close_time` | int64 | `ledger.build` | Ledger close time (epoch seconds) | -| `close_time_correct` | boolean | `ledger.build` | Whether close time was agreed upon by validators | -| `close_resolution_ms` | int64 | `ledger.build` | Close time rounding granularity in milliseconds | -| `tx_count` | int64 | `ledger.build`, `tx.apply` | Transactions in the ledger | -| `tx_failed` | int64 | `ledger.build`, `tx.apply` | Failed transactions in the ledger | -| `validations` | int64 | `ledger.validate` | Number of validations received for this ledger | +| Attribute | Type | Set On | Description | +| --------------------------- | ------- | ------------------------------------------------------------- | ------------------------------------------------ | +| `ledger_seq` | int64 | `ledger.build`, `ledger.validate`, `ledger.store`, `tx.apply` | Ledger sequence number | +| `close_time_ripple_epoch_s` | int64 | `ledger.build` | Ledger close time (Ripple epoch seconds) | +| `close_time_correct` | boolean | `ledger.build` | Whether close time was agreed upon by validators | +| `close_resolution_ms` | int64 | `ledger.build` | Close time rounding granularity in milliseconds | +| `tx_count` | int64 | `ledger.build`, `tx.apply` | Transactions in the ledger | +| `tx_failed` | int64 | `ledger.build`, `tx.apply` | Failed transactions in the ledger | +| `validations` | int64 | `ledger.validate` | Number of validations received for this ledger | **Tempo query**: `{span.ledger_seq=12345}` to find all spans for a specific ledger. diff --git a/docs/telemetry-runbook.md b/docs/telemetry-runbook.md index 0b3e7222fd..a315cf40d8 100644 --- a/docs/telemetry-runbook.md +++ b/docs/telemetry-runbook.md @@ -172,11 +172,11 @@ hash); `tx.preflight` is stateless and omits both. ### Ledger Spans -| Span Name | Source File | Attributes | Description | -| ----------------- | ---------------- | ----------------------------------------------------------------------- | ----------------------------- | -| `ledger.build` | BuildLedger.cpp | `ledger_seq`, `close_time`, `close_time_correct`, `close_resolution_ms` | Ledger build during consensus | -| `ledger.validate` | LedgerMaster.cpp | `ledger_seq`, `validations` | Ledger promoted to validated | -| `ledger.store` | LedgerMaster.cpp | `ledger_seq` | Ledger stored in history | +| Span Name | Source File | Attributes | Description | +| ----------------- | ---------------- | -------------------------------------------------------------------------------------- | ----------------------------- | +| `ledger.build` | BuildLedger.cpp | `ledger_seq`, `close_time_ripple_epoch_s`, `close_time_correct`, `close_resolution_ms` | Ledger build during consensus | +| `ledger.validate` | LedgerMaster.cpp | `ledger_seq`, `validations` | Ledger promoted to validated | +| `ledger.store` | LedgerMaster.cpp | `ledger_seq` | Ledger stored in history | ### Peer Spans