feat(dev/logs/metrics): Add sentry.timestamp.sequence definition to the logs and metrics specs
#16492
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -2,14 +2,17 @@ | |||||
| title: Metrics | ||||||
| description: Counter, gauge, and distribution metrics sent as batched trace_metric envelope items. | ||||||
| spec_id: sdk/telemetry/metrics | ||||||
| spec_version: 2.6.0 | ||||||
| spec_status: stable | ||||||
| spec_depends_on: | ||||||
| - id: sdk/foundations/transport/envelopes | ||||||
| version: ">=1.0.0" | ||||||
| - id: sdk/foundations/state-management/scopes/attributes | ||||||
| version: ">=1.0.0" | ||||||
| spec_changelog: | ||||||
| - version: 2.6.0 | ||||||
| date: 2026-02-06 | ||||||
|
There was a problem hiding this comment. In the changelog, version 2.6.0 is dated 2026-02-06 but the previous 2.5.0 entry is dated 2026-02-12. This makes the timeline inconsistent with the version ordering; update the 2.6.0 date (or the 2.5.0 date) so newer versions don’t appear to precede older ones.
Suggested change
|
||||||
| summary: Added sentry.timestamp.sequence default attribute for deterministic metric ordering | ||||||
| - version: 2.5.0 | ||||||
| date: 2026-02-12 | ||||||
| summary: Clarified sendDefaultPii gating for user attributes — allowed when user manually sets data | ||||||
|
|
@@ -114,6 +117,7 @@ SDKs **MUST** attach the following attributes to every metric by default: | |||||
| 2. `sentry.release` — the release set in the SDK, if defined. | ||||||
| 3. `sentry.sdk.name` — the name of the SDK that sent the metric. | ||||||
| 4. `sentry.sdk.version` — the version of the SDK that sent the metric. | ||||||
| 5. `sentry.timestamp.sequence` — a monotonically incrementing integer counter used to determine correct ordering of metrics when timestamps are identical. **MUST** be sent on runtimes with frozen or low-precision timers, **MAY** be omitted otherwise. See [Metric Ordering](#metric-ordering). | ||||||
|
|
||||||
| SDKs **SHOULD** minimize the number of default attributes. Metrics cardinality can explode quickly with too many attributes. New default attributes **SHOULD** only be added after significant feedback from users and discussion internally with the SDK and ingest teams. | ||||||
|
|
||||||
|
|
@@ -187,6 +191,25 @@ Whenever possible, metrics **SHOULD** be linked to replays. If a metric is recor | |||||
|
|
||||||
| </SpecSection> | ||||||
|
|
||||||
| ### Metric Ordering | ||||||
|
|
||||||
| <SpecSection id="metric-ordering" status="candidate" since="2.6.0"> | ||||||
|
|
||||||
| Some runtimes (notably Cloudflare Workers) freeze timer APIs (`Date.now()`, `performance.now()`) during synchronous execution, causing multiple metrics to share identical timestamps. SDKs that target runtimes where timestamps may be frozen or lack sub-millisecond precision **MUST** attach a `sentry.timestamp.sequence` integer attribute to every metric. SDKs that only target runtimes with reliable sub-millisecond timestamps **MAY** omit it. | ||||||
|
|
||||||
| When sent, the sequence number **MUST**: | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
|
||||||
| - Start at `0` when the SDK initializes. | ||||||
| - Increment by `1` for each metric that is captured. | ||||||
| - Reset to `0` when: | ||||||
| - The SDK is re-initialized. | ||||||
| - The current metric's integer millisecond differs from the previous metric's integer millisecond (i.e., `floor(timestamp_seconds * 1000)` changes). | ||||||
|
|
||||||
| The sequence provides deterministic ordering within a single SDK instance. It does not guarantee ordering across independent processes or workers, which have separate counters. The reset behavior ensures the sequence only increments for consecutive metrics that share the same timestamp. | ||||||
|
|
||||||
| </SpecSection> | ||||||
|
|
||||||
| ### Data Category and Rate Limiting | ||||||
|
|
||||||
| <SpecSection id="data-category-rate-limiting" status="stable" since="2.0.0"> | ||||||
|
|
||||||
| ### Data Category and Rate Limiting | ||||||
|
|
@@ -547,7 +570,8 @@ SentrySDK.metrics() | |||||
| "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, | ||||||
| "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, | ||||||
| "sentry.environment": { "value": "production", "type": "string" }, | ||||||
| "sentry.release": { "value": "1.0.0", "type": "string" }, | ||||||
| "sentry.timestamp.sequence": { "value": 0, "type": "integer" } | ||||||
| } | ||||||
| }, | ||||||
| { | ||||||
|
|
@@ -562,7 +586,8 @@ SentrySDK.metrics() | |||||
| "endpoint": { "value": "/api/users", "type": "string" }, | ||||||
| "method": { "value": "POST", "type": "string" }, | ||||||
| "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, | ||||||
| "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, | ||||||
| "sentry.timestamp.sequence": { "value": 1, "type": "integer" } | ||||||
|
Comment on lines
586
to
+590
There was a problem hiding this comment. In this full envelope example, the first metric item includes |
||||||
| } | ||||||
| }, | ||||||
| { | ||||||
|
|
@@ -577,7 +602,8 @@ SentrySDK.metrics() | |||||
| "cache_name": { "value": "user_sessions", "type": "string" }, | ||||||
| "region": { "value": "us-west-1", "type": "string" }, | ||||||
| "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, | ||||||
| "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, | ||||||
| "sentry.timestamp.sequence": { "value": 0, "type": "integer" } | ||||||
| } | ||||||
| }, | ||||||
| { | ||||||
|
|
@@ -593,7 +619,8 @@ SentrySDK.metrics() | |||||
| "table": { "value": "users", "type": "string" }, | ||||||
| "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, | ||||||
| "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, | ||||||
| "sentry.origin": { "value": "auto.db.graphql", "type": "string" }, | ||||||
| "sentry.timestamp.sequence": { "value": 1, "type": "integer" } | ||||||
| } | ||||||
| }, | ||||||
| { | ||||||
|
|
@@ -607,7 +634,8 @@ SentrySDK.metrics() | |||||
| "cohort": { "value": "beta", "type": "string" }, | ||||||
| "sentry.sdk.name": { "value": "sentry.javascript.browser", "type": "string" }, | ||||||
| "sentry.sdk.version": { "value": "10.17.0", "type": "string" }, | ||||||
| "sentry.replay_id": { "value": "36b75d9fa11f45459412a96c41bdf691", "type": "string" }, | ||||||
| "sentry.timestamp.sequence": { "value": 0, "type": "integer" } | ||||||
| } | ||||||
| } | ||||||
| ] | ||||||
|
|
||||||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would do this, or change them both to 'number', just so we are consistent.