Skip to content

Conversation

chargome
Copy link
Member

  • 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.

ref getsentry/sentry-javascript#17883

@chargome chargome self-assigned this Oct 10, 2025
Copy link

vercel bot commented Oct 10, 2025

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

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

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

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can count take a negative integer/float?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


`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`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


`span_id`

: **String, optional**. The span id for the metric.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +79 to +85
: **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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can count take a negative integer/float?

- `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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why can't we put units on counts?

Copy link
Member

@k-fish k-fish left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +437 to +439
### 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants