feat: Add delta() function for gauge metrics

[pulpdrew]

Summary

Closes HDX-2323

This PR adds a delta() function that can be applied to gauge metrics.

The delta() function is intended to match Prometheus' delta() function:

delta(v range-vector) calculates the difference between the first and last value of each time series element in a range vector v [...]The delta is extrapolated to cover the full time range as specified in the range vector selector, so that it is possible to get a non-integer result even if the sample values are all integers.

The delta() function is applied to the metric values within each (Time Bucket, Attributes Hash) group. Since there can be multiple Attribute Hashes per time bucket, there can be multiple delta values per bucket. Therefore, the aggregation function (min, max, etc) is then be applied on top of the delta values, to select a value to show for the bucket.

Counter-intuitive Behavior

1. Short granularity results in delta = 0. If there is only one data point (per attribute hash) in each time bucket, then the delta is 0.
2. An increase in the metric value from one time bucket to the next can be associated with a negative delta, since the delta is calculated within the bucket, not between buckets.
3. Deltas are extrapolated to the bucket duration, to match Prometheus behavior. Example: Suppose bucket granularity is 1 minute, and we have a data point at 1 second and 31 seconds with a difference of 10. The delta is 20 because the 30 second delta (10) is extrapolated out to 60 seconds.

Testing

Alerts can be configured on the delta values

The delta checkbox is hidden if the selected metric is not a gauge

[changeset-bot]

🦋 Changeset detected

Latest commit: 56ed67c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/common-utils	Minor
@hyperdx/app	Minor
@hyperdx/api	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
hyperdx-v2-oss-app	Ready	Preview	Comment	Sep 9, 2025 0:22am

[pulpdrew]

One thought is that eventually this could be a drop-down with various other functions that could be applied, if we implement other functions. I kept it simple for now though.

[github-actions]

Stably Runner - Test Suite - 'Smoke Test'

Test Suite Run Result: 🔴 Failure (1/4 tests failed) [dashboard]

Failed Tests:

• Advanced Search Workflow - Traces

---

This comment was generated from stably-runner-action

[dhable]

Had one question about the timestamp division but looks solid. You'll also want to write a changeset description for the release notes. You can use yarn changeset if you want a TUI interface to writing the changeset.

[dhable]

Shoot. I forgot to mention that we have a series of integration tests for these queries in https://github.com/hyperdxio/hyperdx/blob/main/packages/api/src/clickhouse/__tests__/renderChartConfig.test.ts.

These tests run the query against a CH instance and real data. It would be great to have a test case or two about the delta function here. This is one of the few places that are well suited to these kind of automated tests because it's a pure input->output function.