feat: Add custom trace-level attributes above trace waterfall

[pulpdrew]

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

1. They are trace level (from any span in the trace), whereas the top of the side panel shows information specific to the span
2. The data comes from the same query as the waterfall, so moving the attributes to the top level would require coordinating the configurations / react query caches between the waterfall and the attributes components. This is definitely possible, but not worth the refactoring at this time.

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:

Values for those attributes within the trace show up on the trace panel above the waterfall:

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

[changeset-bot]

🦋 Changeset detected

Latest commit: f6e12c8

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	Patch
@hyperdx/api	Patch
@hyperdx/app	Patch

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	Nov 14, 2025 8:37pm

[claude]

PR Review - Trace-Level Highlighted Attributes

Code Quality Issues

• ⚠️ Missing input validation in EventTag.tsx:48 → SQL injection risk with SqlString.format when name parameter is user-controlled. The name parameter is passed directly from getAttributesFromData which gets it from source configuration, but should validate/sanitize before SQL formatting.

• ⚠️ Type inconsistency in getAttributesFromData:274 → Function parameter data typed as Record<string, unknown>[] but component passes Record<string, string | number>[]. Should align types to prevent runtime errors.

• ⚠️ Missing null check in DBTraceWaterfallChart.tsx:311 → Using non-null assertion attributeValuesByDisplayKey.get(displayName)! without verifying the key exists first. Should use conditional or verify existence.

• ⚠️ Potential performance issue in DBTraceAttributes → Component re-renders on every data change without memoization of expensive operations. Consider memoizing getAttributesFromData results or moving computation outside component.

• ⚠️ Missing validation in SourceForm.tsx:240 → appendHighlightedAttribute allows adding empty expressions. Should validate that at least sqlExpression is non-empty before allowing save (backend has validation but UX should prevent invalid state).

• ⚠️ MongoDB schema lacks validation → highlightedAttributeExpressions field in source.ts:69-71 has no schema structure defined. Should specify array item schema with required fields for data integrity.

Suggested Fixes

1. In EventTag.tsx:46-49, validate and escape the name parameter before using in SQL formatting
2. Align type definitions between getAttributesFromData and calling components
3. Replace non-null assertion with proper null checks or Optional chaining
4. Add MongoDB schema validation for highlightedAttributeExpressions array structure
5. Consider adding client-side validation in HighlightedAttributeExpressionsFormRow to prevent empty submissions

Minor Notes

• Tests look comprehensive (411 new lines added)
• Good use of Zod validation in common-utils types
• Documentation in CLAUDE.md properly updated with changeset

[github-actions]

E2E Test Results

✅ All tests passed • 39 passed • 3 skipped • 400s

Status	Count
✅ Passed	39
❌ Failed	0
⚠️ Flaky	1
⏭️ Skipped	3

View full report →

[pulpdrew]

JSON column values were being returned as actual null values here, which then broke the value.length check below.

[pulpdrew]

This check was preventing us from clearing the filter state if all filters were removed from the URL params (which happens when changing sources due to clicking on an attribute from a different source)