feat: Add custom trace-level attributes above trace waterfall (#1356)

Ref HDX-2752

# Summary

This PR adds a new Source setting which specifies additional Span-Level attributes which should be displayed above the Trace Waterfall. The attributes may be specified for both Log and Trace kind sources.

These are displayed on the trace panel rather than at the top of the side panel because they are trace level (from any span in the trace), whereas the top of the side panel shows information specific to the span. In a followup PR, we'll add row-level attributes, which will appear at the top of the side panel.

Notes:

1. The attributes are pulled from the log and trace source (if configured for each) despite the search page only being set to query one of those sources. If an attribute value comes from the log source while the trace source is currently configured on the search page, the attribute tag will not offer the option to show the "Add to search" button and instead will just show a "search this value" option, which navigates the search page to search the value in the correct source.

## Demo

First, source is configured with highlighted attributes:
<img width="954" height="288" alt="Screenshot 2025-11-14 at 3 02 25 PM" src="https://github.com/user-attachments/assets/e5eccbfa-3389-4521-83df-d63fcb13232a" />

Values for those attributes within the trace show up on the trace panel above the waterfall:
<img width="1257" height="152" alt="Screenshot 2025-11-14 at 3 02 59 PM" src="https://github.com/user-attachments/assets/7e3e9d87-5f3a-409b-9b08-054d6e460970" />

Values are searchable when clicked, and if a lucene version of the property is provided, the lucene version will be used in the search box
<img width="1334" height="419" alt="Screenshot 2025-11-14 at 3 03 10 PM" src="https://github.com/user-attachments/assets/50d98f99-5056-48ce-acca-4219286a68f7" />

Author: pulpdrew

.changeset/honest-mice-applaud.md

@@ -0,0 +1,7 @@
+---
+"@hyperdx/common-utils": patch
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+---
+
+feat: Add custom trace-level attributes above trace waterfall

packages/api/src/models/source.ts

@@ -66,6 +66,9 @@ export const Source = mongoose.model<ISource>(
       statusCodeExpression: String,
       statusMessageExpression: String,
       spanEventsValueExpression: String,
+      highlightedTraceAttributeExpressions: {
+        type: mongoose.Schema.Types.Array,
+      },
 
       metricTables: {
         type: {

packages/app/src/DBSearchPage.tsx

@@ -34,6 +34,7 @@ import {
   DisplayType,
   Filter,
   SourceKind,
+  TSource,
 } from '@hyperdx/common-utils/dist/types';
 import {
   ActionIcon,
@@ -1091,21 +1092,32 @@ function DBSearchPage() {
     ({
       where,
       whereLanguage,
+      source,
     }: {
       where: SearchConfig['where'];
       whereLanguage: SearchConfig['whereLanguage'];
+      source?: TSource;
     }) => {
       const qParams = new URLSearchParams({
-        where: where || searchedConfig.where || '',
         whereLanguage: whereLanguage || 'sql',
         from: searchedTimeRange[0].getTime().toString(),
         to: searchedTimeRange[1].getTime().toString(),
-        select: searchedConfig.select || '',
-        source: searchedSource?.id || '',
-        filters: JSON.stringify(searchedConfig.filters ?? []),
         isLive: 'false',
         liveInterval: interval.toString(),
       });
+
+      // When generating a search based on a different source,
+      // filters and select for the current source are not preserved.
+      if (source && source.id !== searchedSource?.id) {
+        qParams.append('where', where || '');
+        qParams.append('source', source.id);
+      } else {
+        qParams.append('select', searchedConfig.select || '');
+        qParams.append('where', where || searchedConfig.where || '');
+        qParams.append('filters', JSON.stringify(searchedConfig.filters ?? []));
+        qParams.append('source', searchedSource?.id || '');
+      }
+
       return `/search?${qParams.toString()}`;
     },
     [
@@ -1829,6 +1841,7 @@ function DBSearchPage() {
                             dbSqlRowTableConfig,
                             isChildModalOpen: isDrawerChildModalOpen,
                             setChildModalOpen: setDrawerChildModalOpen,
+                            source: searchedSource,
                           }}
                           config={dbSqlRowTableConfig}
                           sourceId={searchedConfig.source}

packages/app/src/components/DBHighlightedAttributesList.tsx

@@ -0,0 +1,67 @@
+import { useContext, useMemo } from 'react';
+import { TSource } from '@hyperdx/common-utils/dist/types';
+import { Flex } from '@mantine/core';
+
+import { RowSidePanelContext } from './DBRowSidePanel';
+import EventTag from './EventTag';
+
+export type HighlightedAttribute = {
+  source: TSource;
+  displayedKey: string;
+  value: string;
+  sql: string;
+  lucene?: string;
+};
+
+export function DBHighlightedAttributesList({
+  attributes = [],
+}: {
+  attributes: HighlightedAttribute[];
+}) {
+  const {
+    onPropertyAddClick,
+    generateSearchUrl,
+    source: contextSource,
+  } = useContext(RowSidePanelContext);
+
+  const sortedAttributes = useMemo(() => {
+    return attributes.sort(
+      (a, b) =>
+        a.displayedKey.localeCompare(b.displayedKey) ||
+        a.value.localeCompare(b.value),
+    );
+  }, [attributes]);
+
+  return (
+    <Flex wrap="wrap" gap="2px" mb="md">
+      {sortedAttributes.map(({ displayedKey, value, sql, lucene, source }) => (
+        <EventTag
+          displayedKey={displayedKey}
+          name={lucene ? lucene : sql}
+          nameLanguage={lucene ? 'lucene' : 'sql'}
+          value={value as string}
+          key={`${displayedKey}-${value}-${source.id}`}
+          {...(onPropertyAddClick && contextSource?.id === source.id
+            ? {
+                onPropertyAddClick,
+                sqlExpression: sql,
+              }
+            : {
+                onPropertyAddClick: undefined,
+                sqlExpression: undefined,
+              })}
+          generateSearchUrl={
+            generateSearchUrl
+              ? (query, queryLanguage) =>
+                  generateSearchUrl({
+                    where: query || '',
+                    whereLanguage: queryLanguage ?? 'lucene',
+                    source,
+                  })
+              : undefined
+          }
+        />
+      ))}
+    </Flex>
+  );
+}

packages/app/src/components/DBRowOverviewPanel.tsx

@@ -81,11 +81,11 @@ export function RowOverviewPanel({
       : {};
 
   const _generateSearchUrl = useCallback(
-    (query?: string, timeRange?: [Date, Date]) => {
+    (query?: string, queryLanguage?: 'sql' | 'lucene') => {
       return (
         generateSearchUrl?.({
           where: query,
-          whereLanguage: 'lucene',
+          whereLanguage: queryLanguage,
         }) ?? '/'
       );
     },
@@ -195,8 +195,6 @@ export function RowOverviewPanel({
               <Box px="md">
                 <NetworkPropertySubpanel
                   eventAttributes={flattenedEventAttributes}
-                  onPropertyAddClick={onPropertyAddClick}
-                  generateSearchUrl={_generateSearchUrl}
                 />
               </Box>
             </Accordion.Panel>

packages/app/src/components/DBRowSidePanel.tsx

@@ -46,9 +46,11 @@ export type RowSidePanelContextProps = {
   generateSearchUrl?: ({
     where,
     whereLanguage,
+    source,
   }: {
     where: SearchConfig['where'];
     whereLanguage: SearchConfig['whereLanguage'];
+    source?: TSource;
   }) => string;
   generateChartUrl?: (config: {
     aggFn: string;
@@ -61,6 +63,7 @@ export type RowSidePanelContextProps = {
   dbSqlRowTableConfig?: ChartConfigWithDateRange;
   isChildModalOpen?: boolean;
   setChildModalOpen?: (open: boolean) => void;
+  source?: TSource;
 };
 
 export const RowSidePanelContext = createContext<RowSidePanelContextProps>({});

packages/app/src/components/DBRowSidePanelHeader.tsx

@@ -175,11 +175,11 @@ export default function DBRowSidePanelHeader({
   const maxBoxHeight = 120;
 
   const _generateSearchUrl = useCallback(
-    (query?: string, timeRange?: [Date, Date]) => {
+    (query?: string, queryLanguage?: 'sql' | 'lucene') => {
       return (
         generateSearchUrl?.({
           where: query,
-          whereLanguage: 'lucene',
+          whereLanguage: queryLanguage,
         }) ?? '/'
       );
     },