Trace model support specify spanId and Trace query support internal debugging. (#13533)

wankai123 · web-flow · commit 0b24362eef38 · 2025-10-01T22:00:36.000+08:00
diff --git a/docs/en/debugging/query-tracing.md b/docs/en/debugging/query-tracing.md
@@ -189,8 +189,7 @@ childSpans:
   |--------------------|---------------------------------------------------------------------------|----------|
   | startTime          | The start time of the query                                               | Yes      |               
   | endTime            | The end time of the query                                                 | Yes      |               
-  | step               | The query step                                                            | Yes      |  
-  | coldStage          | Only for BanyanDB, the flag to query from cold stage, default is false.   | No       | 
+  | step               | The query step                                                            | Yes      |
   | service            | The service name                                                          | Yes      |               
   | serviceLayer       | The service layer name                                                    | No       |               
   | serviceInstance    | The service instance name                                                 | No       |               
@@ -222,13 +221,16 @@ debuggingTrace:
 - URL: HTTP GET `http://{core restHost}:{core restPort}/debugging/query/trace/queryTrace?{parameters}`.
 - Parameters
 
-  | Field             | Description         | Required           |
-  |-------------------|---------------------|--------------------|
-  | traceId           | The ID of the trace | Yes                |
+  | Field           | Description                      | Required        |
+  |-----------------|----------------------------------|-----------------|
+  | traceId         | The ID of the trace              | Yes             |
+  | startTime       | The start time of the query      | Yes             |               
+  | endTime         | The end time of the query        | Yes             |               
+  | step            | The query step                   | Yes             |
 
 - Example
 ```shell
-curl -X GET 'http://127.0.0.1:12800/debugging/query/trace/queryTrace?traceId=8211a1d1-de0f-4485-8766-c88866a8f034'
+curl -X GET 'http://127.0.0.1:12800/debugging/query/trace/queryTrace?traceId=8211a1d1-de0f-4485-8766-c88866a8f034&startTime=2025-09-28&endTime=2025-09-28%200915&step=DAY'
 ```
 
 Response will include query result and the debuggingTrace information, the debuggingTrace information is the same as the MQE query tracing:
@@ -240,19 +242,6 @@ debuggingTrace:
 ...
 ```
 
-#### Tracing SkyWalking API queryTraceFromColdStage
-Only for BanyanDB, can be used to query the trace in the cold stage.
-
-- URL: HTTP GET `http://{core restHost}:{core restPort}/debugging/query/trace/queryTraceFromColdStage?{parameters}`.
-- Parameters
-
-  | Field           | Description                      | Required        |
-  |-----------------|----------------------------------|-----------------|
-  | traceId         | The ID of the trace              | Yes             |
-  | startTime       | The start time of the query      | Yes             |               
-  | endTime         | The end time of the query        | Yes             |               
-  | step            | The query step                   | Yes             |
-
 ### Tracing Zipkin Trace Query
 
 #### Tracing Zipkin API /api/v2/traces
diff --git a/oap-server-bom/pom.xml b/oap-server-bom/pom.xml
@@ -72,7 +72,7 @@
         <httpcore.version>4.4.16</httpcore.version>
         <httpasyncclient.version>4.1.5</httpasyncclient.version>
         <commons-compress.version>1.21</commons-compress.version>
-        <banyandb-java-client.version>0.9.0</banyandb-java-client.version>
+        <banyandb-java-client.version>0.9.1</banyandb-java-client.version>
         <kafka-clients.version>3.4.0</kafka-clients.version>
         <spring-kafka-test.version>2.4.6.RELEASE</spring-kafka-test.version>
         <consul.client.version>1.5.3</consul.client.version>
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/segment/SegmentRecord.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/segment/SegmentRecord.java
@@ -48,6 +48,7 @@
 @SQLDatabase.ExtraColumn4AdditionalEntity(additionalTable = SegmentRecord.ADDITIONAL_TAG_TABLE, parentColumn = TIME_BUCKET)
 @BanyanDB.TimestampColumn(SegmentRecord.START_TIME)
 @BanyanDB.Trace.TraceIdColumn(SegmentRecord.TRACE_ID)
+@BanyanDB.Trace.SpanIdColumn(SegmentRecord.SEGMENT_ID)
 @BanyanDB.Trace.IndexRule(name = SegmentRecord.START_TIME, columns = {
         SegmentRecord.SERVICE_ID,
         SegmentRecord.IS_ERROR,
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/spanattach/SWSpanAttachedEventRecord.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/spanattach/SWSpanAttachedEventRecord.java
@@ -23,6 +23,7 @@
 import lombok.Setter;
 import org.apache.skywalking.oap.server.core.analysis.Stream;
 import org.apache.skywalking.oap.server.core.analysis.manual.segment.SegmentRecord;
+import org.apache.skywalking.oap.server.core.storage.StorageData;
 import org.apache.skywalking.oap.server.core.storage.model.BanyanDBTrace;
 import org.apache.skywalking.oap.server.core.analysis.record.Record;
 import org.apache.skywalking.oap.server.core.analysis.worker.RecordStreamProcessor;
@@ -45,6 +46,7 @@
 @Stream(name = SWSpanAttachedEventRecord.INDEX_NAME, scopeId = SW_SPAN_ATTACHED_EVENT, builder = SWSpanAttachedEventRecord.Builder.class, processor = RecordStreamProcessor.class)
 @BanyanDB.TimestampColumn(SWSpanAttachedEventRecord.TIMESTAMP)
 @BanyanDB.Trace.TraceIdColumn(SWSpanAttachedEventRecord.RELATED_TRACE_ID)
+@BanyanDB.Trace.SpanIdColumn(StorageData.ID)
 @BanyanDB.Group(traceGroup = BanyanDB.TraceGroup.TRACE)
 public class SWSpanAttachedEventRecord extends Record implements BanyanDBTrace, BanyanDBTrace.MergeTable {
 
@@ -133,6 +135,16 @@ public long getTimestampColumnValue() {
         return timestamp;
     }
 
+    @Override
+    public String getMergeSpanIdColumnName() {
+        return SegmentRecord.SEGMENT_ID;
+    }
+
+    @Override
+    public String getSpanIdColumnValue() {
+        return id().build();
+    }
+
     public static class Builder implements StorageBuilder<SWSpanAttachedEventRecord> {
         @Override
         public SWSpanAttachedEventRecord storage2Entity(Convert2Entity converter) {
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/spanattach/SpanAttachedEventRecord.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/manual/spanattach/SpanAttachedEventRecord.java
@@ -25,6 +25,7 @@
 import org.apache.skywalking.oap.server.core.analysis.record.Record;
 import org.apache.skywalking.oap.server.core.analysis.worker.RecordStreamProcessor;
 import org.apache.skywalking.oap.server.core.source.ScopeDeclaration;
+import org.apache.skywalking.oap.server.core.storage.StorageData;
 import org.apache.skywalking.oap.server.core.storage.StorageID;
 import org.apache.skywalking.oap.server.core.storage.annotation.BanyanDB;
 import org.apache.skywalking.oap.server.core.storage.annotation.Column;
@@ -45,6 +46,7 @@
 @Stream(name = SpanAttachedEventRecord.INDEX_NAME, scopeId = SPAN_ATTACHED_EVENT, builder = SpanAttachedEventRecord.Builder.class, processor = RecordStreamProcessor.class)
 @BanyanDB.TimestampColumn(SpanAttachedEventRecord.TIMESTAMP)
 @BanyanDB.Trace.TraceIdColumn(SpanAttachedEventRecord.RELATED_TRACE_ID)
+@BanyanDB.Trace.SpanIdColumn(StorageData.ID)
 @BanyanDB.Group(traceGroup = BanyanDB.TraceGroup.ZIPKIN_TRACE)
 public class SpanAttachedEventRecord extends Record implements BanyanDBTrace, BanyanDBTrace.MergeTable {
 
@@ -131,6 +133,16 @@ public long getTimestampColumnValue() {
         return timestamp;
     }
 
+    @Override
+    public String getMergeSpanIdColumnName() {
+        return ZipkinSpanRecord.SPAN_ID;
+    }
+
+    @Override
+    public String getSpanIdColumnValue() {
+        return id().build();
+    }
+
     public static class Builder implements StorageBuilder<SpanAttachedEventRecord> {
         @Override
         public SpanAttachedEventRecord storage2Entity(Convert2Entity converter) {
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/annotation/BanyanDB.java
@@ -170,6 +170,12 @@ enum IndexType {
             String value();
         }
 
+        @Target({ElementType.TYPE})
+        @Retention(RetentionPolicy.RUNTIME)
+        @interface SpanIdColumn {
+            String value();
+        }
+
         /**
          * IndexRule is used to define a composite index in BanyanDB.
          * Notice, the order of columns is significant, the columns in front have a higher priority
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/BanyanDBModelExtension.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/BanyanDBModelExtension.java
@@ -50,6 +50,16 @@ public class BanyanDBModelExtension {
     @Setter
     private String traceIdColumn;
 
+
+    /**
+     * spanIdColumn is to identify which column in the Trace model is used as the span ID.
+     *
+     * @since 10.3.0
+     */
+    @Getter
+    @Setter
+    private String spanIdColumn;
+
     /**
      * traceIndexRules is to identify which columns in the Trace model are used as the indexRule.
      * BanyanDB Trace model requires at least one traceIndexRules.
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/BanyanDBTrace.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/BanyanDBTrace.java
@@ -34,5 +34,9 @@ interface MergeTable {
         String getMergeTimestampColumnName();
 
         long getTimestampColumnValue();
+
+        String getMergeSpanIdColumnName();
+
+        String getSpanIdColumnValue();
     }
 }
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/StorageModels.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/storage/model/StorageModels.java
@@ -114,6 +114,15 @@ public Model add(Class<?> aClass, int scopeId, Storage storage) throws StorageEx
             banyanDBModelExtension.setTraceIdColumn(traceIdColumn);
         }
 
+        if (aClass.isAnnotationPresent(BanyanDB.Trace.SpanIdColumn.class)) {
+            String spanIdColumn = aClass.getAnnotation(BanyanDB.Trace.SpanIdColumn.class).value();
+            if (StringUtil.isBlank(spanIdColumn)) {
+                throw new IllegalStateException(
+                    "Model[trace." + storage.getModelName() + "] missing defined @BanyanDB.SpanIdColumn");
+            }
+            banyanDBModelExtension.setSpanIdColumn(spanIdColumn);
+        }
+
         // Add index rules for BanyanDB trace model
         if (aClass.isAnnotationPresent(BanyanDB.Trace.TraceIdColumn.class) ||
             aClass.isAnnotationPresent(BanyanDB.Trace.IndexRule.List.class)) {
diff --git a/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/zipkin/ZipkinSpanRecord.java b/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/zipkin/ZipkinSpanRecord.java
@@ -56,6 +56,7 @@
 @SQLDatabase.ExtraColumn4AdditionalEntity(additionalTable = ZipkinSpanRecord.ADDITIONAL_QUERY_TABLE, parentColumn = TIME_BUCKET)
 @BanyanDB.TimestampColumn(ZipkinSpanRecord.TIMESTAMP_MILLIS)
 @BanyanDB.Trace.TraceIdColumn(ZipkinSpanRecord.TRACE_ID)
+@BanyanDB.Trace.SpanIdColumn(ZipkinSpanRecord.SPAN_ID)
 @BanyanDB.Trace.IndexRule(name = ZipkinSpanRecord.TIMESTAMP_MILLIS, columns = {
     ZipkinSpanRecord.LOCAL_ENDPOINT_SERVICE_NAME,
 }, orderByColumn = ZipkinSpanRecord.TIMESTAMP_MILLIS)
diff --git a/oap-server/server-query-plugin/status-query-plugin/src/main/java/org/apache/skywalking/oap/query/debug/DebuggingHTTPHandler.java b/oap-server/server-query-plugin/status-query-plugin/src/main/java/org/apache/skywalking/oap/query/debug/DebuggingHTTPHandler.java
@@ -183,7 +183,6 @@ public String queryBasicTraces(@Param("service") Optional<String> service,
                                    @Param("startTime") String startTime,
                                    @Param("endTime") String endTime,
                                    @Param("step") String step,
-                                   @Param("coldStage") Optional<Boolean> coldStage,
                                    @Param("minTraceDuration") Optional<Integer> minDuration,
                                    @Param("maxTraceDuration") Optional<Integer> maxDuration,
                                    @Param("traceState") String traceState,
@@ -203,7 +202,6 @@ public String queryBasicTraces(@Param("service") Optional<String> service,
         duration.setStart(startTime);
         duration.setEnd(endTime);
         duration.setStep(Step.valueOf(step));
-        coldStage.ifPresent(duration::setColdStage);
         Pagination pagination = new Pagination();
         pagination.setPageNum(pageNum);
         pagination.setPageSize(pageSize);
@@ -236,30 +234,22 @@ public String queryBasicTraces(@Param("service") Optional<String> service,
         return transToYAMLString(result);
     }
 
-    @SneakyThrows
-    @Get("/debugging/query/trace/queryTrace")
-    public String queryTrace(@Param("traceId") String traceId) {
-        Trace trace = traceQuery.queryTrace(traceId, null, true).join();
-        DebuggingQueryTraceRsp result = new DebuggingQueryTraceRsp(
-            trace.getSpans(), transformTrace(trace.getDebuggingTrace()));
-        return transToYAMLString(result);
-    }
-
     /**
-     * Only for BanyanDB, can be used to query the trace in the cold stage.
+     * Only BanyanDB can query the trace in the cold stage.
      */
     @SneakyThrows
-    @Get("/debugging/query/trace/queryTraceFromColdStage")
-    public String queryTraceFromColdStage(@Param("traceId") String traceId,
-                                          @Param("startTime") String startTime,
-                                          @Param("endTime") String endTime,
-                                          @Param("step") String step) {
+    @Get("/debugging/query/trace/queryTrace")
+    public String queryTrace(@Param("traceId") String traceId,
+                             @Param("startTime") String startTime,
+                             @Param("endTime") String endTime,
+                             @Param("step") String step,
+                             @Param("coldStage") Optional<Boolean> coldStage) {
         Duration duration = new Duration();
         duration.setStart(startTime);
         duration.setEnd(endTime);
         duration.setStep(Step.valueOf(step));
-        duration.setColdStage(true);
-        Trace trace = traceQuery.queryTraceFromColdStage(traceId, duration, true).join();
+        coldStage.ifPresent(duration::setColdStage);
+        Trace trace = traceQuery.queryTrace(traceId, duration, true).join();
         DebuggingQueryTraceRsp result = new DebuggingQueryTraceRsp(
             trace.getSpans(), transformTrace(trace.getDebuggingTrace()));
         return transToYAMLString(result);
diff --git a/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/MetadataRegistry.java b/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/MetadataRegistry.java
@@ -229,6 +229,7 @@ public TraceModel registerTraceModel(Model model, BanyanDBStorageConfig config)
                                                    .setName(schemaMetadata.name()));
         builder.setTraceIdTagName(model.getBanyanDBModelExtension().getTraceIdColumn());
         builder.setTimestampTagName(timestampColumn);
+        builder.setSpanIdTagName(model.getBanyanDBModelExtension().getSpanIdColumn());
         for (final ModelColumn col : model.getColumns()) {
             final String columnStorageName = col.getColumnName().getStorageName();
             // skip no index column, since they are not supposed to be queried
diff --git a/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/stream/AbstractBanyanDBDAO.java b/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/stream/AbstractBanyanDBDAO.java
@@ -324,8 +324,7 @@ protected TraceQueryResponse queryTraceDebuggable(boolean isColdStage,
                 builder.append("\n").append(" Response: ").append(new Gson().toJson(response.getTraces()));
                 span.setMsg(builder.toString());
             }
-            //todo: need update banyandb java client.
-           // addDBTrace2DebuggingTrace(response.getTraceResult(), traceContext, span);
+            addDBTrace2DebuggingTrace(response.getTraceResult(), traceContext, span);
             return response;
         } finally {
             if (traceContext != null && span != null) {
diff --git a/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/stream/BanyanDBRecordDAO.java b/oap-server/server-storage-plugin/storage-banyandb-plugin/src/main/java/org/apache/skywalking/oap/server/storage/plugin/banyandb/stream/BanyanDBRecordDAO.java
@@ -76,7 +76,12 @@ public InsertRequest prepareBatchInsert(Model model, Record record) throws IOExc
                                     tag,
                                     TagAndValue.timestampTagValue(mergeTable.getTimestampColumnValue())
                                 );
-                            } else {
+                            } else if (tag.equals(mergeTable.getMergeSpanIdColumnName())) {
+                                traceWrite.tag(
+                                    tag,
+                                    TagAndValue.stringTagValue(mergeTable.getSpanIdColumnValue())
+                                );
+                            } else  {
                                 traceWrite.tag(tag, TagAndValue.nullTagValue());
                             }
                         }
diff --git a/test/e2e-v2/script/env b/test/e2e-v2/script/env
@@ -23,7 +23,7 @@ SW_AGENT_CLIENT_JS_COMMIT=af0565a67d382b683c1dbd94c379b7080db61449
 SW_AGENT_CLIENT_JS_TEST_COMMIT=4f1eb1dcdbde3ec4a38534bf01dded4ab5d2f016
 SW_KUBERNETES_COMMIT_SHA=6fe5e6f0d3b7686c6be0457733e825ee68cb9b35
 SW_ROVER_COMMIT=79292fe07f17f98f486e0c4471213e1961fb2d1d
-SW_BANYANDB_COMMIT=a3fc5bc16e8c9c3385beb41dcef8b988314ff58d
+SW_BANYANDB_COMMIT=f23caf08871b963bbb07b44141457660ff487568
 SW_AGENT_PHP_COMMIT=d1114e7be5d89881eec76e5b56e69ff844691e35
 SW_PREDICTOR_COMMIT=54a0197654a3781a6f73ce35146c712af297c994
 

Original file line number	Diff line number	Diff line change
`@@ -34,5 +34,9 @@ interface MergeTable {`
`34`	`34`	`String getMergeTimestampColumnName();`
`35`	`35`
`36`	`36`	`long getTimestampColumnValue();`
	`37`	`+`
	`38`	`+ String getMergeSpanIdColumnName();`
	`39`	`+`
	`40`	`+ String getSpanIdColumnValue();`
`37`	`41`	`}`
`38`	`42`	`}`