@hyperdx/cli v0.5.1

@hyperdx/cli v0.5.1

Patch Changes

• 5c46215: Bump @clickhouse/client* to 1.23.0-head.fae5998.1 and fix the type
  incompatibility it introduces.

  In @clickhouse/client* 1.23 each platform package (@clickhouse/client,
  @clickhouse/client-web) bundles its own copy of the shared types, so their
  ClickHouseSettings types — which reference the nominally-compared SettingsMap
  class — are no longer the same type as @clickhouse/client-common's. The shared
  processClickhouseSettings() helper produces the client-common flavor, so
  assigning it into the per-platform clients' query() now requires an explicit
  bridge. Guard the existing as ClickHouseSettings assertions at those
  boundaries (node.ts, browser.ts, cli) with a scoped
  @typescript-eslint/no-unsafe-type-assertion disable, matching the existing
  "client library type mismatch" pattern. No runtime behavior changes.

• 45954c3: Import ClickHouse client types from the platform packages
  (@clickhouse/client / @clickhouse/client-web) instead of the deprecated
  @clickhouse/client-common. This makes the packages forward-compatible with
  @clickhouse/client* 1.23 (where client-common is deprecated and each
  platform package bundles and re-exports its own copy of the shared types)
  without bumping the pinned version. No runtime behavior changes.

• 1a64796: Removing relative imports and using path aliases

---

Installation

npm (recommended):

npm install -g @hyperdx/cli

Or run directly with npx:

npx @hyperdx/cli tui -s <your-hyperdx-api-url>

Manual download (standalone binary, no Node.js required):

# macOS Apple Silicon
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.1/hdx-darwin-arm64 -o hdx
# macOS Intel
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.1/hdx-darwin-x64 -o hdx
# Linux x64
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.1/hdx-linux-x64 -o hdx

chmod +x hdx && sudo mv hdx /usr/local/bin/

Usage

hdx auth login -s <your-hyperdx-api-url>
hdx tui

@hyperdx/otel-collector@2.29.0

Minor Changes

• 34a8559: chore(otel-collector): bump base collector to v0.154.0

  Upgrade the custom OTel Collector base from contrib v0.149.0 (core 1.55.0) to
  v0.154.0 (core 1.60.0). Updates OTEL_COLLECTOR_VERSION /
  OTEL_COLLECTOR_CORE_VERSION in .env, both Dockerfile ARG defaults, and the
  smoke-test compose fallbacks.

  Compatibility: no config changes required. Reviewed contrib and core breaking
  changes across v0.150–v0.154 against every component HyperDX uses. All affected
  upstream changes are either backward-compatible deprecation aliases
  (prometheusremotewrite, resourcedetection), explicit-config no-ops for
  HyperDX (clickhouse exporter already sets json: directly; transform/routing
  connectors set error_mode: ignore explicitly), or internal core feature-gate
  stabilizations.

• 6b6c340: chore(otel-collector): bump base collector to v0.155.0

  Upgrade the custom OTel Collector base from contrib v0.154.0 (core 1.60.0) to
  v0.155.0 (core 1.61.0). Updates OTEL_COLLECTOR_VERSION /
  OTEL_COLLECTOR_CORE_VERSION in .env, both Dockerfile ARG defaults, and the
  smoke-test compose fallbacks.

  Compatibility: no config changes required. Reviewed contrib and core breaking
  changes for v0.155.0 against every component HyperDX uses. The removed
  telemetry.UseLocalHostAsDefaultMetricsAddress core gate has no impact because
  the telemetry metrics endpoint is set explicitly (host: 0.0.0.0, port: 8888), and the memory_limiter metric rename does not affect the smoke tests
  (which assert on the startup log line and the batch/lowlatency metric label,
  not memory_limiter metrics). All other breaking changes are in unused components
  or internal feature-gate removals.

Patch Changes

• 973d120: fix: polish promql experience across the app

• a5dfce4: fix(otel-collector): only enable the prometheus remote-write exporter in
  standalone mode when CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT is set

  The standalone collector config used to unconditionally declare a
  prometheusremotewrite exporter and a metrics/promql pipeline. When
  CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT was unset the exporter rendered
  with an empty endpoint and every metrics batch failed to export.

  The exporter and pipeline have been moved to
  docker/otel-collector/config.standalone.promql.yaml, which is now only
  loaded by entrypoint.sh when CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT is
  non-empty. This mirrors the OpAMP-managed gating in
  packages/api/src/opamp/controllers/opampController.ts (which already
  only adds the exporter when IS_PROMQL_ENABLED is true).

  No action required if CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT is set; the
  behavior is unchanged. If it was unset, the collector now stops emitting
  the failing prometheus-remote-write attempts.

@hyperdx/hdx-eval@0.2.0

Minor Changes

• 5bd1c68: feat: add AI eval framework for benchmarking MCP servers

  New @hyperdx/hdx-eval package for benchmarking AI agents against
  observability MCP servers. Generates deterministic synthetic telemetry
  with planted anomalies, spawns Claude Code as an SRE agent, records full
  trajectories, and grades answers using programmatic checks and an
  LLM-as-judge.

  Includes 5 scenarios (error-root-cause, latency-spike, noisy-signals,
  segmented-regression, service-health-check), MCP-agnostic N-way
  comparison, blinded judging, and a web viewer for browsing results.

Patch Changes

• 6a80031: Support multi-model comparison in eval batches via comma-separated --model flag
• 1a64796: Removing relative imports and using path aliases

@hyperdx/common-utils@0.21.0

Minor Changes

• 5cd7090: Add UI support for configuring an external Prometheus-compatible endpoint on a
  connection. Modify Connections model to now have a boolean
  isPrometheusEndpoint field and use host for storing the host.

