hyperdxio · vinzee · Mar 22, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/.changeset/tiny-forks-deny.md b/.changeset/tiny-forks-deny.md
@@ -0,0 +1,7 @@
+---
+'@hyperdx/common-utils': patch
+'@hyperdx/api': patch
+'@hyperdx/app': patch
+---
+
+feat: support sample-weighted aggregations for sampled trace data
diff --git a/.gitignore b/.gitignore
@@ -52,6 +52,9 @@ packages/app/next-env.d.ts
 # optional npm cache directory
 **/.npm
 
+# npm lockfile (project uses yarn)
+package-lock.json
+
 # dependency directories
 **/node_modules
 

diff --git a/docker/clickhouse/local/init-db-e2e.sh b/docker/clickhouse/local/init-db-e2e.sh
@@ -81,6 +81,7 @@ CREATE TABLE IF NOT EXISTS ${DATABASE}.e2e_otel_traces
     \`Links.TraceState\` Array(String) CODEC(ZSTD(1)),
     \`Links.Attributes\` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)),
     \`__hdx_materialized_rum.sessionId\` String MATERIALIZED ResourceAttributes['rum.sessionId'] CODEC(ZSTD(1)),
+    \`SampleRate\` UInt64 MATERIALIZED greatest(toUInt64OrZero(SpanAttributes['SampleRate']), 1) CODEC(T64, ZSTD(1)),
     INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1,
     INDEX idx_rum_session_id __hdx_materialized_rum.sessionId TYPE bloom_filter(0.001) GRANULARITY 1,
     INDEX idx_res_attr_key mapKeys(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1,

diff --git a/docker/otel-collector/schema/seed/00005_otel_traces.sql b/docker/otel-collector/schema/seed/00005_otel_traces.sql
@@ -24,6 +24,7 @@ CREATE TABLE IF NOT EXISTS ${DATABASE}.otel_traces
     `Links.TraceState` Array(String) CODEC(ZSTD(1)),
     `Links.Attributes` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)),
     `__hdx_materialized_rum.sessionId` String MATERIALIZED ResourceAttributes['rum.sessionId'] CODEC(ZSTD(1)),
+    `SampleRate` UInt64 MATERIALIZED greatest(toUInt64OrZero(SpanAttributes['SampleRate']), 1) CODEC(T64, ZSTD(1)),
     INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1,
     INDEX idx_rum_session_id __hdx_materialized_rum.sessionId TYPE bloom_filter(0.001) GRANULARITY 1,
     INDEX idx_res_attr_key mapKeys(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1,

diff --git a/packages/api/migrations/ch/000002_add_sample_rate_column_to_otel_traces.down.sql b/packages/api/migrations/ch/000002_add_sample_rate_column_to_otel_traces.down.sql
@@ -0,0 +1 @@
+ALTER TABLE ${DATABASE}.otel_traces DROP COLUMN IF EXISTS `SampleRate`;
diff --git a/packages/api/migrations/ch/000002_add_sample_rate_column_to_otel_traces.up.sql b/packages/api/migrations/ch/000002_add_sample_rate_column_to_otel_traces.up.sql
@@ -0,0 +1,4 @@
+ALTER TABLE ${DATABASE}.otel_traces
+    ADD COLUMN IF NOT EXISTS `SampleRate` UInt64
+    MATERIALIZED greatest(toUInt64OrZero(SpanAttributes['SampleRate']), 1)
+    CODEC(T64, ZSTD(1));
diff --git a/packages/api/src/controllers/ai.ts b/packages/api/src/controllers/ai.ts
@@ -8,6 +8,7 @@ import {
   AILineTableResponse,
   AssistantLineTableConfigSchema,
   ChartConfigWithDateRange,
+  SourceKind,
 } from '@hyperdx/common-utils/dist/types';
 import type { LanguageModel } from 'ai';
 import * as chrono from 'chrono-node';
@@ -328,6 +329,11 @@ export function getChartConfigFromResolvedConfig(
     connection: source.connection.toString(),
     groupBy: resObject.groupBy,
     timestampValueExpression: source.timestampValueExpression,
+    ...(source.kind === SourceKind.Trace &&
+      'sampleRateExpression' in source &&
+      source.sampleRateExpression && {
+        sampleWeightExpression: source.sampleRateExpression,
+      }),
     dateRange: [dateRange[0].toString(), dateRange[1].toString()],
     markdown: resObject.markdown,
     granularity: 'auto',

diff --git a/packages/api/src/models/source.ts b/packages/api/src/models/source.ts
@@ -163,6 +163,7 @@ export const TraceSource = Source.discriminator<ITraceSource>(
     parentSpanIdExpression: String,
     spanNameExpression: String,
     spanKindExpression: String,
+    sampleRateExpression: String,
     logSourceId: String,
     sessionSourceId: String,
     metricSourceId: String,

diff --git a/packages/api/src/routers/external-api/v2/charts.ts b/packages/api/src/routers/external-api/v2/charts.ts
@@ -280,6 +280,11 @@ const buildChartConfigFromRequest = async (
     ],
     where: '',
     timestampValueExpression: source.timestampValueExpression,
+    ...(source.kind === SourceKind.Trace &&
+      'sampleRateExpression' in source &&
+      source.sampleRateExpression && {
+        sampleWeightExpression: source.sampleRateExpression,
+      }),
     dateRange: [new Date(params.startTime), new Date(params.endTime)] as [
       Date,
       Date,

diff --git a/packages/api/src/tasks/checkAlerts/index.ts b/packages/api/src/tasks/checkAlerts/index.ts
@@ -107,6 +107,11 @@ export async function computeAliasWithClauses(
       source.kind === SourceKind.Log || source.kind === SourceKind.Trace
         ? source.implicitColumnExpression
         : undefined,
+    ...(source.kind === SourceKind.Trace &&
+      'sampleRateExpression' in source &&
+      source.sampleRateExpression && {
+        sampleWeightExpression: source.sampleRateExpression,
+      }),
     timestampValueExpression: source.timestampValueExpression,
   };
   const query = await renderChartConfig(config, metadata, source.querySettings);
@@ -453,6 +458,11 @@ const getChartConfigFromAlert = (
         source.kind === SourceKind.Log || source.kind === SourceKind.Trace
           ? source.implicitColumnExpression
           : undefined,
+      ...(source.kind === SourceKind.Trace &&
+        'sampleRateExpression' in source &&
+        source.sampleRateExpression && {
+          sampleWeightExpression: source.sampleRateExpression,
+        }),
       timestampValueExpression: source.timestampValueExpression,
     };
   } else if (details.taskType === AlertTaskType.TILE) {
@@ -474,6 +484,12 @@ const getChartConfigFromAlert = (
         source.kind === SourceKind.Log || source.kind === SourceKind.Trace
           ? source.implicitColumnExpression
           : undefined;
+      const sampleWeightExpression =
+        source.kind === SourceKind.Trace &&
+        'sampleRateExpression' in source &&
+        source.sampleRateExpression
+          ? source.sampleRateExpression
+          : undefined;
       const metricTables =
         source.kind === SourceKind.Metric ? source.metricTables : undefined;
       return {
@@ -486,6 +502,7 @@ const getChartConfigFromAlert = (
         granularity: `${windowSizeInMins} minute`,
         groupBy: tile.config.groupBy,
         implicitColumnExpression,
+        sampleWeightExpression,
         metricTables,
         select: tile.config.select,
         timestampValueExpression: source.timestampValueExpression,

diff --git a/packages/api/src/tasks/checkAlerts/template.ts b/packages/api/src/tasks/checkAlerts/template.ts
@@ -598,6 +598,11 @@ ${targetTemplate}`;
       where: savedSearch.where,
       whereLanguage: savedSearch.whereLanguage,
       implicitColumnExpression: source.implicitColumnExpression,
+      ...(source.kind === SourceKind.Trace &&
+        'sampleRateExpression' in source &&
+        source.sampleRateExpression && {
+          sampleWeightExpression: source.sampleRateExpression,
+        }),
       timestampValueExpression: source.timestampValueExpression,
       orderBy: savedSearch.orderBy,
       limit: {

diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx
@@ -231,6 +231,9 @@ const Tile = forwardRef(
             ...chart.config,
             // Populate these two columns from the source to support Lucene-based filters
             ...pick(source, ['implicitColumnExpression', 'from']),
+            sampleWeightExpression: isTraceSource(source)
+              ? source.sampleRateExpression
+              : undefined,
             dateRange,
             granularity,
             filters,
@@ -265,6 +268,9 @@ const Tile = forwardRef(
               isLogSource(source) || isTraceSource(source)
                 ? source.implicitColumnExpression
                 : undefined,
+            sampleWeightExpression: isTraceSource(source)
+              ? source.sampleRateExpression
+              : undefined,
             filters,
             metricTables: isMetricSource ? source.metricTables : undefined,
           });

diff --git a/packages/app/src/DBSearchPage.tsx b/packages/app/src/DBSearchPage.tsx
@@ -638,6 +638,9 @@ function useSearchedConfigToChartConfig(
           whereLanguage: whereLanguage ?? 'sql',
           timestampValueExpression: sourceObj.timestampValueExpression,
           implicitColumnExpression: sourceObj.implicitColumnExpression,
+          ...(isTraceSource(sourceObj) && sourceObj.sampleRateExpression
+            ? { sampleWeightExpression: sourceObj.sampleRateExpression }
+            : {}),
           connection: sourceObj.connection,
           displayType: DisplayType.Search,
           orderBy: orderBy || defaultSearchConfig?.orderBy || defaultOrderBy,

diff --git a/packages/app/src/ServicesDashboardPage.tsx b/packages/app/src/ServicesDashboardPage.tsx
@@ -33,6 +33,9 @@ function pickSourceConfigFields(source: TSource) {
     ...(isLogSource(source) || isTraceSource(source)
       ? { implicitColumnExpression: source.implicitColumnExpression }
       : {}),
+    ...(isTraceSource(source) && source.sampleRateExpression
+      ? { sampleWeightExpression: source.sampleRateExpression }
+      : {}),
   };
 }
 import {

diff --git a/packages/app/src/SessionSubpanel.tsx b/packages/app/src/SessionSubpanel.tsx
@@ -188,6 +188,9 @@ function useSessionChartConfigs({
       where,
       timestampValueExpression: traceSource.timestampValueExpression,
       implicitColumnExpression: traceSource.implicitColumnExpression,
+      ...(traceSource.sampleRateExpression && {
+        sampleWeightExpression: traceSource.sampleRateExpression,
+      }),
       connection: traceSource.connection,
       orderBy: `${traceSource.timestampValueExpression} ASC`,
       limit: {

diff --git a/packages/app/src/components/AlertPreviewChart.tsx b/packages/app/src/components/AlertPreviewChart.tsx
@@ -74,6 +74,9 @@ export const AlertPreviewChart = ({
             isLogSource(source) || isTraceSource(source)
               ? source.implicitColumnExpression
               : undefined,
+          sampleWeightExpression: isTraceSource(source)
+            ? source.sampleRateExpression
+            : undefined,
           groupBy,
           with: aliasWith,
           select: [

diff --git a/packages/app/src/components/ChartEditor/utils.ts b/packages/app/src/components/ChartEditor/utils.ts
@@ -142,6 +142,9 @@ export function convertFormStateToChartConfig(
         isLogSource(source) || isTraceSource(source)
           ? source.implicitColumnExpression
           : undefined,
+      sampleWeightExpression: isTraceSource(source)
+        ? source.sampleRateExpression
+        : undefined,
       metricTables: isMetricSource(source) ? source.metricTables : undefined,
       where: form.where ?? '',
       select: isSelectEmpty

diff --git a/packages/app/src/components/ServiceDashboardDbQuerySidePanel.tsx b/packages/app/src/components/ServiceDashboardDbQuerySidePanel.tsx
@@ -109,6 +109,9 @@ export default function ServiceDashboardDbQuerySidePanel({
                           'connection',
                           'from',
                         ]),
+                        ...(source.sampleRateExpression && {
+                          sampleWeightExpression: source.sampleRateExpression,
+                        }),
                         where: '',
                         whereLanguage: 'sql',
                         select: [
@@ -146,6 +149,9 @@ export default function ServiceDashboardDbQuerySidePanel({
                           'connection',
                           'from',
                         ]),
+                        ...(source.sampleRateExpression && {
+                          sampleWeightExpression: source.sampleRateExpression,
+                        }),
                         where: '',
                         whereLanguage: 'sql',
                         select: [

diff --git a/packages/app/src/components/ServiceDashboardEndpointPerformanceChart.tsx b/packages/app/src/components/ServiceDashboardEndpointPerformanceChart.tsx
@@ -95,6 +95,9 @@ export default function ServiceDashboardEndpointPerformanceChart({
           config={{
             source: source.id,
             ...pick(source, ['timestampValueExpression', 'connection', 'from']),
+            ...(source.sampleRateExpression && {
+              sampleWeightExpression: source.sampleRateExpression,
+            }),
             where: '',
             whereLanguage: 'sql',
             select: [

diff --git a/packages/app/src/components/ServiceDashboardEndpointSidePanel.tsx b/packages/app/src/components/ServiceDashboardEndpointSidePanel.tsx
@@ -116,6 +116,9 @@ export default function ServiceDashboardEndpointSidePanel({
                           'connection',
                           'from',
                         ]),
+                        ...(source.sampleRateExpression && {
+                          sampleWeightExpression: source.sampleRateExpression,
+                        }),
                         where: '',
                         whereLanguage: 'sql',
                         select: [
@@ -159,6 +162,9 @@ export default function ServiceDashboardEndpointSidePanel({
                           'connection',
                           'from',
                         ]),
+                        ...(source.sampleRateExpression && {
+                          sampleWeightExpression: source.sampleRateExpression,
+                        }),
                         where: '',
                         whereLanguage: 'sql',
                         select: [

diff --git a/packages/app/src/components/ServiceDashboardSlowestEventsTile.tsx b/packages/app/src/components/ServiceDashboardSlowestEventsTile.tsx
@@ -33,6 +33,9 @@ export default function SlowestEventsTile({
     {
       source: source.id,
       ...pick(source, ['timestampValueExpression', 'connection', 'from']),
+      ...(source.sampleRateExpression && {
+        sampleWeightExpression: source.sampleRateExpression,
+      }),
       where: '',
       whereLanguage: 'sql',
       select: [
@@ -117,6 +120,9 @@ export default function SlowestEventsTile({
                   'connection',
                   'from',
                 ]),
+                ...(source.sampleRateExpression && {
+                  sampleWeightExpression: source.sampleRateExpression,
+                }),
                 where: '',
                 whereLanguage: 'sql',
                 select: [

diff --git a/packages/app/src/components/Sources/SourceForm.tsx b/packages/app/src/components/Sources/SourceForm.tsx
@@ -1545,6 +1545,21 @@ export function TraceTableModelForm(props: TableModelProps) {
           placeholder="SpanAttributes"
         />
       </FormRow>
+      <FormRow
+        label={'Sample Rate Expression'}
+        helpText="Column or expression for upstream sampling weight (1/N). When set, aggregations (count, avg, sum, quantile) are corrected for sampling. Percentiles use quantileTDigestWeighted, which is an approximation -- exact values may differ slightly. Leave empty if spans are not sampled."
+      >
+        <SQLInlineEditorControlled
+          tableConnection={{
+            databaseName,
+            tableName,
+            connectionId,
+          }}
+          control={control}
+          name="sampleRateExpression"
+          placeholder="SampleRate"
+        />
+      </FormRow>
       <FormRow
         label={'Span Events Expression'}
         helpText="Expression to extract span events. Used to capture events associated with spans. Expected to be Nested ( Timestamp DateTime64(9), Name LowCardinality(String), Attributes Map(LowCardinality(String), String)"

diff --git a/packages/app/src/sessions.ts b/packages/app/src/sessions.ts
@@ -162,6 +162,9 @@ export function useSessions(
             }),
             timestampValueExpression: traceSource.timestampValueExpression,
             implicitColumnExpression: traceSource.implicitColumnExpression,
+            ...(traceSource.sampleRateExpression && {
+              sampleWeightExpression: traceSource.sampleRateExpression,
+            }),
             connection: traceSource.connection,
             groupBy: 'serviceName, sessionId',
           },
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		ALTER TABLE ${DATABASE}.otel_traces DROP COLUMN IF EXISTS `SampleRate`;