docs(pinnacle): document wire_received_at for pipeline-latency benchmarking#241
Open
paperclip-resolver[bot] wants to merge 1 commit into
Open
docs(pinnacle): document wire_received_at for pipeline-latency benchmarking#241paperclip-resolver[bot] wants to merge 1 commit into
paperclip-resolver[bot] wants to merge 1 commit into
Conversation
…ipeline latency (SHA-3419) SHA-3419 surfaced a churn case where a Sharp+WS customer benchmarked SharpAPI's Pinnacle delivery latency against competitors using `odds_changed_at` and saw p50 = 2,049ms. That field carries Pinnacle's own trading-desk timestamp (it can routinely sit hours old on NBA/MLB player props because the desk isn't moving the line), not SharpAPI's ingest contribution, so the metric structurally penalises vendors who preserve source semantics vs vendors who stamp ingest time under the same field name. `wire_received_at` was added in PR #423 specifically as the pipeline-arrival field, but the docs only ever pointed customers at `last_seen_at` for freshness. `last_seen_at` advances every ingest cycle regardless of content change — useful as a heartbeat, but not the right field for ingest-latency benchmarking either. This change: - Updates `content/en/concepts/pinnacle-odds-changed-at.mdx` with a new "Benchmarking Pipeline Latency" section that explicitly names `wire_received_at` as the field to measure against, and explains the apples-to-oranges trap when comparing `odds_changed_at` across vendors. The fields table now lists all three timestamps with their distinct semantics. - Adds `wire_received_at` (and `odds_changed_at`) to the example JSON response and the field reference table on `content/en/api-reference/odds.mdx`. EN-only — the de/es/pt-BR concept pages are last-synced from the 2026-04 EN baseline and rebatched as a translation pass, same pattern the existing pinnacle-odds-changed-at page follows. Translation refresh can be a follow-up. Type: docs Refs SHA-3419
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SHA-3419 surfaced a churn case where a Sharp+WS customer benchmarked SharpAPI's Pinnacle delivery latency against competitors and saw `odds_changed_at` p50 = 2,049ms — but the metric was structurally misleading. `odds_changed_at` is Pinnacle's own trading-desk timestamp (carried forward across unchanged refreshes, can be hours old on NBA/MLB player props because the desk isn't moving the line), not SharpAPI's ingest contribution. Competitors that stamp ingest time under the same field name will look faster on that metric even when their underlying pipeline isn't.
PR #423 added `wire_received_at` as the field that does isolate SharpAPI's ingest contribution, but the docs only ever pointed customers at `last_seen_at` for freshness — which is wrong too (`last_seen_at` advances every cycle regardless of content change, so it's a heartbeat, not a delivery-latency benchmark).
This PR:
EN-only. The de/es/pt-BR concept pages are last-synced from the 2026-04 EN baseline (same pattern the existing pinnacle-odds-changed-at page follows). Translation refresh is the standard rebatch — happy to follow up separately if desired.
No engineering change required on the API side — the underlying field already ships, and pipeline-internal p50 is ~34ms / p95 ~1.9s on Pinnacle per `sharpapi_go_sse_row_wire_age_at_serialize_seconds`. The fix is making it discoverable.
Test plan
Type: docs
Refs SHA-3419