-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
docs(dev-docs): Add metrics telemetry specs #15178
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Co-authored-by: David Herberth <[email protected]>
|
||
At minimum the SDK needs to implement the following methods for each metric type: | ||
|
||
- `Sentry.metrics.increment(name, value, options)` - Increment a counter |
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.
- `Sentry.metrics.increment(name, value, options)` - Increment a counter | |
- `Sentry.metrics.count(name, value, options)` - Increment a counter |
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.
Can count take a negative integer/float?
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 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`). |
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.
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. |
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.
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.
: **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. |
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.
Can you supply both an integer and a float to a metric? So call increment(3)
and then increment(4.5)
?
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 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 |
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.
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) |
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.
Why can't we put units on counts?
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.
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
### 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. |
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.
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)
sdk/telemetry
formetrics
./sdk/data-model/envelope-items/
for the trace metric itemTook the logs specs as a template.
ref getsentry/sentry-javascript#17883