@@ -6,6 +6,239 @@ PR — keep the `hyperdx-release-notes` comment marker intact when editing so yo
66edits survive regeneration. Per-package detail lives in each
77` packages/*/CHANGELOG.md ` .
88
9+ ## v2.41.0 — 2026-10-09
10+
11+ <!-- hyperdx-release-notes version=2.41.0 inputs=3cd9796f20ec -->
12+
13+ ** Query attribution and a session secret change**
14+
15+ Every ClickHouse query HyperDX runs — PromQL included — is now tagged with the
16+ part of the product that issued it, so a row in ` system.query_log ` tells you
17+ which dashboard, tile, search or alert put that load on your cluster. PromQL
18+ sources also pick up the "Minimum auto granularity" setting that metric sources
19+ already had, so charts left on auto granularity stop inferring buckets finer
20+ than your scrape interval. This release also restores Map attribute
21+ autocomplete on tables guarded by a ClickHouse row policy, where the search bar
22+ and the chart, alert and dashboard-filter editors had stopped suggesting any
23+ keys at all. If you run HyperDX with authentication enabled, set
24+ ` EXPRESS_SESSION_SECRET ` before upgrading — the API no longer falls back to a
25+ public default secret.
26+
27+ ### 💥 Breaking Changes
28+
29+ - ** The API no longer signs sessions with a public default secret** :
30+ ` EXPRESS_SESSION_SECRET ` used to fall back to the public value `hyperdx is
31+ cool 👋`. With authentication enabled, leaving it unset — or setting it
32+ explicitly to that old public value — now gets a random secret generated at
33+ startup and reported once in the logs, which means restarting the API signs
34+ every user out and replicas do not share sessions between them. Set it to a
35+ random string (` openssl rand -hex 32 ` ) in any deployment with authentication
36+ enabled; the public value remains available only in the no-auth local demo
37+ (#3129 , thanks @28Hus !).
38+ - ** AI assistant calls are traced with the GenAI semantic conventions** : with
39+ the AI SDK upgraded to v7, HyperDX now emits ` invoke_agent ` , ` chat ` and
40+ ` execute_tool ` spans carrying ` gen_ai.* ` attributes in place of the legacy
41+ ` ai.* ` span shape, and team and user attribution moves from
42+ ` ai.telemetry.metadata.* ` to ` hyperdx.team.id ` and ` user.id ` , plus
43+ ` gen_ai.conversation.id ` when a session is known. Update any saved search,
44+ alert or dashboard keyed on the old ` ai.* ` span names or attributes (#3261 ).
45+
46+ ### ✨ New Features
47+
48+ - ** Attribute ClickHouse queries to the dashboard, search or alert behind
49+ them** : every query HyperDX issues now carries a small JSON ` log_comment ` and
50+ a ` query_id ` beginning with ` hdx- ` , naming the surface that asked — a
51+ dashboard and tile, a saved search, an alert, an MCP tool, the chart explorer,
52+ session replay or a field lookup — along with the source id and, from the
53+ server, the trace id of the request. Group ` system.query_log ` by
54+ ` JSONExtractString(log_comment, 'surface') ` to see where your read load
55+ actually goes, or read the ` query_id ` straight out of ` system.processes ` to
56+ name a query while it is still running, with no JSON parsing needed. PromQL
57+ queries are attributed the same way, whether they run through the
58+ ` prometheusQuery ` /` prometheusQueryRange ` table functions or ClickHouse's
59+ Prometheus HTTP API, so a PromQL-backed dashboard, tile or search shows up in
60+ the same accounting as the rest. The exception is the probes that skip
61+ settings processing — the ` system.settings ` , server version and
62+ Cloud-detection checks, and the onboarding connection test — which get a
63+ ` query_id ` but an empty ` log_comment ` (#3155 , #3300 , thanks @tommyzli !).
64+ - ** Minimum auto granularity on PromQL sources** : a PromQL source can now set a
65+ "Minimum auto granularity", as a metric source already could, and it floors
66+ the step of any chart left on auto granularity so a short date range cannot
67+ infer buckets finer than your metrics actually arrive. ` $__rate_interval ` now
68+ takes that value as the source's scrape interval instead of always assuming
69+ 15s — still 15s when the setting is left unset — and a granularity you choose
70+ explicitly on a tile is never changed (#3292 , thanks @karl-power !).
71+ - ** A series limit for PromQL charts** : the Display Settings drawer now offers a
72+ Series Limit on PromQL line, stacked bar, pie and bar charts, so a query that
73+ fans out over hundreds of series stays readable. Line and stacked bar charts
74+ keep the top N series by peak value — leave it empty for the default of 250,
75+ or set 0 for unlimited — while pie and bar charts keep the N largest slices or
76+ bars, and show all of them when it is left empty (#3294 , thanks
77+ @karl-power !).
78+ - ** A series mode for builder heatmaps** : a heatmap built in the chart builder
79+ now offers a series mode, so the tile can be driven by the series your query
80+ returns rather than only by the single distribution it plotted before. The API
81+ and the MCP tools understand the new mode too, so a heatmap saved with it
82+ renders and queries the same way outside the app. A PromQL source can drive a
83+ series-mode heatmap as well, so a PromQL query's series can be read as a
84+ heatmap rather than only as lines (#3291 , #3298 , #3313 , thanks @pulpdrew !).
85+ - ** Stacked line charts** : time series tiles gain a stacked line (stacked area)
86+ display type, so a set of series can be read as a total and its composition
87+ on one chart rather than as separate lines you add up by eye. The app, the
88+ API and the CLI all understand the new display type (#3290 , thanks
89+ @pulpdrew !).
90+ - ** Single-select dashboard filters** : a dashboard filter can now be configured
91+ to take one value at a time instead of a set, so a filter that is only ever
92+ meant to scope the dashboard to a single value behaves that way for everyone
93+ using it (#3295 , thanks @pulpdrew !).
94+ - ** A PromQL variable format that escapes to suit the filter** : a dashboard
95+ variable used in a PromQL expression now has a ` promql ` format that escapes
96+ its value according to whether the filter it comes from is single- or
97+ multi-select, so one expression holds up whether the variable resolves to a
98+ single value or to several (#3297 , thanks @pulpdrew !).
99+ - ** Choose how property keys are ordered in the row side panel** : the JSON
100+ viewer sorts keys alphabetically, which is the right default for a wide
101+ ClickHouse ` Map(...) ` column such as ` ProfileEvents ` but hides the order the
102+ columns are stored in. The properties view options menu now offers "Sort keys
103+ A–Z", "Sort keys Z–A" and "Original order", and your choice persists with the
104+ viewer's other options. Array elements keep their index order in every mode,
105+ and in "Original order" integer-like keys — HTTP status codes, say — still
106+ list first in ascending order, since that is how parsed JavaScript objects
107+ order their keys (#3126 , thanks @MikeShi42 !).
108+ - ** Label each instance in the tab title and sidebar** : operators running more
109+ than one HyperDX — one per region, say — can now set
110+ ` NEXT_PUBLIC_INSTANCE_LABEL ` to a short label such as "UK", which is appended
111+ to the browser tab title and shown in the sidebar, so a wall of tabs tells you
112+ which instance you are looking at. It is empty by default and changes nothing
113+ unless you set it; the sidebar shows the label only while the sidebar is
114+ expanded, where it takes the place of the UTC badge when both are set (#3250 ,
115+ thanks @arj22 !).
116+
117+ ### 🧪 Experimental
118+
119+ - ** Onboarding detects a PromQL source for you** : with PromQL enabled
120+ (` NEXT_PUBLIC_ENABLE_PROMQL=true ` ), onboarding's source auto-detection now
121+ also creates a PromQL source for a ClickHouse TimeSeries engine table. It
122+ prefers ` prometheus.metrics ` , the table the ClickHouse Prometheus docs
123+ suggest, then one named ` metrics_ts ` , and otherwise takes the only TimeSeries
124+ table on the connection — and a service that has nothing but a TimeSeries
125+ table is no longer sent off to manual source setup (#3310 , thanks
126+ @karl-power !).
127+ - ** A default PromQL source is provisioned only where PromQL is on** : a
128+ ` DEFAULT_SOURCES ` entry of kind ` promql ` is now skipped unless
129+ ` ENABLE_PROMQL=true ` , so one sources list can carry a PromQL source and still
130+ be used on deployments that have PromQL turned off, where it simply is not
131+ created (#3311 , thanks @karl-power !).
132+
133+ ### 🔧 Improvements
134+
135+ - ** A trace's total duration in the waterfall controls bar** : the trace
136+ waterfall now shows how long the whole trace took in wall-clock terms, right
137+ in its controls bar, so you can size up a trace without reading it off the
138+ timeline (#3051 , thanks @milansanjeev !).
139+ - ** Heatmaps respect explicit and minimum granularity** : a heatmap now honours
140+ the granularity you set on the tile, and the minimum auto granularity its
141+ source carries, when it buckets time, rather than choosing its own interval
142+ regardless (#3305 , thanks @pulpdrew !).
143+ - ** Heatmap value and count edited in the chart editor** : a heatmap's value and
144+ count inputs now sit inline in the chart editor form, alongside the rest of
145+ the tile's settings, rather than apart from them (#3277 , thanks @pulpdrew !).
146+ - ** Rename a dashboard or saved search by clicking its title** : the pencil
147+ button is gone — click the name where it sits to edit it in place, with Enter
148+ or a click away to save and Escape to revert (#3278 , thanks @elizabetdev !).
149+ - ** The metric drill-down warning can be dismissed for good** : drilling down
150+ from a metric chart whose source has no correlated log source shows a warning,
151+ and closing it now hides it permanently in that browser instead of having it
152+ return on the next drill-down. Clicking through several times no longer stacks
153+ copies of the warning either (#3304 , thanks @knudtty !).
154+ - ** ` clickstack_list_metrics ` is faster and no longer fails at the deadline** :
155+ the MCP metric listing scans metric names only — about 9x fewer bytes read per
156+ kind — fetches unit and description just for the page it returns, and scans
157+ kinds in parallel. When the time budget runs out it returns the kinds that
158+ finished, reports the rest in ` partialFailure ` , and hands back a ` nextCursor `
159+ that resumes at the kind that timed out instead of failing the whole call; it
160+ also stops dropping later kinds when one kind exactly fills a page. Both
161+ ` clickstack_list_metrics ` and ` clickstack_describe_metric ` now get 30s rather
162+ than 10s, matching the other MCP query tools (#3260 ).
163+
164+ ### 🐛 Bug Fixes
165+
166+ - ** Map key autocomplete works again on tables with a row policy** : ClickHouse
167+ refuses the ` mergeTreeTextIndex ` lookup with ` ACCESS_DENIED ` on any table
168+ carrying a row policy, and key discovery treated that as "no keys" rather than
169+ trying anything else, so autocomplete offered nothing for ` Map ` columns such
170+ as ` ResourceAttributes ` on those tables. A failed text index read now falls
171+ through to the remaining strategies, reading keys from the policy-filtered
172+ source table and skipping the key rollup table the policy does not cover
173+ (#3268 ).
174+ - ** The filter sidebar keeps the Map keys you are most likely to want** : where a
175+ text index serves key discovery, the keys were grouped and cut off at the
176+ limit with no ordering at all, so a ` Map ` column holding more keys than the
177+ limit showed an arbitrary subset of them. Both of those paths now order by
178+ ` sum(cardinality) DESC ` , keeping the most frequent keys, as the key rollup
179+ path already did (#3254 , thanks @BilalAtique !).
180+ - ** Map key lookups stop serving one caller another's shortened list** : the
181+ metadata cache keyed a column's Map keys without recording how many had been
182+ asked for, so MCP discovery and the AI assistant's field discovery, which
183+ request different numbers of keys, could each be handed the other's cached
184+ answer and work from fewer keys than they asked for. The requested limit is
185+ now part of the cache key (#3339 , thanks @qoega !).
186+ - ** Plain searches against a FixedString column such as a trace id run again** :
187+ a bare search term compiled to ` hasToken(lower(TraceId), ...) ` , which
188+ ClickHouse rejects on a FixedString column, so searching an OTel TraceId
189+ errored instead of returning the rows. Those haystacks are now cast to
190+ ` String ` first (#3271 , thanks @milansanjeev !).
191+ - ** Heatmap hover follows the cell under the cursor** : hovering a heatmap now
192+ highlights and describes the cell you are actually pointing at, instead of a
193+ neighbouring one (#3273 , thanks @pulpdrew !).
194+ - ** Services charts show that they are refreshing** : the Services dashboard's
195+ list-bar and latency histogram charts kept their previous data through a
196+ refresh with no sign that anything was loading, and the histogram could flash
197+ "Loading Chart Data..." in place of the chart. Both now hold their data on
198+ screen and pulse while the refetch runs, like every other chart
199+ (#3229 , thanks @Harshul1484 !).
200+ - ** Consistent source kind labels on the Sources page** : the source form's data
201+ type options and the sources list now read Logs, Traces, OTel metrics,
202+ Sessions and PromQL, so the names match between the two and "OTel" is spelt
203+ the same way everywhere (#3257 , thanks @teeohhem !).
204+ - ** ` clickstack_describe_source ` returns partial results instead of timing
205+ out** : the MCP describe deadline is now 30s, matching the other MCP query
206+ tools, and hitting it no longer throws away the work. The tool returns the
207+ schema and samples it managed to gather, marked ` partial ` with the
208+ ` skippedStages ` it had to drop, and only reports a timeout error when the
209+ column schema never loaded at all (#3259 ).
210+ - ** The trace breakdown tool stops at the MCP timeout and says why** :
211+ ` clickstack_trace_top_time_consuming_operations ` now runs its queries under
212+ the MCP request timeout and its ` max_execution_time ` ceiling, which a source's
213+ ` querySettings ` can no longer override, so the tool can no longer hang past
214+ the deadline. A timeout now comes back with guidance to shorten the window or
215+ narrow ` parentFilter ` rather than a misleading "invalid SQL" hint, and the
216+ client-side ` Timeout error. ` carries that hint in every MCP tool. Sources
217+ whose ` timestampValueExpression ` spans several columns, including a leading
218+ Date column such as ` EventDate, EventTime ` , also return correct breakdowns
219+ now (#3258 ).
220+
221+ ### 📦 Build / Packaging
222+
223+ - ** The app bundles ClickHouse's click-ui design system** : ` ClickUIProvider ` is
224+ now mounted alongside the existing Mantine provider, following HyperDX's own
225+ colour mode rather than persisting a theme of its own. The "open an issue on
226+ GitHub" link in error messages and the alert state badges are the first
227+ components built on it — a fired alert now shows a solid red badge and an
228+ evaluation error a light red one (#3262 , #3314 , thanks @hoorayimhelping !).
229+
230+ <!-- hyperdx-package-list -->
231+
232+ ### 📦 Package changelogs
233+
234+ - ` @hyperdx/api ` 2.40.0 → 2.41.0 — [ changelog] ( https://github.com/hyperdxio/hyperdx/blob/main/packages/api/CHANGELOG.md#2410 )
235+ - ` @hyperdx/app ` 2.40.0 → 2.41.0 — [ changelog] ( https://github.com/hyperdxio/hyperdx/blob/main/packages/app/CHANGELOG.md#2410 )
236+ - ` @hyperdx/cli ` 0.6.4 → 0.7.0 — [ changelog] ( https://github.com/hyperdxio/hyperdx/blob/main/packages/cli/CHANGELOG.md#070 )
237+ - ` @hyperdx/common-utils ` 0.30.0 → 0.31.0 — [ changelog] ( https://github.com/hyperdxio/hyperdx/blob/main/packages/common-utils/CHANGELOG.md#0310 )
238+ - ` @hyperdx/otel-collector ` 2.40.0 → 2.41.0 — [ changelog] ( https://github.com/hyperdxio/hyperdx/blob/main/packages/otel-collector/CHANGELOG.md#2410 )
239+
240+ <!-- /hyperdx-package-list -->
241+
9242## v2.40.0 — 2026-10-01
10243
11244<!-- hyperdx-release-notes version=2.40.0 inputs=b95c34cd6847 -->
0 commit comments