docs(dev-docs): Add metrics telemetry specs #15178

chargome · 2025-10-10T10:13:34Z

Adds a new entry to sdk/telemetry for metrics.
Adds a new entry to /sdk/data-model/envelope-items/ for the trace metric item

Took the logs specs as a template.

vercel · 2025-10-10T10:13:39Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Ready	Preview	Comment	Oct 14, 2025 5:14pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
sentry-docs	Ignored	Preview		Oct 14, 2025 5:14pm

develop-docs/sdk/telemetry/metrics.mdx

Co-authored-by: David Herberth <[email protected]>

develop-docs/sdk/telemetry/metrics.mdx

cleptric · 2025-10-14T13:02:36Z

develop-docs/sdk/telemetry/metrics.mdx

+
+At minimum the SDK needs to implement the following methods for each metric type:
+
+- `Sentry.metrics.increment(name, value, options)` - Increment a counter


Suggested change

- `Sentry.metrics.increment(name, value, options)` - Increment a counter

- `Sentry.metrics.count(name, value, options)` - Increment a counter

Can count take a negative integer/float?

I think counters in metrics should be always increasing – but there is e.g. a separate up/down-counter in otel. We don't prevent passing negative integers from the SDK though

develop-docs/sdk/telemetry/metrics.mdx

AbhiPrasad · 2025-10-14T14:38:38Z

develop-docs/sdk/telemetry/metrics.mdx

+
+`name`
+
+: **String, required**. The name of the metric. This should follow a hierarchical naming convention using dots as separators (e.g., `api.response_time`, `db.query.duration`).


This should follow a hierarchical naming convention using dots as separators

Will this be enforced by the backend? Or just recommended to users? Are spaces in the name valid?

AbhiPrasad · 2025-10-14T14:39:05Z

develop-docs/sdk/telemetry/metrics.mdx

+
+`span_id`
+
+: **String, optional**. The span id for the metric.


Is this is the span id of the parent span? Or does this represent the metric item itself? If it does, we can probably remove this from the client protocol.

develop-docs/sdk/telemetry/metrics.mdx

AbhiPrasad · 2025-10-14T14:42:04Z

develop-docs/sdk/telemetry/metrics.mdx

+: **Number, required**. The numeric value of the metric. The interpretation depends on the metric `type`:
+
+- For `counter` metrics: the count to increment by (should default to 1)
+- For `gauge` metrics: the current value
+- For `distribution` metrics: a single measured value
+
+Integers should be a 64-bit signed integer, while doubles should be a 64-bit floating point number.


Can you supply both an integer and a float to a metric? So call increment(3) and then increment(4.5)?

I suggest we stick to integers for counters. @k-fish I assume the value eventually ends up in an EAP attribute where integers and floats go into separate columns. Mixing both types might then make queries tricky, plus you'd have to deal with precision loss for very large numbers.

Tagging on to the discussion, is the SDK expected to truncate large integers? If so, how do we truncate, or do we just reject integers that are beyond 64 bits.

In particular, 64-bit floats are natural in Python, but integers are arbitrary precision (under the hood more memory is allocated if the user provides a large integer).

AbhiPrasad · 2025-10-14T14:42:58Z

develop-docs/sdk/telemetry/metrics.mdx

+
+At minimum the SDK needs to implement the following methods for each metric type:
+
+- `Sentry.metrics.increment(name, value, options)` - Increment a counter


Can count take a negative integer/float?

AbhiPrasad · 2025-10-14T14:43:51Z

develop-docs/sdk/telemetry/metrics.mdx

+- `name` **String, required**: The name of the metric
+- `value` **Number, required**: The value of the metric
+- `options` **Object, optional**: An object containing the following properties:
+  - `unit` **String, optional**: The unit of measurement (distribution and gauge only)


Why can't we put units on counts?

develop-docs/sdk/telemetry/metrics.mdx

k-fish

Thanks for this @chargome 👍

A couple notes:

This api might change before a beta takes place, so we may want to leave it up in PR for a while
Metrics may have different limits than logs (eg. metric size limit is 2kib currently, might lower it) so may want to make note of that when it comes to adding attributes. We also probably need indicate what the failure mode should be if you have too much attribute data on the scope that you're trying to add to each metric

develop-docs/sdk/telemetry/metrics.mdx

k-fish · 2025-10-14T14:49:23Z

develop-docs/sdk/telemetry/metrics.mdx

+### Buffering
+
+Metrics should be buffered and aggregated before being sent. SDKs should keep a buffer of metrics on the client that flushes out based on some kind of condition. We recommend following the [batch processor specification](/sdk/telemetry/spans/batch-processor/) outlined in the develop docs, but you should choose the approach that works best for your platform.