• f40cf68: feat(dashboards): add a background trend sparkline to number tiles

  Number tiles can now render a faint line or area sparkline behind the value,
  derived from a time-bucketed version of the same query, so the value's trend
  over the selected range is visible at a glance. This is handy for SLO /
  error-budget tiles where the burn over time matters as much as the current
  number. The sparkline inherits the tile's color by default and can be
  overridden to any palette token. Configure it under Display Settings >
  Background chart on a number tile. Available on builder number tiles (raw SQL
  number tiles return a single value with no time dimension to bucket).

• 17e1eb1: feat: Add an "external link" row-click action for dashboard table tiles

• e03971b: refactor(theme): rename chart palette tokens from chart-1..10 to hue-named
  (chart-blue, chart-orange, ...) and unify the categorical palette across HyperDX
  and ClickStack

  Stored configs from the initial color picker (#2265) keep working.
  ChartPaletteTokenSchema stays strict (a plain z.enum, so its z.input
  matches z.output — wrapping it in z.preprocess would poison
  validateRequest's req.body inference all the way up to
  Dashboard.tiles[i].config.color). Migration of legacy chart-1 .. chart-10
  happens at five complementary points so no entry or wire-format path can slip
  through, all composing over a single shared walker
  (walkRawDashboardTileColors in common-utils) so the per-tile traversal
  stays in lockstep:

  • Fetch-time / write-time (React): normalizeDashboardTileColors in
    packages/app/src/dashboard.ts heals dashboards on read
    (useDashboards / fetchLocalDashboards / fetchDashboards) and on write
    (useUpdateDashboard / useCreateDashboard). Unresolvable color strings
    (stale hexes, hand-edited values, forward-rolled future tokens) are
    preserved so the user's chosen value survives a render pass — the strict
    server-side schema surfaces a clear error on next save instead of the
    normalizer quietly dropping the field.
  • JSON import: DBDashboardImportPage runs
    normalizeRawDashboardTileColors on the parsed JSON before the strict
    DashboardTemplateSchema.safeParse, so templates exported from a
    pre-rename deploy import cleanly.
  • Server-side GET response healing: getDashboards / getDashboard in
    packages/api/src/controllers/dashboard.ts rewrite legacy tile colors on
    the way out. Pre-rename Mongo docs are served on the wire as
    hue-named tokens so non-React HTTP clients (CI scripts, stale bundle
    tabs during a rolling deploy, the external API) can round-trip
    GET → PATCH without ever resurrecting chart-N through the strict
    schema.
  • Server-side write shim: the dashboards POST / PATCH routes mount
    a request-body preprocessor that rewrites legacy tile colors before
    validateRequest runs ChartPaletteTokenSchema. Catches non-React
    HTTP callers (stale-bundle tabs during a rolling deploy, CI scripts,
    MCP, the upcoming external-API parity work) for a one-release
    deprecation window without weakening the schema's input/output equality.
    The dashboard provisioner task applies the same shim before parsing
    on-disk template files.
  • Render-time (belt-and-suspenders): DBNumberChart and
    ColorSwatchInput also call resolveChartPaletteToken for tiles
    constructed in memory between fetch and save (ChartEditor form
    state, unit-test fixtures, hand-rolled Tile literals).

  The migration preserves the HyperDX slot ordering from #2265 (slot 1 = brand
  green, slot 2 = blue, etc.).

  ClickStack legacy color caveat: Pre-rename ClickStack used a different slot
  ordering than HyperDX (--color-chart-1 was brand blue #437eef, not brand
  green). The migration map uses HyperDX slot ordering, so any ClickStack
  dashboard saved via #2265 with color: 'chart-1' will flip from blue to
  Observable green after migration. We chose this trade-off deliberately over
  branching the legacy map by active theme: LEGACY_CHART_PALETTE_TOKEN_MAP lives
  in common-utils (shared with the API), and migration is one-shot persisted on
  next save — theme-branching would couple common-utils to browser DOM state and
  still produce wrong results for users whose active theme changed since the
  original pick. Affected users can manually re-pick the desired hue via the (now
  hue-labeled) color picker.

  The categorical palette is based on Observable 10, with chart-blue swapped to
  #437eef to match the brand link color
  (--click-global-color-text-link-default); all other hues are straight from
  Observable 10. The palette resolves identically on both themes — picking
  chart-blue always renders the brand blue. Brand identity for charts moves
  entirely into the semantic layer: --color-chart-success and --color-chart-info
  resolve to categorical chart-green (#3ca951) and chart-blue (#437eef) on
  both HyperDX and ClickStack, so success fills, info-level logs, and the
  matching multi-series slots all read consistently across brands.

  Internally, JS (CATEGORICAL_HEX_BY_TOKEN in packages/app/src/utils.ts) is
  the source of truth for categorical hues — getColorFromCSSVariable and
  getColorFromCSSToken skip getComputedStyle for categorical tokens since the
  palette is unified across themes. The matching --color-chart-{hue} CSS vars in
  _tokens.scss remain as a stylesheet-author affordance (inline var() use,
  devtools inspection) and a hook for any future per-brand override. Semantic
  tokens still resolve through getComputedStyle because they genuinely vary per
  theme.

Patch Changes

• 1d44098: fix: recover the SELECT-alias map when a query has ClickHouse-specific SQL the parser rejects

  chSqlToAliasMap returned an empty map whenever the rendered query contained
  SQL that node-sql-parser's Postgresql dialect cannot parse, for example a
  sampling CTE with greatest(CAST(total / N AS UInt32), 1). An empty alias map
  drops the WITH clauses that define the source's select aliases, so filters on
  aliased columns (Event Patterns, histogram, alerts) failed with Unknown identifier. It now falls back to parsing only the outer SELECT projection,
  which is all the alias map needs, so the aliases are recovered even when the
  rest of the statement is unparseable.

• 998ea5d: feat: Add option to fit time chart y-axis lower bound

• ee90738: fix: Add sourceId to MCP Raw SQL Tile schema

• 5c46215: Bump @clickhouse/client* to 1.23.0-head.fae5998.1 and fix the type
  incompatibility it introduces.

  In @clickhouse/client* 1.23 each platform package (@clickhouse/client,
  @clickhouse/client-web) bundles its own copy of the shared types, so their
  ClickHouseSettings types — which reference the nominally-compared SettingsMap
  class — are no longer the same type as @clickhouse/client-common's. The shared
  processClickhouseSettings() helper produces the client-common flavor, so
  assigning it into the per-platform clients' query() now requires an explicit
  bridge. Guard the existing as ClickHouseSettings assertions at those
  boundaries (node.ts, browser.ts, cli) with a scoped
  @typescript-eslint/no-unsafe-type-assertion disable, matching the existing
  "client library type mismatch" pattern. No runtime behavior changes.

• 45954c3: Import ClickHouse client types from the platform packages
  (@clickhouse/client / @clickhouse/client-web) instead of the deprecated
  @clickhouse/client-common. This makes the packages forward-compatible with
  @clickhouse/client* 1.23 (where client-common is deprecated and each
  platform package bundles and re-exports its own copy of the shared types)
  without bumping the pinned version. No runtime behavior changes.

• 5a1dde4: fix(search): wrap date column values in a type-matching parse/convert expression when building IN/NOT IN filters, so including/excluding a timestamp value no longer fails with "Cannot convert string ... to type DateTime64" or "Type mismatch in IN ... Expected: DateTime. Got: Decimal64". Date column types are now resolved from the query result set, so aliased (TimestampTime AS time) and computed (toDate(TimestampTime)) DateTime/Date columns are also wrapped correctly when added to filters.

• ae39bc4: fix: Correct filter handling for filter keys with special characters

• 8261b46: fix: inline parametric aggregate function arguments instead of passing as query parameters

• bf6e1f2: feat(charts): the time-chart series limit is now configured per chart in the Display Settings drawer instead of as a workspace-wide team setting (the team "Time Chart Series Limit" setting is removed). It is disabled by default — charts fetch every series and no __hdx_series_limit CTE is emitted — and is cleared back to disabled by emptying the field. The control only appears for builder line/bar charts; the limit and its Generated SQL preview now come from the chart's own config. When a limit is set, chunked time-chart queries keep a consistent top-N series set: previously each time-window chunk ranked its own top-N, so charts could render more series than the limit and adjacent windows disagreed; the ranking is now pinned to the newest chunk window for every chunk so the union across chunks equals the limit.

• 973d120: fix: polish promql experience across the app

• 677e3f7: fix: Skip rendering empty aggConditions

• 89949b1: Adding filters to dashboard exports. Implemented validation on dashboard imports to catch potential issues with generated JSON or manually tweaked JSON.

• 747352f: feat: add direct...

@hyperdx/cli@0.5.1

Patch Changes

• 5c46215: Bump @clickhouse/client* to 1.23.0-head.fae5998.1 and fix the type
  incompatibility it introduces.

  In @clickhouse/client* 1.23 each platform package (@clickhouse/client,
  @clickhouse/client-web) bundles its own copy of the shared types, so their
  ClickHouseSettings types — which reference the nominally-compared SettingsMap
  class — are no longer the same type as @clickhouse/client-common's. The shared
  processClickhouseSettings() helper produces the client-common flavor, so
  assigning it into the per-platform clients' query() now requires an explicit
  bridge. Guard the existing as ClickHouseSettings assertions at those
  boundaries (node.ts, browser.ts, cli) with a scoped
  @typescript-eslint/no-unsafe-type-assertion disable, matching the existing
  "client library type mismatch" pattern. No runtime behavior changes.

• 45954c3: Import ClickHouse client types from the platform packages
  (@clickhouse/client / @clickhouse/client-web) instead of the deprecated
  @clickhouse/client-common. This makes the packages forward-compatible with
  @clickhouse/client* 1.23 (where client-common is deprecated and each
  platform package bundles and re-exports its own copy of the shared types)
  without bumping the pinned version. No runtime behavior changes.

• 1a64796: Removing relative imports and using path aliases

@hyperdx/app@2.29.0

Minor Changes

• 9af8cba: feat: add Browser RUM dashboard template

  • New "Browser RUM" template in the dashboards gallery for browser sessions instrumented with the HyperDX Browser SDK (or any OTel browser instrumentation emitting a rum.sessionId resource attribute)
  • Performance Overview section: page-view/session/error KPIs, Core Web Vitals (LCP/INP/CLS) p75, median/p75/p90 page-load percentiles, and long-task health
  • Page Views Breakdown section: traffic grouped by URL, browser (parsed from the http.user_agent the document-load instrumentation emits), country, and device size (derived from screen.xy)
  • Errors section with tabs for an overview, JS exceptions (by message and by page), and failing API calls
  • Five dashboard-level filters: Service, Environment, Service Version, Page URL, and Country
  • Top Countries tile and the Country filter populate when the OTel collector's geoip processor is enabled (geo can't be derived in the browser)

