genai: typed condition fields and source-aware span addressing

[wu-sheng]

Follow-up to #163, from reviewing the OAP implementation in apache/skywalking#13943. No OAP submodule pointer references #163 yet, so these changes carry no client impact.

1. Remove tags and GenAIEvaluationRecordTag

A tags condition exists so callers can filter on key-values the protocol cannot enumerate. This record has none — it persists no user-supplied attribute.

The asymmetry is the tell: Log returns tags: [KeyValue!] and LogQueryCondition filters them, whereas GenAIEvaluationRecord has no tags field at all — so the condition filtered something the API never returns.

In the OAP implementation the accepted key set turns out to be the record's own column names: 11 of 15 are already typed fields on the same condition, and the remaining 4 (operation_name, span_type, evalStringValue, reason) are fixed columns of a record the protocol fully defines. Nothing in the set is custom.

2. Address the span by its source scheme

GenAI evaluation accepts SkyWalking native, OTLP and Zipkin traces. Native span ids are a segment-local int index; OTLP and Zipkin ids are 16 hex characters. spanId: String cannot describe both honestly — and in the implementation it is parsed into an int, which throws for every OTLP/Zipkin span.

GenAITraceRef makes the scheme explicit, and spanIndex is named for what it is: an index, not an identifier, unique only with segmentId.

This stays GenAI-scoped. spanId: Int in trace.graphqls, profile.graphqls and TraceScopeCondition is correctly scoped to native-trace addressing and does not change.

3. Split the value slots

scoreValue (SCORE) / booleanValue (BOOLEAN) / stringValue (STRING, JSON), so valueType genuinely discriminates. BOOLEAN previously shared scoreValue as 0 / 1000000, which meant minScore/maxScore silently spanned both types. value → stringValue for parallel naming; reason stays separate because it is orthogonal and populated for every task.

4. Drop spanType

SpanEvaluationType has exactly one value, LLM_CALL — nothing to query and nothing to display. Reintroduce as an enum if a second span kind appears.

5. Document entity scope and layer

Provider is a service and model is its instance, both Layer.VIRTUAL_GENAI, while serviceId is a normal agent-detected service. Stating this on the fields makes an entity-id mistake visible at review time.

---

Scores remain Long on the 1,000,000 ppm scale, unchanged — SkyWalking does not carry Float/Double in stored or transported values; the convention is Long with the code controlling precision.

OAP-side changes this requires

• getScoreValue() returns the stored Long rather than dividing into a Double
• the Java condition takes Long for minScore/maxScore; the DAOs stop re-scaling an already-scaled input
• booleanValue wired through the condition and all three DAOs
• spanId becomes a String column plus a ref_type column; the Integer.parseInt is removed
• value_type loses storageOnly so it is filterable on Elasticsearch
• QUERYABLE_TAG_KEYS deleted from the ES and JDBC DAOs, and the BanyanDB tag loop with it
• the writer must always set valueType, now non-null

🤖 Generated with Claude Code