Merge branch 'main' into issue_6021

docs/api/openapi.yml

@@ -8349,6 +8349,8 @@ components:
           $ref: '#/components/schemas/RuletypesAlertState'
         overallStateChanged:
           type: boolean
+        relatedAITracesLink:
+          type: string
         relatedLogsLink:
           type: string
         relatedTracesLink:
@@ -8392,6 +8394,8 @@ components:
             $ref: '#/components/schemas/Querybuildertypesv5Label'
           nullable: true
           type: array
+        relatedAITracesLink:
+          type: string
         relatedLogsLink:
           type: string
         relatedTracesLink:
@@ -8497,6 +8501,7 @@ components:
       - TRACES_BASED_ALERT
       - LOGS_BASED_ALERT
       - EXCEPTIONS_BASED_ALERT
+      - AI_TRACES_BASED_ALERT
       type: string
     RuletypesBasicRuleThreshold:
       properties:

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -9610,6 +9610,10 @@ export interface RulestatehistorytypesGettableRuleStateHistoryDTO {
 	 * @type boolean
 	 */
 	overallStateChanged: boolean;
+	/**
+	 * @type string
+	 */
+	relatedAITracesLink?: string;
 	/**
 	 * @type string
 	 */
@@ -9658,6 +9662,10 @@ export interface RulestatehistorytypesGettableRuleStateHistoryContributorDTO {
 	 * @type array,null
 	 */
 	labels: Querybuildertypesv5LabelDTO[] | null;
+	/**
+	 * @type string
+	 */
+	relatedAITracesLink?: string;
 	/**
 	 * @type string
 	 */
@@ -9753,6 +9761,7 @@ export enum RuletypesAlertTypeDTO {
 	TRACES_BASED_ALERT = 'TRACES_BASED_ALERT',
 	LOGS_BASED_ALERT = 'LOGS_BASED_ALERT',
 	EXCEPTIONS_BASED_ALERT = 'EXCEPTIONS_BASED_ALERT',
+	AI_TRACES_BASED_ALERT = 'AI_TRACES_BASED_ALERT',
 }
 export enum RuletypesMatchTypeDTO {
 	at_least_once = 'at_least_once',

pkg/contextlinks/links.go

@@ -12,25 +12,32 @@ import (
 
 // PrepareParamsForTracesV5 returns the traces explorer query params for the
 // given range and filter; the traces explorer writes its time params in
-// nanoseconds.
-func PrepareParamsForTracesV5(start, end time.Time, whereClause string) url.Values {
-	return prepareExplorerParams("traces", start.UnixNano(), end.UnixNano(), whereClause)
+// nanoseconds. queryType is builder_ai_query for the AI observability explorer.
+func PrepareParamsForTracesV5(start, end time.Time, whereClause string, queryType qbtypes.QueryType) url.Values {
+	return prepareExplorerParams("traces", queryType, start.UnixNano(), end.UnixNano(), whereClause)
 }
 
 // PrepareParamsForLogsV5 returns the logs explorer query params for the given
 // range and filter; the logs explorer writes its time params in milliseconds.
 func PrepareParamsForLogsV5(start, end time.Time, whereClause string) url.Values {
-	return prepareExplorerParams("logs", start.UnixMilli(), end.UnixMilli(), whereClause)
+	return prepareExplorerParams("logs", qbtypes.QueryTypeBuilder, start.UnixMilli(), end.UnixMilli(), whereClause)
 }
 
 // The end link is double encoded because otherwise a filter expression with `%` somewhere in it breaks.
-func prepareExplorerParams(dataSource string, start, end int64, whereClause string) url.Values {
+func prepareExplorerParams(dataSource string, queryType qbtypes.QueryType, start, end int64, whereClause string) url.Values {
+	// builder_query is the explorer default, so it is left out to keep existing links unchanged
+	builderQueryType := ""
+	if queryType != qbtypes.QueryTypeBuilder {
+		builderQueryType = queryType.StringValue()
+	}
+
 	urlData := URLShareableCompositeQuery{
 		QueryType: "builder",
 		Builder: URLShareableBuilderQuery{
 			QueryData: []LinkQuery{{
-				DataSource: dataSource,
-				Filter:     &FilterExpression{Expression: whereClause},
+				DataSource:       dataSource,
+				BuilderQueryType: builderQueryType,
+				Filter:           &FilterExpression{Expression: whereClause},
 			}},
 			QueryFormulas: make([]string, 0),
 		},
@@ -47,7 +54,8 @@ func prepareExplorerParams(dataSource string, start, end int64, whereClause stri
 
 // BuilderQueryForSignal returns the filter expression and group-by keys of the
 // builder query for the given signal, or found=false when the composite query
-// has no builder query for it (e.g. PromQL or ClickHouse SQL alerts).
+// has no builder query for it (e.g. PromQL or ClickHouse SQL alerts). AI trace
+// queries (builder_ai_query) count as trace builder queries.
 // TODO(srikanthccv): re-visit this and support multiple queries.
 func BuilderQueryForSignal(queries []qbtypes.QueryEnvelope, signal telemetrytypes.Signal) (string, []qbtypes.GroupByKey, bool) {
 	switch signal {
@@ -63,7 +71,7 @@ func builderQueryForSignal[T any](queries []qbtypes.QueryEnvelope, signal teleme
 	var q qbtypes.QueryBuilderQuery[T]
 	found := false
 	for _, query := range queries {
-		if query.Type != qbtypes.QueryTypeBuilder {
+		if query.Type != qbtypes.QueryTypeBuilder && query.Type != qbtypes.QueryTypeBuilderAI {
 			continue
 		}
 		if spec, ok := query.Spec.(qbtypes.QueryBuilderQuery[T]); ok {

pkg/contextlinks/links_test.go

@@ -30,6 +30,15 @@ func TestBuilderQueryForSignal(t *testing.T) {
 		Type: qbtypes.QueryTypePromQL,
 		Spec: qbtypes.PromQuery{Name: "C"},
 	}
+	aiTraceQuery := qbtypes.QueryEnvelope{
+		Type: qbtypes.QueryTypeBuilderAI,
+		Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+			Name:    "D",
+			Signal:  telemetrytypes.SignalTraces,
+			Filter:  &qbtypes.Filter{Expression: "trace.input_tokens > 1000"},
+			GroupBy: []qbtypes.GroupByKey{{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "session.id"}}},
+		},
+	}
 
 	t.Run("logs query among mixed queries", func(t *testing.T) {
 		filterExpr, groupBy, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{promQuery, logQuery, traceQuery}, telemetrytypes.SignalLogs)
@@ -46,6 +55,14 @@ func TestBuilderQueryForSignal(t *testing.T) {
 		assert.Empty(t, groupBy)
 	})
 
+	t.Run("ai trace query counts as traces", func(t *testing.T) {
+		filterExpr, groupBy, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{logQuery, aiTraceQuery}, telemetrytypes.SignalTraces)
+		require.True(t, found)
+		assert.Equal(t, "trace.input_tokens > 1000", filterExpr)
+		require.Len(t, groupBy, 1)
+		assert.Equal(t, "session.id", groupBy[0].Name)
+	})
+
 	t.Run("no builder query for signal", func(t *testing.T) {
 		_, _, found := BuilderQueryForSignal([]qbtypes.QueryEnvelope{traceQuery}, telemetrytypes.SignalLogs)
 		assert.False(t, found)

pkg/contextlinks/types.go

@@ -13,8 +13,9 @@ type FilterExpression struct {
 // LinkQuery carries the only fields the explorer pages read from a shared
 // link; the frontend fills in the rest of the query shape with defaults.
 type LinkQuery struct {
-	DataSource string            `json:"dataSource"`
-	Filter     *FilterExpression `json:"filter,omitempty"`
+	DataSource       string            `json:"dataSource"`
+	BuilderQueryType string            `json:"builderQueryType,omitempty"`
+	Filter           *FilterExpression `json:"filter,omitempty"`
 }
 
 type URLShareableBuilderQuery struct {

pkg/modules/rulestatehistory/implrulestatehistory/handler.go

@@ -114,6 +114,7 @@ func (h *handler) GetRuleHistoryTimeline(w http.ResponseWriter, r *http.Request)
 			Fingerprint:         item.Fingerprint,
 			Value:               item.Value,
 			RelatedTracesLink:   item.RelatedTracesLink,
+			RelatedAITracesLink: item.RelatedAITracesLink,
 			RelatedLogsLink:     item.RelatedLogsLink,
 		})
 	}
@@ -151,11 +152,12 @@ func (h *handler) GetRuleHistoryContributors(w http.ResponseWriter, r *http.Requ
 	converted := make([]rulestatehistorytypes.GettableRuleStateHistoryContributor, 0, len(res))
 	for _, item := range res {
 		converted = append(converted, rulestatehistorytypes.GettableRuleStateHistoryContributor{
-			Fingerprint:       item.Fingerprint,
-			Labels:            item.Labels.ToQBLabels(),
-			Count:             item.Count,
-			RelatedTracesLink: item.RelatedTracesLink,
-			RelatedLogsLink:   item.RelatedLogsLink,
+			Fingerprint:         item.Fingerprint,
+			Labels:              item.Labels.ToQBLabels(),
+			Count:               item.Count,
+			RelatedTracesLink:   item.RelatedTracesLink,
+			RelatedAITracesLink: item.RelatedAITracesLink,
+			RelatedLogsLink:     item.RelatedLogsLink,
 		})
 	}
 	render.Success(w, http.StatusOK, converted)

pkg/modules/rulestatehistory/implrulestatehistory/links.go

@@ -41,7 +41,8 @@ func (m *module) relatedLinkBuilderForRule(ctx context.Context, orgID valuer.UUI
 		return nil
 	}
 
-	if rule.AlertType != ruletypes.AlertTypeLogs && rule.AlertType != ruletypes.AlertTypeTraces {
+	signal, ok := relatedLinkSignal(rule.AlertType)
+	if !ok {
 		return nil
 	}
 	if rule.RuleCondition == nil || rule.RuleCondition.CompositeQuery == nil {
@@ -62,10 +63,6 @@ func (m *module) relatedLinkBuilderForRule(ctx context.Context, orgID valuer.UUI
 		builder.evaluation = ruletypes.RollingWindow{EvalWindow: evalWindow}
 	}
 
-	signal := telemetrytypes.SignalLogs
-	if rule.AlertType == ruletypes.AlertTypeTraces {
-		signal = telemetrytypes.SignalTraces
-	}
 	// links are still built from the labels alone when the rule has no builder
 	// query for the signal (e.g. ClickHouse SQL alerts)
 	builder.filterExpr, builder.groupBy, _ = contextlinks.BuilderQueryForSignal(rule.RuleCondition.CompositeQuery.Queries, signal)
@@ -84,21 +81,35 @@ func (b *relatedLinkBuilder) queryWindow(unixMilli int64) (time.Time, time.Time)
 	return start.Add(-3 * time.Minute), end
 }
 
-// links returns the encoded logs and traces explorer query params for the
-// given entry labels and time range; at most one of the two is non-empty.
-func (b *relatedLinkBuilder) links(labels rulestatehistorytypes.LabelsString, start, end time.Time) (string, string) {
+// links returns the explorer query params for the given entry labels and time
+// range.
+func (b *relatedLinkBuilder) links(labels rulestatehistorytypes.LabelsString, start, end time.Time) rulestatehistorytypes.RelatedLinks {
 	lbls := map[string]string{}
 	if err := json.Unmarshal([]byte(labels), &lbls); err != nil {
-		return "", ""
+		return rulestatehistorytypes.RelatedLinks{}
 	}
 
 	whereClause := contextlinks.PrepareFilterExpression(lbls, b.filterExpr, b.groupBy)
 
 	switch b.alertType {
 	case ruletypes.AlertTypeLogs:
-		return contextlinks.PrepareParamsForLogsV5(start, end, whereClause).Encode(), ""
+		return rulestatehistorytypes.RelatedLinks{RelatedLogsLink: contextlinks.PrepareParamsForLogsV5(start, end, whereClause).Encode()}
 	case ruletypes.AlertTypeTraces:
-		return "", contextlinks.PrepareParamsForTracesV5(start, end, whereClause).Encode()
+		return rulestatehistorytypes.RelatedLinks{RelatedTracesLink: contextlinks.PrepareParamsForTracesV5(start, end, whereClause, qbtypes.QueryTypeBuilder).Encode()}
+	case ruletypes.AlertTypeAITraces:
+		return rulestatehistorytypes.RelatedLinks{RelatedAITracesLink: contextlinks.PrepareParamsForTracesV5(start, end, whereClause, qbtypes.QueryTypeBuilderAI).Encode()}
 	}
-	return "", ""
+	return rulestatehistorytypes.RelatedLinks{}
+}
+
+// relatedLinkSignal returns the explorer signal that related links open for
+// the alert type, or ok=false when the alert type has none (e.g. metrics).
+func relatedLinkSignal(alertType ruletypes.AlertType) (telemetrytypes.Signal, bool) {
+	switch alertType {
+	case ruletypes.AlertTypeLogs:
+		return telemetrytypes.SignalLogs, true
+	case ruletypes.AlertTypeTraces, ruletypes.AlertTypeAITraces:
+		return telemetrytypes.SignalTraces, true
+	}
+	return telemetrytypes.SignalUnspecified, false
 }

pkg/modules/rulestatehistory/implrulestatehistory/module.go

@@ -34,7 +34,7 @@ func (m *module) GetHistoryTimeline(ctx context.Context, orgID valuer.UUID, rule
 	if builder := m.relatedLinkBuilderForRule(ctx, orgID, ruleID); builder != nil {
 		for idx := range items {
 			start, end := builder.queryWindow(items[idx].UnixMilli)
-			items[idx].RelatedLogsLink, items[idx].RelatedTracesLink = builder.links(items[idx].Labels, start, end)
+			items[idx].RelatedLinks = builder.links(items[idx].Labels, start, end)
 		}
 	}
 
@@ -60,7 +60,7 @@ func (m *module) GetHistoryContributors(ctx context.Context, orgID valuer.UUID,
 		// span it too instead of a single evaluation window
 		start, end := time.UnixMilli(query.Start), time.UnixMilli(query.End)
 		for idx := range contributors {
-			contributors[idx].RelatedLogsLink, contributors[idx].RelatedTracesLink = builder.links(contributors[idx].Labels, start, end)
+			contributors[idx].RelatedLinks = builder.links(contributors[idx].Labels, start, end)
 		}
 	}
 

pkg/query-service/app/http_handler.go

@@ -830,12 +830,12 @@ func (aH *APIHandler) getRuleStateHistory(w http.ResponseWriter, r *http.Request
 				whereClause := contextlinks.PrepareFilterExpression(lbls, filterExpr, q.GroupBy)
 
 				res.Items[idx].RelatedLogsLink = contextlinks.PrepareParamsForLogsV5(start, end, whereClause).Encode()
-			} else if rule.AlertType == ruletypes.AlertTypeTraces {
+			} else if rule.AlertType == ruletypes.AlertTypeTraces || rule.AlertType == ruletypes.AlertTypeAITraces {
 				// TODO(srikanthccv): re-visit this and support multiple queries
 				var q qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]
 
 				for _, query := range rule.RuleCondition.CompositeQuery.Queries {
-					if query.Type == qbtypes.QueryTypeBuilder {
+					if query.Type == qbtypes.QueryTypeBuilder || query.Type == qbtypes.QueryTypeBuilderAI {
 						switch spec := query.Spec.(type) {
 						case qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]:
 							q = spec
@@ -849,7 +849,7 @@ func (aH *APIHandler) getRuleStateHistory(w http.ResponseWriter, r *http.Request
 				}
 
 				whereClause := contextlinks.PrepareFilterExpression(lbls, filterExpr, q.GroupBy)
-				res.Items[idx].RelatedTracesLink = contextlinks.PrepareParamsForTracesV5(start, end, whereClause).Encode()
+				res.Items[idx].RelatedTracesLink = contextlinks.PrepareParamsForTracesV5(start, end, whereClause, rule.AlertType.BuilderQueryType()).Encode()
 			}
 		}
 	}

pkg/query-service/rules/base_rule.go

@@ -420,7 +420,7 @@ func (r *BaseRule) ShouldSkipNewGroups() bool {
 func (r *BaseRule) isFilterNewSeriesSupported() bool {
 	if r.ruleCondition.CompositeQuery.QueryType == ruletypes.QueryTypeBuilder {
 		for _, query := range r.ruleCondition.CompositeQuery.Queries {
-			if query.Type != qbtypes.QueryTypeBuilder {
+			if query.Type != qbtypes.QueryTypeBuilder && query.Type != qbtypes.QueryTypeBuilderAI {
 				continue
 			}
 			switch query.Spec.(type) {

pkg/query-service/rules/base_rule_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
@@ -164,6 +165,24 @@ type filterNewSeriesTestCase struct {
 	expectError       bool
 }
 
+func TestBaseRule_IsFilterNewSeriesSupported(t *testing.T) {
+	postableRule := createPostableRule(&ruletypes.AlertCompositeQuery{
+		QueryType: ruletypes.QueryTypeBuilder,
+		Queries: []qbtypes.QueryEnvelope{{
+			Type: qbtypes.QueryTypeBuilderAI,
+			Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+				Name:         "A",
+				Signal:       telemetrytypes.SignalTraces,
+				Aggregations: []qbtypes.TraceAggregation{{Expression: "max(trace.total_tokens)"}},
+			},
+		}},
+	})
+
+	rule, err := NewBaseRule("test-rule", valuer.GenerateUUID(), &postableRule, mustParseURL(t, "http://localhost:8080"), WithLogger(instrumentationtest.New().Logger()))
+	require.NoError(t, err)
+	assert.False(t, rule.isFilterNewSeriesSupported())
+}
+
 func TestBaseRule_FilterNewSeries(t *testing.T) {
 	defaultEvalTime := time.Unix(1700000000, 0)
 	defaultNewGroupEvalDelay := valuer.MustParseTextDuration("2m")

pkg/query-service/rules/setups_test.go

@@ -9,6 +9,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/querier"
 	"github.com/SigNoz/signoz/pkg/statementbuilder"
+	"github.com/SigNoz/signoz/pkg/statementbuilder/aistatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/logsstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/metricsstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/tracesstatementbuilder"
@@ -127,3 +128,40 @@ func prepareQuerierForTraces(t *testing.T, telemetryStore telemetrystore.Telemet
 		0, // maxConcurrentQueries (0 means default)
 	)
 }
+
+func prepareQuerierForAITraces(t *testing.T, telemetryStore telemetrystore.TelemetryStore, keysMap map[string][]*telemetrytypes.TelemetryFieldKey) querier.Querier {
+	t.Helper()
+
+	providerSettings := instrumentationtest.New().ToProviderSettings()
+	metadataStore := telemetrytypestest.NewMockMetadataStore()
+
+	for _, keys := range keysMap {
+		for _, key := range keys {
+			key.Signal = telemetrytypes.SignalTraces
+		}
+	}
+	metadataStore.KeysMap = keysMap
+
+	fl := flaggertest.New(t)
+	aiTraceStmtBuilder, err := aistatementbuilder.NewFactory(telemetryStore, metadataStore, fl).New(context.Background(), providerSettings, statementbuilder.Config{})
+	require.NoError(t, err)
+
+	return querier.New(
+		providerSettings,
+		telemetryStore,
+		metadataStore,
+		nil, // prometheus
+		nil, // promV2
+		nil, // traceStmtBuilder
+		aiTraceStmtBuilder,
+		nil, // logStmtBuilder
+		nil, // auditStmtBuilder
+		nil, // metricStmtBuilder
+		nil, // meterStmtBuilder
+		nil, // traceOperatorStmtBuilder
+		nil, // bucketCache
+		fl,
+		0,
+		0, // maxConcurrentQueries (0 means default)
+	)
+}

pkg/query-service/rules/threshold_rule.go

@@ -132,7 +132,7 @@ func (r *ThresholdRule) prepareParamsForTraces(ctx context.Context, ts time.Time
 
 	whereClause := contextlinks.PrepareFilterExpression(lbls.Map(), filterExpr, groupBy)
 
-	return contextlinks.PrepareParamsForTracesV5(start, end, whereClause)
+	return contextlinks.PrepareParamsForTracesV5(start, end, whereClause, r.typ.BuilderQueryType())
 }
 
 func (r *ThresholdRule) buildAndRunQuery(ctx context.Context, orgID valuer.UUID, ts time.Time) (ruletypes.Vector, error) {
@@ -308,10 +308,14 @@ func (r *ThresholdRule) Eval(ctx context.Context, ts time.Time) (int, error) {
 		// is used alert grouping, and we want to group alerts with the same
 		// label set, but different timestamps, together.
 		switch r.typ {
-		case ruletypes.AlertTypeTraces:
+		case ruletypes.AlertTypeTraces, ruletypes.AlertTypeAITraces:
 			params := r.prepareParamsForTraces(ctx, ts, smpl.Metric)
 			if len(params) > 0 {
-				link := r.ExternalURL("traces-explorer", params)
+				explorerPath := "traces-explorer"
+				if r.typ == ruletypes.AlertTypeAITraces {
+					explorerPath = "ai-observability/explorer"
+				}
+				link := r.ExternalURL(explorerPath, params)
 				r.logger.InfoContext(ctx, "adding traces link to annotations", slog.String("annotation.link", link))
 				annotations = append(annotations, ruletypes.Label{Name: ruletypes.AnnotationRelatedTraces, Value: link})
 			}

pkg/query-service/rules/threshold_rule_test.go

@@ -916,6 +916,104 @@ func TestThresholdRuleTracesLink(t *testing.T) {
 	}
 }
 
+func TestThresholdRuleAITracesLink(t *testing.T) {
+	postableRule := ruletypes.PostableRule{
+		AlertName: "AI traces link test",
+		AlertType: ruletypes.AlertTypeAITraces,
+		RuleType:  ruletypes.RuleTypeThreshold,
+		Evaluation: &ruletypes.EvaluationEnvelope{Kind: ruletypes.RollingEvaluation, Spec: ruletypes.RollingWindow{
+			EvalWindow: valuer.MustParseTextDuration("5m"),
+			Frequency:  valuer.MustParseTextDuration("1m"),
+		}},
+		RuleCondition: &ruletypes.RuleCondition{
+			CompositeQuery: &ruletypes.AlertCompositeQuery{
+				QueryType: ruletypes.QueryTypeBuilder,
+				Queries: []qbtypes.QueryEnvelope{{
+					Type: qbtypes.QueryTypeBuilderAI,
+					Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+						Name:         "A",
+						StepInterval: qbtypes.Step{Duration: time.Minute},
+						Aggregations: []qbtypes.TraceAggregation{{
+							Expression: "count()",
+						}},
+						Signal: telemetrytypes.SignalTraces,
+						Filter: &qbtypes.Filter{
+							Expression: "service.name = 'llm-gateway'",
+						},
+					},
+				}},
+			},
+		},
+	}
+
+	cols := make([]cmock.ColumnType, 0)
+	cols = append(cols, cmock.ColumnType{Name: "value", Type: "Float64"})
+	cols = append(cols, cmock.ColumnType{Name: "attr", Type: "String"})
+	cols = append(cols, cmock.ColumnType{Name: "timestamp", Type: "DateTime"})
+
+	keysMap := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"service.name": {
+			{
+				Name:          "service.name",
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			},
+		},
+	}
+
+	logger := instrumentationtest.New().Logger()
+
+	for idx, c := range testCases {
+
+		telemetryStore := telemetrystoretest.New(telemetrystore.Config{}, &queryMatcherAny{})
+
+		rows := cmock.NewRows(cols, c.values)
+		telemetryStore.Mock().
+			ExpectQuery("SELECT any").
+			WithArgs(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil).
+			WillReturnRows(rows)
+
+		querier := prepareQuerierForAITraces(t, telemetryStore, keysMap)
+
+		postableRule.RuleCondition.CompareOperator = c.compareOperator
+		postableRule.RuleCondition.MatchType = c.matchType
+		postableRule.RuleCondition.Target = &c.target
+		postableRule.RuleCondition.CompositeQuery.Unit = c.yAxisUnit
+		postableRule.RuleCondition.TargetUnit = c.targetUnit
+		postableRule.RuleCondition.Thresholds = &ruletypes.RuleThresholdData{
+			Kind: ruletypes.BasicThresholdKind,
+			Spec: ruletypes.BasicRuleThresholds{
+				{
+					Name:            postableRule.AlertName,
+					TargetValue:     &c.target,
+					TargetUnit:      c.targetUnit,
+					MatchType:       c.matchType,
+					CompareOperator: c.compareOperator,
+				},
+			},
+		}
+		postableRule.Annotations = map[string]string{
+			"description": "This alert is fired when the defined metric (current value: {{$value}}) crosses the threshold ({{$threshold}})",
+			"summary":     "The rule threshold is set to {{$threshold}}, and the observed metric value is {{$value}}",
+		}
+
+		externalURL := mustParseURL(t, "http://localhost:8080")
+		rule, err := NewThresholdRule("69", valuer.GenerateUUID(), &postableRule, querier, logger, externalURL)
+		require.NoError(t, err, "case %d", idx)
+
+		alertsFound, err := rule.Eval(context.Background(), time.Now())
+		require.NoError(t, err, "case %d", idx)
+
+		assert.Equal(t, c.expectAlerts, alertsFound, "case %d", idx)
+		for _, item := range rule.Active {
+			link := item.Annotations.Map()[ruletypes.AnnotationRelatedTraces]
+			assert.True(t, strings.HasPrefix(link, "http://localhost:8080/ai-observability/explorer?"), "case %d: %s", idx, link)
+			assert.Contains(t, link, "builder_ai_query", "case %d", idx)
+			assert.Contains(t, link, "llm-gateway", "case %d", idx)
+		}
+	}
+}
+
 func TestThresholdRuleLogsLink(t *testing.T) {
 	postableRule := ruletypes.PostableRule{
 		AlertName: "Logs link test",

pkg/types/rulestatehistorytypes/response.go

@@ -23,15 +23,17 @@ type GettableRuleStateHistory struct {
 	Fingerprint         uint64               `json:"fingerprint" required:"true"`
 	Value               float64              `json:"value" required:"true"`
 	RelatedTracesLink   string               `json:"relatedTracesLink,omitempty"`
+	RelatedAITracesLink string               `json:"relatedAITracesLink,omitempty"`
 	RelatedLogsLink     string               `json:"relatedLogsLink,omitempty"`
 }
 
 type GettableRuleStateHistoryContributor struct {
-	Fingerprint       uint64           `json:"fingerprint" required:"true"`
-	Labels            []*qbtypes.Label `json:"labels" required:"true"`
-	Count             uint64           `json:"count" required:"true"`
-	RelatedTracesLink string           `json:"relatedTracesLink,omitempty"`
-	RelatedLogsLink   string           `json:"relatedLogsLink,omitempty"`
+	Fingerprint         uint64           `json:"fingerprint" required:"true"`
+	Labels              []*qbtypes.Label `json:"labels" required:"true"`
+	Count               uint64           `json:"count" required:"true"`
+	RelatedTracesLink   string           `json:"relatedTracesLink,omitempty"`
+	RelatedAITracesLink string           `json:"relatedAITracesLink,omitempty"`
+	RelatedLogsLink     string           `json:"relatedLogsLink,omitempty"`
 }
 
 type GettableRuleStateWindow struct {

pkg/types/rulestatehistorytypes/store.go

@@ -77,16 +77,23 @@ type RuleStateHistory struct {
 	Fingerprint  uint64               `ch:"fingerprint"`
 	Value        float64              `ch:"value"`
 
-	RelatedTracesLink string
-	RelatedLogsLink   string
+	RelatedLinks
 }
 
 type RuleStateHistoryContributor struct {
-	Fingerprint       uint64       `ch:"fingerprint"`
-	Labels            LabelsString `ch:"labels"`
-	Count             uint64       `ch:"count"`
-	RelatedTracesLink string
-	RelatedLogsLink   string
+	Fingerprint uint64       `ch:"fingerprint"`
+	Labels      LabelsString `ch:"labels"`
+	Count       uint64       `ch:"count"`
+
+	RelatedLinks
+}
+
+// RelatedLinks holds the encoded explorer query params for a history entry;
+// at most one field is non-empty.
+type RelatedLinks struct {
+	RelatedTracesLink   string
+	RelatedAITracesLink string
+	RelatedLogsLink     string
 }
 
 type Store interface {

pkg/types/ruletypes/api_params.go

@@ -24,6 +24,7 @@ const (
 	AlertTypeTraces     AlertType = "TRACES_BASED_ALERT"
 	AlertTypeLogs       AlertType = "LOGS_BASED_ALERT"
 	AlertTypeExceptions AlertType = "EXCEPTIONS_BASED_ALERT"
+	AlertTypeAITraces   AlertType = "AI_TRACES_BASED_ALERT"
 )
 
 // Enum implements jsonschema.Enum; returns the acceptable values for AlertType.
@@ -33,9 +34,19 @@ func (AlertType) Enum() []any {
 		AlertTypeTraces,
 		AlertTypeLogs,
 		AlertTypeExceptions,
+		AlertTypeAITraces,
 	}
 }
 
+// BuilderQueryType returns the query type the alert type's builder queries
+// carry; only AI trace alerts use builder_ai_query.
+func (t AlertType) BuilderQueryType() qbtypes.QueryType {
+	if t == AlertTypeAITraces {
+		return qbtypes.QueryTypeBuilderAI
+	}
+	return qbtypes.QueryTypeBuilder
+}
+
 const (
 	DefaultSchemaVersion  = "v1"
 	SchemaVersionV2Alpha1 = "v2alpha1"
@@ -406,11 +417,11 @@ func (r *PostableRule) Validate() error {
 
 	if r.AlertType != "" {
 		switch r.AlertType {
-		case AlertTypeMetric, AlertTypeTraces, AlertTypeLogs, AlertTypeExceptions:
+		case AlertTypeMetric, AlertTypeTraces, AlertTypeLogs, AlertTypeExceptions, AlertTypeAITraces:
 		default:
 			errs = append(errs, errors.NewInvalidInputf(errors.CodeInvalidInput,
-				"alertType: unsupported value %q; must be one of %q, %q, %q, %q",
-				r.AlertType, AlertTypeMetric, AlertTypeTraces, AlertTypeLogs, AlertTypeExceptions))
+				"alertType: unsupported value %q; must be one of %q, %q, %q, %q, %q",
+				r.AlertType, AlertTypeMetric, AlertTypeTraces, AlertTypeLogs, AlertTypeExceptions, AlertTypeAITraces))
 		}
 	}
 

pkg/types/ruletypes/validate_test.go

@@ -209,6 +209,10 @@ func TestValidate_PostableRule_Common(t *testing.T) {
 			name: "valid alertType EXCEPTIONS_BASED_ALERT",
 			json: patchJSON(validV1Builder(), `{"alertType": "EXCEPTIONS_BASED_ALERT"}`),
 		},
+		{
+			name: "valid alertType AI_TRACES_BASED_ALERT",
+			json: patchJSON(validV1Builder(), `{"alertType": "AI_TRACES_BASED_ALERT"}`),
+		},
 		{
 			name: "empty alertType is ok (optional)",
 			json: removeField(validV1Builder(), "alertType"),

tests/fixtures/queriercommon.py

@@ -1,4 +1,4 @@
-"""Seed data for the queriercommon keyless-semantics and explicit-context tests.
+"""Seed data for the queriercommon keyless-semantics tests.
 
 Three identities exist in every signal. GOLD and SILVER carry the test keys.
 NONE carries no key at all. The tests assert which identities a filter
@@ -8,7 +8,6 @@ The attribute names are outside every semantic-convention family, so the
 seeded data pins base behavior with any semconv overlay state.
 """
 
-import json
 from collections.abc import Callable, Generator
 from datetime import UTC, datetime, timedelta
 
@@ -123,98 +122,3 @@ def keyless_series(insert_metrics: Callable[[list[Metrics]], None]) -> Generator
         ]
     )
     yield start, start + points * 60
-
-
-EXPLICIT_PREFIX = "explicit-ctx"
-# Unambiguous string attribute that names the row. Every assertion reads it back.
-IDENTITY_KEY = "probe.id"
-# Attribute-only key with no same-named column, for the own-context miss. On
-# logs the rows that lack the attribute carry it nested in the body JSON.
-ATTRIBUTE_ONLY_KEY = "route.tag"
-CONTESTED_VALUE = "checkout"
-
-# Row identities, by where the contested name carries the contested value:
-# the intrinsic column (`name` on spans, `severity_text` on logs), the
-# same-named string attribute, both, neither, or a same-named number
-# attribute (a data type that contradicts the column).
-COLUMN_ONLY = f"{EXPLICIT_PREFIX}-column"
-ATTRIBUTE_ONLY = f"{EXPLICIT_PREFIX}-attribute"
-BOTH = f"{EXPLICIT_PREFIX}-both"
-NEITHER = f"{EXPLICIT_PREFIX}-neither"
-NUMBER_ATTRIBUTE = f"{EXPLICIT_PREFIX}-number"
-NUMBER_VALUE = 42
-
-# (identity, column carries the value, attribute carries the value,
-#  attribute carries the number, resource service.name, attribute service.name,
-#  carries route.tag, insert offset in seconds)
-ROWS = [
-    (COLUMN_ONLY, True, False, False, "svc-a", None, True, 1),
-    (ATTRIBUTE_ONLY, False, True, False, "svc-b", "svc-a", False, 2),
-    (BOTH, True, True, False, "svc-a", "svc-a", True, 3),
-    (NEITHER, False, False, False, "svc-b", "svc-b", False, 4),
-    (NUMBER_ATTRIBUTE, False, False, True, "svc-b", None, False, 5),
-]
-
-# Logs only: the declared scope path `scope.name` next to a scope attribute
-# that is also named `name`, and a plain scope attribute.
-SCOPE_NAME = "scope-a"
-SCOPE_ATTRIBUTE_KEY = "env"
-SCOPE_ATTRIBUTE_VALUE = "prod"
-
-
-@pytest.fixture(name="ambiguous_rows", scope="function")
-def ambiguous_rows(
-    insert_logs: Callable[[list[Logs]], None],
-    insert_traces: Callable[[list[Traces]], None],
-) -> Generator[datetime]:
-    """One span and one log per identity. `service.name` exists as a resource
-    attribute on every row and as a span or log attribute on some, with
-    different values, so a bare `service.name` is ambiguous. Logs that lack
-    the `route.tag` attribute carry it in the body JSON instead. Logs with
-    the column value carry the scope name; logs with the attribute value
-    carry the scope attributes. Yields the base timestamp."""
-    now = datetime.now(tz=UTC).replace(microsecond=0) - timedelta(minutes=1)
-
-    insert_traces(
-        [
-            Traces(
-                timestamp=now - timedelta(seconds=offset),
-                duration=timedelta(milliseconds=10),
-                trace_id=TraceIdGenerator.trace_id(),
-                span_id=TraceIdGenerator.span_id(),
-                name=CONTESTED_VALUE if column else "other",
-                kind=TracesKind.SPAN_KIND_SERVER,
-                status_code=TracesStatusCode.STATUS_CODE_OK,
-                resources={"service.name": resource_service},
-                attributes={
-                    IDENTITY_KEY: identity,
-                    **({"name": CONTESTED_VALUE} if attribute else {}),
-                    **({"name": NUMBER_VALUE} if number else {}),
-                    **({"service.name": attribute_service} if attribute_service else {}),
-                    **({ATTRIBUTE_ONLY_KEY: CONTESTED_VALUE} if tagged else {}),
-                },
-            )
-            for identity, column, attribute, number, resource_service, attribute_service, tagged, offset in ROWS
-        ]
-    )
-    insert_logs(
-        [
-            Logs(
-                timestamp=now - timedelta(seconds=offset),
-                body=json.dumps({} if tagged else {"route": {"tag": CONTESTED_VALUE}}),
-                severity_text="ERROR" if column else "INFO",
-                scope_name=SCOPE_NAME if column else "",
-                scope_attributes={"name": CONTESTED_VALUE, SCOPE_ATTRIBUTE_KEY: SCOPE_ATTRIBUTE_VALUE} if attribute else {},
-                resources={"service.name": resource_service},
-                attributes={
-                    IDENTITY_KEY: identity,
-                    **({"severity_text": "ERROR"} if attribute else {}),
-                    **({"severity_text": NUMBER_VALUE} if number else {}),
-                    **({"service.name": attribute_service} if attribute_service else {}),
-                    **({ATTRIBUTE_ONLY_KEY: CONTESTED_VALUE} if tagged else {}),
-                },
-            )
-            for identity, column, attribute, number, resource_service, attribute_service, tagged, offset in ROWS
-        ]
-    )
-    yield now

tests/integration/testdata/alerts/test_scenarios/rule_state_history_ai_traces/alert_data.jsonl

@@ -0,0 +1,16 @@
+{"timestamp": "2026-01-29T10:00:00.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f601", "span_id": "c1b2c3d4e5f6a701", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:00:00.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f601", "span_id": "d1b2c3d4e5f6a701", "parent_span_id": "c1b2c3d4e5f6a701", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-0", "gen_ai.usage.input_tokens": 300, "gen_ai.usage.output_tokens": 120, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:00:30.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f602", "span_id": "c1b2c3d4e5f6a702", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:00:30.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f602", "span_id": "d1b2c3d4e5f6a702", "parent_span_id": "c1b2c3d4e5f6a702", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-1", "gen_ai.usage.input_tokens": 310, "gen_ai.usage.output_tokens": 125, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:01:00.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f603", "span_id": "c1b2c3d4e5f6a703", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:01:00.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f603", "span_id": "d1b2c3d4e5f6a703", "parent_span_id": "c1b2c3d4e5f6a703", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-0", "gen_ai.usage.input_tokens": 320, "gen_ai.usage.output_tokens": 130, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:01:30.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f604", "span_id": "c1b2c3d4e5f6a704", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:01:30.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f604", "span_id": "d1b2c3d4e5f6a704", "parent_span_id": "c1b2c3d4e5f6a704", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-1", "gen_ai.usage.input_tokens": 330, "gen_ai.usage.output_tokens": 135, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:02:00.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f605", "span_id": "c1b2c3d4e5f6a705", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:02:00.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f605", "span_id": "d1b2c3d4e5f6a705", "parent_span_id": "c1b2c3d4e5f6a705", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-0", "gen_ai.usage.input_tokens": 340, "gen_ai.usage.output_tokens": 140, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:02:30.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f606", "span_id": "c1b2c3d4e5f6a706", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:02:30.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f606", "span_id": "d1b2c3d4e5f6a706", "parent_span_id": "c1b2c3d4e5f6a706", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-1", "gen_ai.usage.input_tokens": 350, "gen_ai.usage.output_tokens": 145, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:03:00.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f607", "span_id": "c1b2c3d4e5f6a707", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:03:00.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f607", "span_id": "d1b2c3d4e5f6a707", "parent_span_id": "c1b2c3d4e5f6a707", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-0", "gen_ai.usage.input_tokens": 360, "gen_ai.usage.output_tokens": 150, "_signoz.gen_ai.total_cost": 0.02}}
+{"timestamp": "2026-01-29T10:03:30.000000Z", "duration": "PT2.5S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f608", "span_id": "c1b2c3d4e5f6a708", "parent_span_id": "", "name": "POST /chat", "kind": 2, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"http.request.method": "POST", "http.response.status_code": "200", "http.request.path": "/chat"}}
+{"timestamp": "2026-01-29T10:03:30.200000Z", "duration": "PT2S", "trace_id": "7a1f6d3d6b0a1f9e8a71b2c3d4e5f608", "span_id": "d1b2c3d4e5f6a708", "parent_span_id": "c1b2c3d4e5f6a708", "name": "chat gpt-4o-mini", "kind": 3, "status_code": 1, "status_message": "", "resources": {"deployment.environment": "production", "service.name": "llm-gateway", "os.type": "linux", "host.name": "linux-000"}, "attributes": {"gen_ai.system": "openai", "gen_ai.request.model": "gpt-4o-mini", "gen_ai.user.id": "user-1", "gen_ai.usage.input_tokens": 370, "gen_ai.usage.output_tokens": 155, "_signoz.gen_ai.total_cost": 0.02}}

tests/integration/testdata/alerts/test_scenarios/rule_state_history_ai_traces/rule.json

@@ -0,0 +1,73 @@
+{
+  "alert": "rule_state_history_ai_traces",
+  "ruleType": "threshold_rule",
+  "alertType": "AI_TRACES_BASED_ALERT",
+  "condition": {
+    "thresholds": {
+      "kind": "basic",
+      "spec": [
+        {
+          "name": "critical",
+          "target": 0,
+          "matchType": "at_least_once",
+          "op": "above",
+          "channels": [
+            "test channel"
+          ]
+        }
+      ]
+    },
+    "compositeQuery": {
+      "queryType": "builder",
+      "panelType": "graph",
+      "queries": [
+        {
+          "type": "builder_ai_query",
+          "spec": {
+            "name": "A",
+            "signal": "traces",
+            "filter": {
+              "expression": "trace.input_tokens > 100"
+            },
+            "groupBy": [
+              {
+                "name": "service.name",
+                "fieldContext": "resource",
+                "fieldDataType": "string"
+              }
+            ],
+            "aggregations": [
+              {
+                "expression": "max(trace.total_tokens)"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    "selectedQueryName": "A"
+  },
+  "evaluation": {
+    "kind": "rolling",
+    "spec": {
+      "evalWindow": "5m0s",
+      "frequency": "15s"
+    }
+  },
+  "labels": {},
+  "annotations": {
+    "description": "This alert is fired when the defined metric (current value: {{$value}}) crosses the threshold ({{$threshold}})",
+    "summary": "This alert is fired when the defined metric (current value: {{$value}}) crosses the threshold ({{$threshold}})"
+  },
+  "notificationSettings": {
+    "groupBy": [],
+    "usePolicy": false,
+    "renotify": {
+      "enabled": false,
+      "interval": "30m",
+      "alertStates": []
+    }
+  },
+  "version": "v5",
+  "schemaVersion": "v2alpha1"
+}

tests/integration/tests/alerts/03_rule_state_history.py

@@ -38,6 +38,7 @@ def test_logs_rule_history_related_links(
 
     assert labels_to_map(item["labels"]).get("service.name") == "payment-service"
     assert item.get("relatedTracesLink", "") == ""
+    assert item.get("relatedAITracesLink", "") == ""
     assert item.get("relatedLogsLink", "") != ""
 
     # logs explorer links carry the time range in milliseconds, anchored to the
@@ -52,6 +53,7 @@ def test_logs_rule_history_related_links(
     assert len(contributors) == 1
     assert contributors[0]["count"] >= 1
     assert contributors[0].get("relatedTracesLink", "") == ""
+    assert contributors[0].get("relatedAITracesLink", "") == ""
     assert contributors[0].get("relatedLogsLink", "") != ""
 
     # contributor counts aggregate the whole queried range, so their links span it
@@ -80,6 +82,7 @@ def test_traces_rule_history_related_links(
 
     assert labels_to_map(item["labels"]).get("service.name") == "order-service"
     assert item.get("relatedLogsLink", "") == ""
+    assert item.get("relatedAITracesLink", "") == ""
     assert item.get("relatedTracesLink", "") != ""
 
     # traces explorer links carry the time range in nanoseconds, anchored to the
@@ -94,6 +97,7 @@ def test_traces_rule_history_related_links(
     assert len(contributors) == 1
     assert contributors[0]["count"] >= 1
     assert contributors[0].get("relatedLogsLink", "") == ""
+    assert contributors[0].get("relatedAITracesLink", "") == ""
     assert contributors[0].get("relatedTracesLink", "") != ""
 
     # contributor counts aggregate the whole queried range, so their links span it
@@ -101,3 +105,49 @@ def test_traces_rule_history_related_links(
     assert contributor_link["start"] == query_start_ms * 1_000_000
     assert contributor_link["end"] == query_end_ms * 1_000_000
     assert_related_link_query(contributor_link, "traces", ["http.request.path", "/order", "service.name", "order-service"])
+
+
+def test_ai_traces_rule_history_related_links(
+    signoz: types.SigNoz,
+    create_alert_rule_with_channel: Callable[[str], str],
+    insert_alert_data: Callable[[list[types.AlertData], datetime], None],
+    get_token: Callable[[str, str], str],
+):
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    query_start_ms = int((datetime.now(tz=UTC) - timedelta(minutes=30)).timestamp() * 1000)
+
+    insert_alert_data(
+        [types.AlertData(type="traces", data_path="alerts/test_scenarios/rule_state_history_ai_traces/alert_data.jsonl")],
+        base_time=datetime.now(tz=UTC) - timedelta(minutes=5),
+    )
+    rule_id = create_alert_rule_with_channel("alerts/test_scenarios/rule_state_history_ai_traces/rule.json")
+
+    (item, query_end_ms) = wait_for_firing_timeline_entry(signoz, token, rule_id, query_start_ms)
+
+    assert labels_to_map(item["labels"]).get("service.name") == "llm-gateway"
+    assert item.get("relatedLogsLink", "") == ""
+    assert item.get("relatedTracesLink", "") == ""
+    assert item.get("relatedAITracesLink", "") != ""
+
+    # AI alert links follow the traces explorer shape: a nanosecond range
+    # anchored to the second-truncated entry timestamp
+    link = parse_related_link(item["relatedAITracesLink"])
+    assert link["end"] == (item["unixMilli"] // 1000) * 1_000_000_000
+    assert link["end"] - link["start"] == RELATED_LINK_WINDOW_SECONDS * 1_000_000_000
+    assert_related_link_query(link, "traces", ["trace.input_tokens", "100", "service.name", "llm-gateway"])
+    # the AI explorer only resolves trace.* fields for builder_ai_query
+    assert link["composite_query"]["builder"]["queryData"][0]["builderQueryType"] == "builder_ai_query"
+
+    contributors = get_rule_history_top_contributors(signoz, token, rule_id, query_start_ms, query_end_ms)
+    contributors = [c for c in contributors if labels_to_map(c["labels"]).get("service.name") == "llm-gateway"]
+    assert len(contributors) == 1
+    assert contributors[0]["count"] >= 1
+    assert contributors[0].get("relatedLogsLink", "") == ""
+    assert contributors[0].get("relatedTracesLink", "") == ""
+    assert contributors[0].get("relatedAITracesLink", "") != ""
+
+    contributor_link = parse_related_link(contributors[0]["relatedAITracesLink"])
+    assert contributor_link["start"] == query_start_ms * 1_000_000
+    assert contributor_link["end"] == query_end_ms * 1_000_000
+    assert_related_link_query(contributor_link, "traces", ["trace.input_tokens", "100", "service.name", "llm-gateway"])
+    assert contributor_link["composite_query"]["builder"]["queryData"][0]["builderQueryType"] == "builder_ai_query"

tests/integration/tests/queriercommon/07_explicit_context.py

@@ -1,371 +0,0 @@
-from collections.abc import Callable
-from datetime import datetime, timedelta
-from http import HTTPStatus
-
-import pytest
-
-from fixtures import types
-from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
-from fixtures.querier import (
-    RequestType,
-    assert_scalar_value,
-    build_aggregation,
-    build_group_by_field,
-    build_order_by,
-    build_raw_query,
-    build_scalar_query,
-    get_all_warnings,
-    get_column_data_from_response,
-    get_scalar_table_data,
-    make_query_request,
-)
-from fixtures.queriercommon import (
-    ATTRIBUTE_ONLY,
-    BOTH,
-    COLUMN_ONLY,
-    EXPLICIT_PREFIX,
-    IDENTITY_KEY,
-    NEITHER,
-    NUMBER_ATTRIBUTE,
-)
-
-# Which rows a filter returns when the same name exists as an intrinsic
-# column and as an attribute (`name` on spans, `severity_text` on logs), or
-# as a resource attribute and a span or log attribute (`service.name`).
-# An explicit context is honored as written. A bare name that is both a
-# column and an attribute reads both, with an ambiguity warning. A bare name
-# that is both a resource and an attribute reads the resource, with a
-# warning. The warning also fires for an explicit attribute context when the
-# attribute exists in two data types, and a string operand reaches the
-# number attribute through a text cast. A key under the signal's own context
-# that exists only as an attribute corrects to the attribute; on logs the
-# correction also reads the body JSON path.
-FILTER_MATRIX = [
-    pytest.param("{contested} = '{value}'", {COLUMN_ONLY, ATTRIBUTE_ONLY, BOTH}, True, id="bare_column_and_attribute"),
-    pytest.param("{own}.{contested} = '{value}'", {COLUMN_ONLY, BOTH}, False, id="own_context_column_only"),
-    pytest.param("attribute.{contested} = '{value}'", {ATTRIBUTE_ONLY, BOTH}, True, id="attribute_context_warns_about_two_types"),
-    pytest.param("{contested} != '{value}'", {NEITHER, NUMBER_ATTRIBUTE}, True, id="bare_negative_excludes_every_carrier"),
-    pytest.param("{contested} EXISTS", {COLUMN_ONLY, ATTRIBUTE_ONLY, BOTH, NEITHER, NUMBER_ATTRIBUTE}, True, id="bare_exists_is_the_column"),
-    pytest.param("{contested} NOT EXISTS", set(), True, id="bare_not_exists_is_never"),
-    pytest.param("attribute.{contested} EXISTS", {ATTRIBUTE_ONLY, BOTH, NUMBER_ATTRIBUTE}, True, id="attribute_exists_spans_both_types"),
-    pytest.param("attribute.{contested} NOT EXISTS", {COLUMN_ONLY, NEITHER}, True, id="attribute_not_exists"),
-    pytest.param("{contested} = '42'", {NUMBER_ATTRIBUTE}, True, id="bare_string_operand_reaches_the_number_attribute"),
-    pytest.param("attribute.{contested}:string = '{value}'", {ATTRIBUTE_ONLY, BOTH}, False, id="type_suffix_selects_the_string_attribute"),
-    pytest.param("attribute.{contested}:float64 = 42", {NUMBER_ATTRIBUTE}, False, id="type_suffix_selects_the_number_attribute"),
-    pytest.param("service.name = 'svc-a'", {COLUMN_ONLY, BOTH}, True, id="bare_resource_wins_with_warning"),
-    pytest.param("service.name != 'svc-a'", {ATTRIBUTE_ONLY, NEITHER, NUMBER_ATTRIBUTE}, True, id="bare_resource_negative"),
-    pytest.param("resource.service.name = 'svc-a'", {COLUMN_ONLY, BOTH}, False, id="resource_context_no_warning"),
-    pytest.param("resource.service.name != 'svc-a'", {ATTRIBUTE_ONLY, NEITHER, NUMBER_ATTRIBUTE}, False, id="resource_context_negative"),
-    pytest.param("attribute.service.name = 'svc-a'", {ATTRIBUTE_ONLY, BOTH}, False, id="attribute_context_no_warning"),
-    pytest.param(
-        "{own}.route.tag = 'checkout'",
-        {"traces": {COLUMN_ONLY, BOTH}, "logs": {COLUMN_ONLY, ATTRIBUTE_ONLY, BOTH, NEITHER, NUMBER_ATTRIBUTE}},
-        False,
-        id="own_context_miss_corrects_to_attribute_and_on_logs_to_body",
-    ),
-    pytest.param("route.tag = 'checkout'", {COLUMN_ONLY, BOTH}, False, id="bare_attribute_only_key"),
-]
-
-SIGNALS = [
-    pytest.param("traces", "span", "name", "checkout", "other", id="traces"),
-    pytest.param("logs", "log", "severity_text", "ERROR", "INFO", id="logs"),
-]
-
-
-@pytest.mark.parametrize("expression_template,expected,expects_ambiguity_warning", FILTER_MATRIX)
-@pytest.mark.parametrize("signal,own_context,contested,value,other_value", SIGNALS)
-def test_filter_resolution(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    signal: str,
-    own_context: str,
-    contested: str,
-    value: str,
-    other_value: str,  # pylint: disable=unused-argument
-    expression_template: str,
-    expected: set[str] | dict[str, set[str]],
-    expects_ambiguity_warning: bool,
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-    expression = expression_template.format(own=own_context, contested=contested, value=value)
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.RAW,
-        queries=[
-            build_raw_query(
-                "A",
-                signal,
-                limit=100,
-                filter_expression=expression,
-                order=[build_order_by("timestamp", "asc")],
-                select_fields=[{"name": IDENTITY_KEY}],
-            )
-        ],
-    )
-    assert response.status_code == HTTPStatus.OK, response.text
-
-    matched = {row for row in get_column_data_from_response(response.json(), IDENTITY_KEY) if row.startswith(EXPLICIT_PREFIX)}
-    assert matched == (expected[signal] if isinstance(expected, dict) else expected), expression
-
-    warnings = [w["message"] for w in get_all_warnings(response.json())]
-    assert any("ambiguous" in w for w in warnings) == expects_ambiguity_warning, warnings
-
-
-# Group by resolves the contested name in the column stage: a bare name that
-# is both a column and an attribute groups by the column alone, an explicit
-# context groups by that context alone.
-GROUP_BY_MATRIX = [
-    pytest.param(None, {"{value}": 2, "{other}": 3}, id="bare_groups_by_the_column"),
-    pytest.param("own", {"{value}": 2, "{other}": 3}, id="own_context_groups_by_the_column"),
-    pytest.param("attribute", {"{value}": 2}, id="attribute_context_groups_by_the_attribute"),
-]
-
-
-@pytest.mark.parametrize("context,expected_template", GROUP_BY_MATRIX)
-@pytest.mark.parametrize("signal,own_context,contested,value,other_value", SIGNALS)
-def test_group_by_resolution(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    signal: str,
-    own_context: str,
-    contested: str,
-    value: str,
-    other_value: str,
-    context: str | None,
-    expected_template: dict[str, int],
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-    field_context = own_context if context == "own" else context
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.SCALAR,
-        queries=[
-            build_scalar_query(
-                "A",
-                signal,
-                [build_aggregation("count()", "rows")],
-                group_by=[build_group_by_field(contested, "string", field_context) if field_context else {"name": contested}],
-                filter_expression=f"{IDENTITY_KEY} LIKE '{EXPLICIT_PREFIX}%'",
-            )
-        ],
-    )
-    assert response.status_code == HTTPStatus.OK, response.text
-
-    expected = {key.format(value=value, other=other_value): count for key, count in expected_template.items()}
-    groups = {row[0]: row[1] for row in get_scalar_table_data(response.json()) if row[0] in expected}
-    assert groups == expected, get_scalar_table_data(response.json())
-
-
-# A raw select of a bare name that is both a resource and an attribute reads
-# one value per row: the resource value, also on the row whose attribute
-# carries a different value.
-@pytest.mark.parametrize("signal", ["traces", "logs"])
-def test_select_of_ambiguous_name(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    signal: str,
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.RAW,
-        queries=[
-            build_raw_query(
-                "A",
-                signal,
-                limit=100,
-                filter_expression=f"{IDENTITY_KEY} LIKE '{EXPLICIT_PREFIX}%'",
-                order=[build_order_by("timestamp", "asc")],
-                select_fields=[{"name": IDENTITY_KEY}, {"name": "service.name"}],
-            )
-        ],
-    )
-    assert response.status_code == HTTPStatus.OK, response.text
-
-    rows = response.json()["data"]["data"]["results"][0]["rows"] or []
-    by_identity = {row["data"][IDENTITY_KEY]: row["data"]["service.name"] for row in rows if row["data"].get(IDENTITY_KEY, "").startswith(EXPLICIT_PREFIX)}
-    assert by_identity == {
-        COLUMN_ONLY: "svc-a",
-        ATTRIBUTE_ONLY: "svc-b",
-        BOTH: "svc-a",
-        NEITHER: "svc-b",
-        NUMBER_ATTRIBUTE: "svc-b",
-    }
-
-
-# Order by resolves the contested name in the column stage, descending, with
-# the timestamp descending as the tie breaker. A bare or own-context name
-# sorts by the column alone. An explicit attribute context sorts by the
-# attribute on traces, where the number attribute reads as text and rows
-# without the attribute come last; on logs it still sorts by the column.
-BY_COLUMN = [ATTRIBUTE_ONLY, NEITHER, NUMBER_ATTRIBUTE, COLUMN_ONLY, BOTH]
-ORDER_BY_MATRIX = [
-    pytest.param(None, {"traces": BY_COLUMN, "logs": BY_COLUMN}, id="bare_orders_by_the_column"),
-    pytest.param("own", {"traces": BY_COLUMN, "logs": BY_COLUMN}, id="own_context_orders_by_the_column"),
-    pytest.param(
-        "attribute",
-        {"traces": [ATTRIBUTE_ONLY, BOTH, NUMBER_ATTRIBUTE, COLUMN_ONLY, NEITHER], "logs": BY_COLUMN},
-        id="attribute_context_orders_by_the_attribute_on_traces_only",
-    ),
-]
-
-
-@pytest.mark.parametrize("context,expected", ORDER_BY_MATRIX)
-@pytest.mark.parametrize("signal,own_context,contested,value,other_value", SIGNALS)
-def test_order_by_resolution(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    signal: str,
-    own_context: str,
-    contested: str,
-    value: str,  # pylint: disable=unused-argument
-    other_value: str,  # pylint: disable=unused-argument
-    context: str | None,
-    expected: dict[str, list[str]],
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-    prefix = f"{own_context}." if context == "own" else f"{context}." if context else ""
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.RAW,
-        queries=[
-            build_raw_query(
-                "A",
-                signal,
-                limit=100,
-                filter_expression=f"{IDENTITY_KEY} LIKE '{EXPLICIT_PREFIX}%'",
-                order=[build_order_by(f"{prefix}{contested}", "desc"), build_order_by("timestamp", "desc")],
-                select_fields=[{"name": IDENTITY_KEY}],
-            )
-        ],
-    )
-    assert response.status_code == HTTPStatus.OK, response.text
-
-    ordered = [row for row in get_column_data_from_response(response.json(), IDENTITY_KEY) if row.startswith(EXPLICIT_PREFIX)]
-    assert ordered == expected[signal]
-
-
-# An aggregation argument resolves the contested name in the column stage: a
-# bare name counts the column's values alone; an attribute context counts the
-# attribute in both of its data types, so the number attribute adds a
-# distinct value.
-AGGREGATION_MATRIX = [
-    pytest.param(None, 2, id="bare_counts_the_column"),
-    pytest.param("own", 2, id="own_context_counts_the_column"),
-    pytest.param("attribute", 2, id="attribute_context_counts_both_attribute_types"),
-]
-
-
-@pytest.mark.parametrize("context,expected", AGGREGATION_MATRIX)
-@pytest.mark.parametrize("signal,own_context,contested,value,other_value", SIGNALS)
-def test_aggregation_argument_resolution(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    signal: str,
-    own_context: str,
-    contested: str,
-    value: str,  # pylint: disable=unused-argument
-    other_value: str,  # pylint: disable=unused-argument
-    context: str | None,
-    expected: int,
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-    prefix = f"{own_context}." if context == "own" else f"{context}." if context else ""
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.SCALAR,
-        queries=[
-            build_scalar_query(
-                "A",
-                signal,
-                [build_aggregation(f"count_distinct({prefix}{contested})", "distinct")],
-                filter_expression=f"{IDENTITY_KEY} LIKE '{EXPLICIT_PREFIX}%'",
-            )
-        ],
-    )
-    assert response.status_code == HTTPStatus.OK, response.text
-    assert_scalar_value(response, "A", expected)
-
-
-# Logs only. `body.x` addresses the body JSON and never the same-named
-# attribute; `log.x` reads the attribute and the body JSON path together,
-# even when the attribute exists in metadata. A `scope.` key is a strict
-# context resolved through metadata alone: the declared scope path
-# `scope.name` and a scope attribute both answer "key not found" when
-# metadata does not report them, even when the rows carry them.
-LOGS_ONLY_MATRIX = [
-    pytest.param("body.route.tag = 'checkout'", {ATTRIBUTE_ONLY, NEITHER, NUMBER_ATTRIBUTE}, id="body_context_reads_the_body_json"),
-    pytest.param("log.route.tag = 'checkout'", {COLUMN_ONLY, ATTRIBUTE_ONLY, BOTH, NEITHER, NUMBER_ATTRIBUTE}, id="log_context_reads_attribute_and_body"),
-    pytest.param("scope.name = 'scope-a'", "key `name` not found", id="scope_name_needs_metadata"),
-    pytest.param("scope.env = 'prod'", "key `env` not found", id="scope_attribute_needs_metadata"),
-    pytest.param("scope.env EXISTS", "key `env` not found", id="scope_attribute_exists_needs_metadata"),
-]
-
-
-@pytest.mark.parametrize("expression,expected", LOGS_ONLY_MATRIX)
-def test_logs_body_and_scope_contexts(
-    signoz: types.SigNoz,
-    create_user_admin: None,  # pylint: disable=unused-argument
-    get_token: Callable[[str, str], str],
-    ambiguous_rows: datetime,
-    expression: str,
-    expected: set[str] | str,
-) -> None:
-    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
-
-    response = make_query_request(
-        signoz,
-        token,
-        start_ms=int((ambiguous_rows - timedelta(minutes=2)).timestamp() * 1000),
-        end_ms=int((ambiguous_rows + timedelta(minutes=1)).timestamp() * 1000),
-        request_type=RequestType.RAW,
-        queries=[
-            build_raw_query(
-                "A",
-                "logs",
-                limit=100,
-                filter_expression=expression,
-                order=[build_order_by("timestamp", "asc")],
-                select_fields=[{"name": IDENTITY_KEY}],
-            )
-        ],
-    )
-
-    if isinstance(expected, str):
-        assert response.status_code == HTTPStatus.BAD_REQUEST, response.text
-        assert expected in response.text, response.text
-        return
-
-    assert response.status_code == HTTPStatus.OK, response.text
-    matched = {row for row in get_column_data_from_response(response.json(), IDENTITY_KEY) if row.startswith(EXPLICIT_PREFIX)}
-    assert matched == expected, expression