• 5cd7090: Add UI support for configuring an external Prometheus-compatible endpoint on a
  connection. Modify Connections model to now have a boolean
  isPrometheusEndpoint field and use host for storing the host.

• b6a4b3b: feat: lazy-load dashboard tiles based on viewport visibility

  Dashboard tiles now only run their ClickHouse queries once they scroll into the browser viewport, instead of every tile querying on page load. A tile loads the first time it becomes visible and keeps its data afterward. This significantly reduces the number of queries fired when opening dashboards with many tiles.

• f40cf68: feat(dashboards): add a background trend sparkline to number tiles

  Number tiles can now render a faint line or area sparkline behind the value,
  derived from a time-bucketed version of the same query, so the value's trend
  over the selected range is visible at a glance. This is handy for SLO /
  error-budget tiles where the burn over time matters as much as the current
  number. The sparkline inherits the tile's color by default and can be
  overridden to any palette token. Configure it under Display Settings >
  Background chart on a number tile. Available on builder number tiles (raw SQL
  number tiles return a single value with no time dimension to bucket).

• 17e1eb1: feat: Add an "external link" row-click action for dashboard table tiles

• c1403a7: Number chart tiles now support a second series with the "As Ratio" toggle (series[0] / series[1]), matching line and bar charts. Combined with a percent number format, this renders a percentage (e.g. success/error rate) as a single big number with the trend sparkline behind it.