Careful with the term aggregated here since generally trace metrics may have a span id, timestamp etc. that we want to preserve, making aggregation on the sdk side not desirable, although we may offer special aggregation functions / ability in the future.

Also as an aside, the metrics and log buffers are currently set to the same in the js sdk (100 items) but we may consider changing that if we keep the low metric size limit (~1-2kib)

coolguyzone · 2025-10-16T22:50:57Z

develop-docs/sdk/data-model/envelope-items.mdx

+
+Item type `"trace_metric"` contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item.
+
+Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`.


Suggested change

Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`.

Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`. Both the `item_count` and `content_type` fields are required.

coolguyzone · 2025-10-16T22:51:21Z

develop-docs/sdk/data-model/envelope-items.mdx

+
+Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`.
+
+It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header.


Suggested change

It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header.

It's okay to mix metrics from different traces into the same `trace_metric` envelope item, but if you do, you MUST NOT attach a DSC (dynamic sampling context) to the envelope header.

coolguyzone

LGTM!

alexander-alderman-webb · 2025-10-17T07:44:18Z

develop-docs/sdk/telemetry/metrics.mdx

+Metrics are sent to Sentry via the `trace_metric` envelope item. Each `trace_metric` envelope item contains a batch of metric payloads encoded as JSON, allowing for transmission of multiple metrics in a single envelope.
+
+### `trace_metric` Envelope Item
+
+The `trace_metric` envelope item is an object that contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item. See [Appendix A](#appendix-a-example-trace_metric-envelope) for an example `trace_metric` envelope.


nitpick: These paragraphs could be consolidated.

alexander-alderman-webb · 2025-10-17T07:48:48Z

develop-docs/sdk/telemetry/metrics.mdx

+```python
+# Increment a counter
+Sentry.metrics.count('button.clicks', 1, {
+  'attributes': {'button_id': 'submit', 'page': 'checkout'}
+})
+
+# Set a gauge value
+Sentry.metrics.gauge('db.connection_pool.active', 42, {
+  'unit': 'connection',
+  'attributes': {'pool_name': 'main_db', 'database': 'postgres'}
+})
+
+# Record a distribution
+Sentry.metrics.distribution('page.load_time', 245.7, {
+  'unit': 'millisecond',
+  'attributes': {'page': '/dashboard', 'browser': 'chrome'}
+})
+```


Non-blocking.

Suggested change

```python

# Increment a counter

Sentry.metrics.count('button.clicks', 1, {

'attributes': {'button_id': 'submit', 'page': 'checkout'}

})

# Set a gauge value

Sentry.metrics.gauge('db.connection_pool.active', 42, {

'unit': 'connection',

'attributes': {'pool_name': 'main_db', 'database': 'postgres'}

})

# Record a distribution

Sentry.metrics.distribution('page.load_time', 245.7, {

'unit': 'millisecond',

'attributes': {'page': '/dashboard', 'browser': 'chrome'}

})

```

```python

# Increment a counter

Sentry.metrics.count(

'button.clicks',

1,

attributes={'button_id': 'submit', 'page': 'checkout'},

)

# Set a gauge value

Sentry.metrics.gauge(

'db.connection_pool.active',

42,

unit='connection',

attributes={'pool_name': 'main_db', 'database': 'postgres'},

)

# Record a distribution

Sentry.metrics.distribution(

'page.load_time',

245.7,

unit='millisecond',

attributes={'page': '/dashboard', 'browser': 'chrome'},

)

alexander-alderman-webb · 2025-10-17T08:00:30Z

develop-docs/sdk/telemetry/metrics.mdx

+: **Number, required**. The numeric value of the metric. The interpretation depends on the metric `type`:
+
+- For `counter` metrics: the count to increment by (should default to 1)
+- For `gauge` metrics: the current value
+- For `distribution` metrics: a single measured value
+
+Integers should be a 64-bit signed integer, while doubles should be a 64-bit floating point number.


Tagging on to the discussion, is the SDK expected to truncate large integers? If so, how do we truncate, or do we just reject integers that are beyond 64 bits.

In particular, 64-bit floats are natural in Python, but integers are arbitrary precision (under the hood more memory is allocated if the user provides a large integer).

alexander-alderman-webb · 2025-10-17T08:07:43Z

develop-docs/sdk/telemetry/metrics.mdx

+- `Sentry.metrics.count(name, value, options)` - Increment a counter
+- `Sentry.metrics.gauge(name, value, options)` - Set a gauge value
+- `Sentry.metrics.distribution(name, value, options)` - Add a distribution value


From an API perspective, would any of these changes make it clearer?

Suggested change

- `Sentry.metrics.count(name, value, options)` - Increment a counter

- `Sentry.metrics.gauge(name, value, options)` - Set a gauge value

- `Sentry.metrics.distribution(name, value, options)` - Add a distribution value

- `Sentry.metrics.increment(name, count, options)` - Increment a counter

- `Sentry.metrics.gauge(name, value, options)` - Set a gauge value

- `Sentry.metrics.distribution(name, sample, options)` - Add a distribution value

alexander-alderman-webb · 2025-10-17T08:10:53Z

develop-docs/sdk/telemetry/metrics.mdx

+
+#### Method Signatures
+
+The parameters for these methods are:


This sounds prescriptive right now.

Suggested change

The parameters for these methods are:

The parameters for these methods should be the following, or an equivalent form that is more natural for SDK's language:

alexander-alderman-webb · 2025-10-17T08:19:44Z

develop-docs/sdk/telemetry/metrics.mdx

+`unit`
+
+: **String, optional**. The unit of measurement for the metric value.


Can we clarify in the spec who modifies the input or drops the metric if the user provides malformed arguments with the wrong type?

For example, I provide an integer in the unit field when calling metrics.count(). Does the SDK

drop the metric; and/or

coerce into a string; and/or

send an integer and relies on downstream systems to discard the metric?

add metrics docs

3957c4f

chargome self-assigned this Oct 10, 2025

vercel bot deployed to Preview – develop-docs October 10, 2025 10:15 View deployment

update resources

3cd9dc2

chargome changed the title ~~docs(dev-docs): Add metrics docs~~ docs(dev-docs): Add metrics telemetry specs Oct 10, 2025

vercel bot deployed to Preview – develop-docs October 10, 2025 10:27 View deployment

Dav1dde reviewed Oct 10, 2025

View reviewed changes

develop-docs/sdk/telemetry/metrics.mdx Outdated Show resolved Hide resolved

develop-docs/sdk/telemetry/metrics.mdx Outdated Show resolved Hide resolved

Update develop-docs/sdk/telemetry/metrics.mdx

4ca5e7b

Co-authored-by: David Herberth <[email protected]>

vercel bot deployed to Preview – develop-docs October 10, 2025 11:17 View deployment

.

8058f51

vercel bot deployed to Preview – develop-docs October 10, 2025 11:46 View deployment

chargome marked this pull request as ready for review October 13, 2025 07:45

chargome requested review from AbhiPrasad and k-fish October 13, 2025 08:50

cleptric requested changes Oct 14, 2025

View reviewed changes

AbhiPrasad reviewed Oct 14, 2025

View reviewed changes

k-fish reviewed Oct 14, 2025

View reviewed changes

chargome added 5 commits October 14, 2025 18:25

use count

4eb6bc8

update docs for flag

80f1227

add note on sendDefaultPii

da457fc

user agent parsing

7b06da1

one more increment leftover

af220b6

vercel bot deployed to Preview – develop-docs October 14, 2025 17:14 View deployment

coolguyzone reviewed Oct 16, 2025

View reviewed changes

coolguyzone approved these changes Oct 16, 2025

View reviewed changes

alexander-alderman-webb reviewed Oct 17, 2025

View reviewed changes


		At minimum the SDK needs to implement the following methods for each metric type:

		- `Sentry.metrics.increment(name, value, options)` - Increment a counter

	- `Sentry.metrics.increment(name, value, options)` - Increment a counter
	- `Sentry.metrics.count(name, value, options)` - Increment a counter


		`name`

		: String, required. The name of the metric. This should follow a hierarchical naming convention using dots as separators (e.g., `api.response_time`, `db.query.duration`).


		`span_id`

		: String, optional. The span id for the metric.

		### Buffering

		Metrics should be buffered and aggregated before being sent. SDKs should keep a buffer of metrics on the client that flushes out based on some kind of condition. We recommend following the [batch processor specification](/sdk/telemetry/spans/batch-processor/) outlined in the develop docs, but you should choose the approach that works best for your platform.


		Item type `"trace_metric"` contains an array of metric payloads encoded as JSON. This allows for multiple metric payloads to be sent in a single envelope item.

		Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`.


		Only a single trace_metric container is allowed per envelope. The `item_count` field in the envelope item header must match the amount of metrics sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.trace_metric+json`.

		It's okay to mix metrics from different traces into the same trace_metric envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header.

	The parameters for these methods are:
	The parameters for these methods should be the following, or an equivalent form that is more natural for SDK's language:

		`unit`

		: String, optional. The unit of measurement for the metric value.

Uh oh!

docs(dev-docs): Add metrics telemetry specs #15178

Are you sure you want to change the base?

docs(dev-docs): Add metrics telemetry specs #15178

Uh oh!

Conversation

chargome commented Oct 10, 2025

Uh oh!

vercel bot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

k-fish left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

vercel bot commented Oct 10, 2025 •

edited

Loading