• e03971b: refactor(theme): rename chart palette tokens from chart-1..10 to hue-named
  (chart-blue, chart-orange, ...) and unify the categorical palette across HyperDX
  and ClickStack

  Stored configs from the initial color picker (#2265) keep working.
  ChartPaletteTokenSchema stays strict (a plain z.enum, so its z.input
  matches z.output — wrapping it in z.preprocess would poison
  validateRequest's req.body inference all the way up to
  Dashboard.tiles[i].config.color). Migration of legacy chart-1 .. chart-10
  happens at five complementary points so no entry or wire-format path can slip
  through, all composing over a single shared walker
  (walkRawDashboardTileColors in common-utils) so the per-tile traversal
  stays in lockstep:

  • Fetch-time / write-time (React): normalizeDashboardTileColors in
    packages/app/src/dashboard.ts heals dashboards on read
    (useDashboards / fetchLocalDashboards / fetchDashboards) and on write
    (useUpdateDashboard / useCreateDashboard). Unresolvable color strings
    (stale hexes, hand-edited values, forward-rolled future tokens) are
    preserved so the user's chosen value survives a render pass — the strict
    server-side schema surfaces a clear error on next save instead of the
    normalizer quietly dropping the field.
  • JSON import: DBDashboardImportPage runs
    normalizeRawDashboardTileColors on the parsed JSON before the strict
    DashboardTemplateSchema.safeParse, so templates exported from a
    pre-rename deploy import cleanly.
  • Server-side GET response healing: getDashboards / getDashboard in
    packages/api/src/controllers/dashboard.ts rewrite legacy tile colors on
    the way out. Pre-rename Mongo docs are served on the wire as
    hue-named tokens so non-React HTTP clients (CI scripts, stale bundle
    tabs during a rolling deploy, the external API) can round-trip
    GET → PATCH without ever resurrecting chart-N through the strict
    schema.
  • Server-side write shim: the dashboards POST / PATCH routes mount
    a request-body preprocessor that rewrites legacy tile colors before
    validateRequest runs ChartPaletteTokenSchema. Catches non-React
    HTTP callers (stale-bundle tabs during a rolling deploy, CI scripts,
    MCP, the upcoming external-API parity work) for a one-release
    deprecation window without weakening the schema's input/output equality.
    The dashboard provisioner task applies the same shim before parsing
    on-disk template files.
  • Render-time (belt-and-suspenders): DBNumberChart and
    ColorSwatchInput also call resolveChartPaletteToken for tiles
    constructed in memory between fetch and save (ChartEditor form
    state, unit-test fixtures, hand-rolled Tile literals).

  The migration preserves the HyperDX slot ordering from #2265 (slot 1 = brand
  green, slot 2 = blue, etc.).

  ClickStack legacy color caveat: Pre-rename ClickStack used a different slot
  ordering than HyperDX (--color-chart-1 was brand blue #437eef, not brand
  green). The migration map uses HyperDX slot ordering, so any ClickStack
  dashboard saved via #2265 with color: 'chart-1' will flip from blue to
  Observable green after migration. We chose this trade-off deliberately over
  branching the legacy map by active theme: LEGACY_CHART_PALETTE_TOKEN_MAP lives
  in common-utils (shared with the API), and migration is one-shot persisted on
  next save — theme-branching would couple common-utils to browser DOM state and
  still produce wrong results for users whose active theme changed since the
  original pick. Affected users can manually re-pick the desired hue via the (now
  hue-labeled) color picker.

  The categorical palette is based on Observable 10, with chart-blue swapped to
  #437eef to match the brand link color
  (--click-global-color-text-link-default); all other hues are straight from
  Observable 10. The palette resolves identically on both themes — picking
  chart-blue always renders the brand blue. Brand identity for charts moves
  entirely into the semantic layer: --color-chart-success and --color-chart-info
  resolve to categorical chart-green (#3ca951) and chart-blue (#437eef) on
  both HyperDX and ClickStack, so success fills, info-level logs, and the
  matching multi-series slots all read consistently across brands.

  Internally, JS (CATEGORICAL_HEX_BY_TOKEN in packages/app/src/utils.ts) is
  the source of truth for categorical hues — getColorFromCSSVariable and
  getColorFromCSSToken skip getComputedStyle for categorical tokens since the
  palette is unified across themes. The matching --color-chart-{hue} CSS vars in
  _tokens.scss remain as a stylesheet-author affordance (inline var() use,
  devtools inspection) and a hook for any future per-brand override. Semantic
  tokens still resolve through getComputedStyle because they genuinely vary per
  theme.

• 418567f: feat: trace panel inline split detail

Patch Changes

• 56c5866: fix(search-filters): prevent nested filter dropdowns from disappearing on reopen

• 998ea5d: feat: Add option to fit time chart y-axis lower bound

• 0497ca5: Bump http-proxy-middleware to v4, replacing http-proxy with httpxy

• 20fabc6: feat: add a "Connect your AI assistant" section to Team Settings

  A new section on the Team Settings page (Integrations tab, above the API Keys
  card) lets a user install the HyperDX MCP server in Claude Code, Cursor,
  VS Code + Copilot, Codex CLI, or any MCP-compatible host without hand-rolling
  JSON. Per-host snippets carry the user's personal access key so the install
  works against the existing /api/mcp route without extra setup.

• 8e52cef: feat(dashboard): auto-resize font in number tiles to fit container

  Number tiles now automatically scale their font size to fit the available
  width, preventing text overflow on narrow tiles and making better use of
  space on wide ones. Includes an error boundary so a single broken tile
  does not crash the entire dashboard.

• 5a1dde4: fix(search): wrap date column values in a type-matching parse/convert expression when building IN/NOT IN filters, so including/excluding a timestamp value no longer fails with "Cannot convert string ... to type DateTime64" or "Type mismatch in IN ... Expected: DateTime. Got: Decimal64". Date column types are now resolved from the query result set, so aliased (TimestampTime AS time) and computed (toDate(TimestampTime)) DateTime/Date columns are also wrapped correctly when added to filters.

• 31b8781: feat(chart-explorer): duplicate a series in the chart builder

  Add a Duplicate button to each series row in the chart builder that inserts a
  copy of that series directly below it, so building a near-identical variant
  (for example avg and p95 of the same column) no longer requires re-entering
  every field by hand. "Add Series" still creates a blank series. The copy
  starts with an empty alias so it does not collide with the original's alias in
  the generated SQL.

• 5e19a2b: Show elapsed time and Generated SQL for search timeline view

• 65931e3: feat(search): make active filter pills editable in place

  Clicking an active filter pill under the search bar now opens a small menu to copy the value, fl...

@hyperdx/api@2.29.0

Minor Changes

• 9119de5: Add unique MongoDB index on accessKey field in User model to eliminate full collection scans during API key authentication. This could cause startup failures if any existing users share duplicate accessKey values.

• 9f23b7e: Feat: Added a V2 endpoint for team management.

• 5cd7090: Add UI support for configuring an external Prometheus-compatible endpoint on a
  connection. Modify Connections model to now have a boolean
  isPrometheusEndpoint field and use host for storing the host.

• b798f91: Add connection management endpoints to the external API (/api/v2/connections), supporting list, get, create, update, and delete with Bearer token authentication. Passwords are write-only and never returned by the API.

• 63469fe: feat(mcp): first-class metric source support

  • Two new tools: clickstack_list_metrics paginates the metric-name catalog with optional kind / namePattern (ILIKE) / time-window filters and opaque cursor pagination; clickstack_describe_metric returns per-metric kind(s), unit, description, attribute keys, and sampled values (with kind auto-detection).
  • clickstack_describe_source is metric-aware: picks a representative metric table (gauge → sum → histogram), runs column / map-key / value-sampling against it, and adds a per-kind metric-name sample.
  • clickstack_timeseries and clickstack_table accept metricType (gauge / sum / histogram), metricName, and isDelta on each select item, plus aggFn:"increase" for Sum counters. valueExpression defaults to "Value" for metric sources. Surfaces the renderer's 20-group top-N cap on increase + groupBy as a neutral hint.
  • Dashboard prompt's "use raw SQL for metric tiles" workaround is replaced with positive discovery-workflow guidance and one worked example per supported kind.
  • summary and "exponential histogram" kinds remain out of scope (no query renderer support yet).

• f126d5b: Support number-tile color authoring through the external dashboards API. The v2 REST API and OpenAPI spec now accept color (a palette token) and colorRules (ordered conditional color rules, last match wins) on builder number tiles, and color on raw SQL number tiles, matching what the in-product number-tile editor persists. Color rules accept the numeric and equality operators the editor offers (gt, gte, lt, lte, between, eq, neq). Existing dashboards keep working: tiles saved before the palette was renamed to hue names are normalized to the current token names on read.

• ebfc2e8: Extend observability instrumentation to the remaining API surfaces using the
  shared helpers. Add custom metrics and tracing to previously log-only paths:
  OpAMP message handling (message outcomes, agent status reports, remote configs
  sent), the Prometheus proxy router (query duration + swallowed-error counters
  labeled by endpoint and backend), alert webhook/notification delivery (delivery
  attempts and duration labeled by service and outcome), and MongoDB connection
  lifecycle events.

  Add a reusable SLO primitive (withOperationMetrics / recordOperationOutcome)
  that emits standard availability + latency SLIs (hyperdx.operation.requests
  and hyperdx.operation.duration_ms, labeled by operation and outcome) so
  SLOs can be defined per piece of application functionality. Apply it to the AI
  assistant generation call, the ClickHouse proxy (query passthrough +
  connection test), and alert processing — both the end-to-end alert evaluation
  (alerts.evaluate, excluding scheduling skips) and its ClickHouse data fetch
  (alerts.query) — paths whose failures previously surfaced only as logs or
  failures-only counters with no latency or denominator.

• bbc2985: Improve API observability instrumentation. Add a centralized tracing + metrics
  helper library (withSpan, setBusinessContext, getStaticFeatureFlags,
  memoized getCounter/getHistogram, recordDuration), attach consistent
  team/user/feature-flag context to traces across all auth paths (session,
  access-key, local mode), and add custom metrics for previously log-only hot
  paths: API errors, alert evaluation outcomes/query/process failures, and
  external API search/charts query duration and errors.

• 17e1eb1: feat: Add an "external link" row-click action for dashboard table tiles

Patch Changes

• 998ea5d: feat: Add option to fit time chart y-axis lower bound

• 0497ca5: Bump http-proxy-middleware to v4, replacing http-proxy with httpxy

• ee90738: fix: Add sourceId to MCP Raw SQL Tile schema

• 9a7e392: fix: Add missing numberFormats, compareToPreviousPeriod fields to MCP Schemas

• cdd7ca0: fix(mcp): reduce describe_source timeouts by using rollup tables for map key discovery

• d11991b: fix: enforce password complexity on team invite acceptance

• 8261b46: fix: inline parametric aggregate function arguments instead of passing as query parameters

• 973d120: fix: polish promql experience across the app

• 8164492: fix(mcp): improve alias field descriptions and examples for readable chart legends

• a19ba54: feat(mcp): add patch_dashboard, get_dashboard_tile, search_dashboards tools

  Add three new MCP dashboard tools for granular operations:

  • hyperdx_get_dashboard_tile — retrieve a single tile by tileId
  • hyperdx_patch_dashboard — update name/tags and/or replace one tile
    without resubmitting the full dashboard
  • hyperdx_search_dashboards — search by name and/or tags

  Fix empty parameter schema on patch/search tools caused by Zod
  .refine() wrapping. Document Lucene substring matching limitations
  prominently in tool descriptions and query guide prompt.

  Breaking (minor): Tile name on hyperdx_save_dashboard now requires
  at least 1 character (.min(1)). Previously empty string "" was accepted
  and silently persisted as a blank title. Callers sending name: "" will
  now receive a validation error.

• 7e7159a: fix(mcp): improve error hints and fix readonly mode for query safety settings

  Switch MCP ClickHouse safety settings from readonly=1 to readonly=2 so
  max_execution_time and max_result_rows are actually applied (readonly=1
  silently rejects all setting changes).

  Improve DateTime64 cast error hint to recommend parseDateTime64BestEffort()
  which works on both DateTime and DateTime64 columns, replacing
  toDateTime64() which only works on DateTime64.

  Add error hint for unknown column/identifier errors directing agents to
  call describe_source before retrying.

• f34a31f: Support number-tile color in the MCP dashboard tools. save_dashboard and patch_dashboard now accept a static color and conditional colorRules on builder number tiles, and a static color on raw SQL number tiles, matching the external REST dashboards API.

• f6bda8c: refactor(mcp): simplify ObjectId validation with shared helpers and schema-level checks

  Add mcpError() and validateObjectId() utilities to reduce boilerplate
  across MCP tool handlers. Move ObjectId validation into Zod input schemas
  for always-required ID fields, eliminating inline checks entirely. Remaining
  conditional checks use the new one-liner helper.

• f326ccf: fix(mcp): quote multi-word aliases in orderBy and steer event-pattern usage

  Quote resolved aliases that are not bare identifiers (e.g. "P95 Latency")
  in resolveOrderBy output, in both the direct alias-match and aggFn-match
  paths. Previously an unquoted multi-word alias produced SQL-invalid
  ORDER BY output. Incoming orderBy values are stripped of surrounding
  double-quote/backtick quoting before matching, so agents that already quote
  the alias resolve correctly without being double-quoted.

  Also document the alias-quoting requirement in the orderBy schema
  descriptions, and update the clickstack_event_patterns tool description to
  steer agents toward it (over clickstack_search / clickstack_table) when
  exploring what messages, errors, or events exist.

• 750b8af: feat(mcp): add denoise option to clickstack_search tool

  Add a denoise boolean parameter to the MCP clickstack_search tool that
  automatically filters out high-frequency repetitive event patterns from
  search results, mirroring the web app's "Denoise Results" feature.

  When enabled, the tool samples 10k random events, mines patterns using
  the Drain algorithm, identifies noisy patterns (>10% of sample), and
  filters them out of result rows. Returns filtered rows plus metadata
  listing removed patterns with estimated counts.

  Extracts shared denoise constants (DENOISE_SAMPLE_SIZE,
  DENOISE_NOISE_THRESHOLD) into @hyperdx/common-utils so the web app
  and MCP server use the same values.

• caba7c2: fix: Nudge agents towards macros in raw SQL tiles

• f113ea3: fix(mcp): add ClickHouse safety settings (max_execution_time, max_result_rows, readonly) for MCP query execution

• 634101c: chore: upgrade moduleResolution to NodeNext and simplify clickhouseProxy static import

• ba626ef: Add backgroundChart support to number tiles in the external dashboards API (/api/v2/dashboards). Builder number tiles can now carry an optional background trend sparkline (type line or area, with an optional palette-token color) over the v2 REST API, matching the dashboard editor. Raw SQL number tiles do not support it.

• 60a91e4: fix(mcp): remove max_result_rows from MCP safety settings

  Remove the hardcoded max_result_rows=100000 setting from MCP query
  execution. Some ClickHouse connections impose profile constraints that
  cap max_result_rows below our default, causing SETTING_CONSTRAINT_VIOLATION
  errors. The remaining safety settings (max_execution_time=30, readonly=2)
  and trimToolResponse provide sufficient protection.

  Add a SETTING_CONSTRAINT_VIOLATION error hint so constrained settings
  surface actionable guidance instead of raw ClickHouse errors.

• e03971b: refactor(theme): rename chart palette tokens from chart-...

@hyperdx/cli v0.5.0

@hyperdx/cli v0.5.0

Minor Changes

• 3123db5: feat: experimental promql support

Patch Changes

• b20275c: fix(cli): exit with non-zero code when upload-sourcemaps fails

  The upload-sourcemaps command now exits with code 1 when uploads fail
  (missing source maps, pre-signed URL request failure, authentication failure,
  or any per-file upload failure after retries). Previously these failures were
  logged to stderr but the process exited cleanly with code 0, causing CI
  pipelines to treat failed uploads as successes.

• 19cd7c9: fix: only use pk and row uniqueness to look up a row

• 8810ff0: feat: Add option for force-enabling/disabling text index support

---

Installation

npm (recommended):

npm install -g @hyperdx/cli

Or run directly with npx:

npx @hyperdx/cli tui -s <your-hyperdx-api-url>

Manual download (standalone binary, no Node.js required):

# macOS Apple Silicon
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.0/hdx-darwin-arm64 -o hdx
# macOS Intel
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.0/hdx-darwin-x64 -o hdx
# Linux x64
curl -L https://github.com/hyperdxio/hyperdx/releases/download/cli-v0.5.0/hdx-linux-x64 -o hdx

chmod +x hdx && sudo mv hdx /usr/local/bin/

Usage

hdx auth login -s <your-hyperdx-api-url>
hdx tui

@hyperdx/otel-collector@2.28.0

Minor Changes

• 3123db5: feat: experimental promql support

• cb6a74c: fix(otel-collector): allow CUSTOM_OTELCOL_CONFIG_FILE to override the
  default memory_limiter, batch (and other pipeline processors)

  Pipeline processors: lists used to be defined in the OpAMP remote config
  sent by the API (packages/api/src/opamp/controllers/opampController.ts).
  That meant the remote config overwrote any pipeline processors: list a
  user supplied via CUSTOM_OTELCOL_CONFIG_FILE, making it impossible to
  substitute the default memory_limiter with one configured for
  limit_percentage/spike_limit_percentage mode (#2145).

  The pipeline processors: lists now live in the bootstrap config
  (docker/otel-collector/config.yaml for supervisor mode, and
  docker/otel-collector/config.standalone.yaml for standalone mode). The
  OpAMP remote config no longer sets processors: on these pipelines, so the
  bootstrap+custom merge wins. Receivers and exporters are still configured
  dynamically by the OpAMP controller.

  To override memory_limiter, define a new processor with a different name
  in CUSTOM_OTELCOL_CONFIG_FILE and swap the pipeline processors: lists:

  processors:
    memory_limiter/custom:
      check_interval: 5s
      limit_percentage: 75
      spike_limit_percentage: 25
  
  service:
    pipelines:
      traces:
        processors: [memory_limiter/custom, batch]
      metrics:
        processors: [memory_limiter/custom, batch]
      logs/out-default:
        processors: [memory_limiter/custom, transform, batch]
      logs/out-rrweb:
        processors: [memory_limiter/custom, batch]

  The default memory_limiter block defined in the base config is left in
  the merged config but is no longer referenced by any pipeline; the
  collector only instantiates memory_limiter/custom at runtime.

  The same swap pattern works for the batch processor (and any other base
  processor). For example, to lower the export timeout on a specific
  pipeline:

  processors:
    batch/lowlatency:
      send_batch_size: 1000
      send_batch_max_size: 2000
      timeout: 500ms
  
  service:
    pipelines:
      traces:
        processors: [memory_limiter, batch/lowlatency]
      logs/out-default:
        processors: [memory_limiter, transform, batch/lowlatency]

  Lighter-weight env-var tuning is also available for the default batch
  processor without writing a custom config file:
  HYPERDX_OTEL_BATCH_SEND_BATCH_SIZE,
  HYPERDX_OTEL_BATCH_SEND_BATCH_MAX_SIZE, and HYPERDX_OTEL_BATCH_TIMEOUT.
  See the README for details.

Patch Changes

• ad3f1c9: fix(otel-collector): skip string severity inference when JSON body has a
  level/severity field

  When the log body parsed as JSON and contained a level-like field, the
  pipeline still ran its \b(alert|crit|emerg|fatal|error|err|warn|notice|debug|dbug|trace)
  keyword scan over the raw body string. The leading-only \b boundary
  matched any word starting with a severity keyword, so bodies containing
  words like alertmanager, alerting, errors, warning, etc. produced
  the wrong severity. A Grafana sidecar log with body
  {"level":"INFO", "msg":"... mimir-alertmanager-dashboard ..."} was being
  tagged SeverityText="fatal", SeverityNumber=21 because alert matched
  inside alertmanager, even though the JSON level said INFO.

  A new OTTL log_statements block in
  docker/otel-collector/config.yaml runs between the existing JSON-parse
  block and the string-inference block. It promotes a JSON-derived level
  field (now in log.attributes) to log.severity_text, which causes the
  string-inference block to be skipped via its existing
  severity_number == 0 and severity_text == "" guard. The block is
  case-insensitive across keys by enumerating common casings of common field
  names used by mainstream logging frameworks: level / Level / LEVEL
  (pino, winston, zerolog, zap, logrus, slog, Serilog, NLog),
  severity / Severity / SEVERITY (Datadog, GCP Cloud Logging), and
  log.level (Elastic ECS, flattened from nested JSON). Each set
  self-guards on severity_text == "" so the first match wins (priority:
  level > severity > log.level). The block as a whole is gated on no
  producer-set severity, so explicit producer values are always preserved.

  severity_number is mapped via case-insensitive (?i) regex over
  severity_text, mirroring the existing string-inference keyword set.
  Unrecognized values (e.g. "verbose") fall back to INFO, matching
  block 2's else-branch. The existing ConvertCase(severity_text, "lower")
  normalization is unchanged.

  Behavior preserved for: non-JSON bodies, JSON bodies without a level
  field, and any log record where the producer already set
  severity_text or severity_number.

  Fixes HDX-4383.

@hyperdx/common-utils@0.20.0

Minor Changes

• 3123db5: feat: experimental promql support

• dcab1cb: feat: default the direct_read map column optimization on supported ClickHouse versions

  The full-text-search logs schema (00002_otel_logs.sql) now ships with
  ResourceAttributeItems, ScopeAttributeItems, and LogAttributeItems
  ALIAS columns plus their text(tokenizer='array') skip indexes. The
  traces schema (00005_otel_traces.sql) similarly gains
  ResourceAttributeItems and SpanAttributeItems ALIAS columns with
  matching items indexes. New installs and freshly migrated tables get
  the optimization automatically — no manual ALTER TABLE required.

  Note: the traces table previously used only bloom_filter skip indexes
  and worked on any ClickHouse version. The added text(tokenizer='array')
  items indexes raise the minimum ClickHouse version required to create
  the traces table to >= 26.2. Existing tables on older clusters are
  unaffected (CREATE TABLE IF NOT EXISTS is a no-op).

  At query time, the app gates the Map['key'] = 'value' →
  has(<MapItems>, concat('key', '=', 'value')) rewrite on the connected
  ClickHouse server version (SELECT version(), cached per connection).
  The gate only applies to ALIAS items columns, which are computed at
  query time and therefore depend on the server being able to perform a
  direct_read against the underlying Map's tuple storage. The direct_read
  feature was backported into multiple stable 26.x release lines, so the
  gate uses a per-branch minimum:

  • 26.2 line: >= 26.2.19.43
  • 26.3 line: >= 26.3.12.3
  • 26.4 line: >= 26.4.3.37
  • 26.5+ : always supported

  ALIAS items columns on servers below their branch's threshold continue
  to compile filters into the original Map-subscript form.

  MATERIALIZED items columns are always used when available, regardless
  of ClickHouse version. MATERIALIZED columns are physically stored on
  disk, so has(items, ...) reads them directly and works on any
  ClickHouse version that supports the text index itself. Operators who
  want the optimization on servers below the backport cutoffs can
  ALTER TABLE to materialize the items columns.

• 1df7583: feat: emit Lucene conditions from sidebar/dashboard filters to enable KV items direct_read optimization on Map columns

  Legacy type: 'sql' filters in URLs are automatically migrated to Lucene
  on page load. The persisted DashboardFilter.expression in MongoDB is unchanged.

Patch Changes

• a945fa0: feat(mcp): add hyperdx_event_deltas tool

  Add hyperdx_event_deltas MCP tool that compares two row groups (target
  vs baseline) and ranks properties by how much their value distributions
  differ. Same algorithm as the in-app Event Deltas view.

  Extract shared event-deltas algorithm from the UI into
  @hyperdx/common-utils/src/core/eventDeltas.ts so it can be used by
  both the frontend and the MCP server.

• 6a5ac3e: fix(charts): histogram bucket picks the highest-precision DateTime column when
  Timestamp Column lists multiple columns

  When a source's Timestamp Column listed multiple columns (e.g.
  "EventDate, EventTime" for partition-pruning), the histogram bucket was
  built from only the first token. If that token was a Date column, every
  row in a day collapsed into a single bar at midnight UTC of that day.

  The bucket resolver now walks the comma-split list, queries each column's
  type via metadata, and returns the highest-precision DateTime / DateTime64
  token. Date columns are skipped. If no DateTime-typed token is found, the
  original first-token behavior is preserved with a console.warn.

  The WHERE clause continues to use the multi-column form, so partition
  pruning via the Date column keeps working. The same resolved column is
  also used for the argMin / argMax / min / max time math in delta
  expressions.

  Fixes HDX-4371.

• e1c4381: fix: bare-text Lucene search now falls back from Implicit Column Expression to
  Body Expression on log sources

  Previously, a log source configured with bodyExpression set but
  implicitColumnExpression unset threw Can not search bare text without an implicit column set. on every bare-token search, even though the row panel
  rendered correctly using the body column.

  Search now reuses the same one-way fallback that getEventBody already
  implements: when no Implicit Column Expression is set, bare-text search runs
  against the configured Body Expression. Trace sources are unchanged
  (spanNameExpression is not a body equivalent for trace search).

• b30dfe0: fix: support text index on lower(Body) with no preprocessor

• dcb8582: fix: escape colons in Lucene field names so filters on Map sub-keys containing
  : (e.g. LogAttributes['foo:bar']) parse correctly

  filtersToQuery now backslash-escapes : and \ in the emitted Lucene field
  name, and parseLuceneFilter + the SQL serializer decode those placeholders
  when consuming the AST so the original key is restored end-to-end.

• b5148c8: Dashboard table tiles configured with a row-click action now show a hover hint describing where the click will go (for example, Search HyperDX Logs or Open dashboard "API Latency Drilldown"). The cell wrapper is now a real link, so cmd-click and middle-click open the destination in a new tab, right-click shows the browser context menu with "Open in New Tab" and "Copy Link Address", and the destination URL appears in the browser status bar on hover. Keyboard users can Tab to a cell and press Enter to navigate, with a visible focus ring.

• 04a5a92: feat: Add source scoping to dashboard filters

• 8810ff0: feat: Add option for force-enabling/disabling text index support

• a8eb27d: feat: filters reflect all values, not search aware; filters use metadata MVs if available