You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by ha...@apache.org on 2025/07/01 00:43:01 UTC

(skywalking-banyandb) 01/01: Introduce the `Trace` data model to store the trace/span data

This is an automated email from the ASF dual-hosted git repository.

hanahmily pushed a commit to branch trace
in repository https://gitbox.apache.org/repos/asf/skywalking-banyandb.git

commit 73bcc1944e1932d2605be6d233891273c693a74c
Author: Gao Hongtao <ha...@gmail.com>
AuthorDate: Tue Jul 1 00:35:09 2025 +0000

    Introduce the `Trace` data model to store the trace/span data
    
    Signed-off-by: Gao Hongtao <ha...@gmail.com>
---
 CHANGES.md                                  |   1 +
 api/proto/banyandb/common/v1/common.proto   |   1 +
 api/proto/banyandb/database/v1/schema.proto |  25 ++++
 api/proto/banyandb/trace/v1/query.proto     |  72 ++++++++++
 api/proto/banyandb/trace/v1/rpc.proto       |  40 ++++++
 api/proto/banyandb/trace/v1/write.proto     |  42 ++++++
 docs/api-reference.md                       | 205 ++++++++++++++++++++++++++++
 7 files changed, 386 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 5ebb4d53..aba5d5f6 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -18,6 +18,7 @@ Release Notes.
 - Implement versioning properties and replace physical deletion with the tombstone mechanism for the property database.
 - Add Load Balancer Feature to Liaison. 
 - Implement fadvise for large files to prevent page cache pollution.
+- Data Model: Introduce the `Trace` data model to store the trace/span data.
 
 ### Bug Fixes
 
diff --git a/api/proto/banyandb/common/v1/common.proto b/api/proto/banyandb/common/v1/common.proto
index 733c68c2..644b08de 100644
--- a/api/proto/banyandb/common/v1/common.proto
+++ b/api/proto/banyandb/common/v1/common.proto
@@ -30,6 +30,7 @@ enum Catalog {
   CATALOG_STREAM = 1;
   CATALOG_MEASURE = 2;
   CATALOG_PROPERTY = 3;
+  CATALOG_TRACE = 4;
 }
 
 // Metadata is for multi-tenant, multi-model use
diff --git a/api/proto/banyandb/database/v1/schema.proto b/api/proto/banyandb/database/v1/schema.proto
index 42bcf3df..7a9979f1 100644
--- a/api/proto/banyandb/database/v1/schema.proto
+++ b/api/proto/banyandb/database/v1/schema.proto
@@ -163,6 +163,8 @@ message IndexRule {
   enum Type {
     TYPE_UNSPECIFIED = 0;
     TYPE_INVERTED = 1;
+    // TYPE_TREE is a tree index, which is used for storing hierarchical data.
+    TYPE_TREE = 3;
   }
   // type is the IndexType of this IndexObject.
   Type type = 3 [(validate.rules).enum.defined_only = true];
@@ -219,3 +221,26 @@ message Property {
   // updated_at indicates when the property is updated
   google.protobuf.Timestamp updated_at = 6;
 }
+
+// TraceTagSpec defines the specification of a tag in a trace.
+message TraceTagSpec {
+  // name is the name of the tag.
+  string name = 1 [(validate.rules).string.min_len = 1];
+  // type is the type of the tag.
+  TagType type = 2 [(validate.rules).enum.defined_only = true];
+}
+
+// Trace defines a tracing-specific storage resource.
+// It is suitable for storing traces and spans.
+// The name of a Trace is a logical namespace within a group,
+// while the group of a Trace corresponds to a physical directory.
+message Trace {
+  // metadata is the identity of the trace resource.
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
+  // tags are the specification of tags.
+  repeated TraceTagSpec tags = 2 [(validate.rules).repeated.min_items = 1];
+  // trace_id_tag_name is the name of the tag that stores the trace ID.
+  string trace_id_tag_name = 3 [(validate.rules).string.min_len = 1];
+  // updated_at indicates when the trace resource is updated.
+  google.protobuf.Timestamp updated_at = 4;
+}
diff --git a/api/proto/banyandb/trace/v1/query.proto b/api/proto/banyandb/trace/v1/query.proto
new file mode 100644
index 00000000..39c7b726
--- /dev/null
+++ b/api/proto/banyandb/trace/v1/query.proto
@@ -0,0 +1,72 @@
+// Licensed to Apache Software Foundation (ASF) under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Apache Software Foundation (ASF) licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+syntax = "proto3";
+
+package banyandb.trace.v1;
+
+import "banyandb/common/v1/trace.proto";
+import "banyandb/model/v1/query.proto";
+import "google/protobuf/timestamp.proto";
+import "validate/validate.proto";
+
+option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/trace/v1";
+option java_package = "org.apache.skywalking.banyandb.trace.v1";
+
+// Span is a single operation within a trace.
+message Span {
+  // tags are the indexed tags of the span.
+  repeated model.v1.Tag tags = 1;
+  // span is the raw span data.
+  bytes span = 2;
+  // timestamp is the timestamp of the span.
+  google.protobuf.Timestamp timestamp = 3;
+}
+
+// QueryResponse is the response of a query.
+message QueryResponse {
+  // spans is a list of spans that match the query.
+  repeated Span spans = 1;
+  // trace_query_result contains the trace of the query execution if tracing is enabled.
+  common.v1.Trace trace_query_result = 2;
+}
+
+// QueryRequest is the request contract for query.
+message QueryRequest {
+  // groups indicate the physical data location.
+  repeated string groups = 1 [(validate.rules).repeated.min_items = 1];
+  // name is the identity of a trace.
+  string name = 2 [(validate.rules).string.min_len = 1];
+  // time_range is a range query with begin/end time of entities in the timeunit of milliseconds.
+  // In the context of trace, it represents the range of the `startTime` for spans/segments,
+  // it is always recommended to specify time range for performance reason
+  model.v1.TimeRange time_range = 3;
+  // offset is used to support pagination, together with the following limit
+  uint32 offset = 4;
+  // limit is used to impose a boundary on the number of spans being returned
+  uint32 limit = 5;
+  // order_by is given to specify the sort for a tag. So far, only fields in the type of Integer are supported
+  model.v1.QueryOrder order_by = 6;
+  // criteria is the filter criteria.
+  model.v1.Criteria criteria = 7;
+  // projection can be used to select the names of the tags in the response
+  repeated string tag_projection = 8;
+  // trace is used to enable trace for the query
+  bool trace = 9;
+  // stage is used to specify the stage of the query in the lifecycle
+  repeated string stages = 10;
+}
diff --git a/api/proto/banyandb/trace/v1/rpc.proto b/api/proto/banyandb/trace/v1/rpc.proto
new file mode 100644
index 00000000..0c889388
--- /dev/null
+++ b/api/proto/banyandb/trace/v1/rpc.proto
@@ -0,0 +1,40 @@
+// Licensed to Apache Software Foundation (ASF) under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Apache Software Foundation (ASF) licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+syntax = "proto3";
+
+package banyandb.trace.v1;
+
+import "banyandb/trace/v1/query.proto";
+import "banyandb/trace/v1/write.proto";
+import "google/api/annotations.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/trace/v1";
+option java_package = "org.apache.skywalking.banyandb.trace.v1";
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {base_path: "/api"};
+
+service TraceService {
+  rpc Query(QueryRequest) returns (QueryResponse) {
+    option (google.api.http) = {
+      post: "/v1/trace/data"
+      body: "*"
+    };
+  }
+
+  rpc Write(stream WriteRequest) returns (stream WriteResponse);
+}
diff --git a/api/proto/banyandb/trace/v1/write.proto b/api/proto/banyandb/trace/v1/write.proto
new file mode 100644
index 00000000..38a6c1f1
--- /dev/null
+++ b/api/proto/banyandb/trace/v1/write.proto
@@ -0,0 +1,42 @@
+// Licensed to Apache Software Foundation (ASF) under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Apache Software Foundation (ASF) licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+syntax = "proto3";
+
+package banyandb.trace.v1;
+
+import "banyandb/common/v1/common.proto";
+import "banyandb/model/v1/common.proto";
+import "google/protobuf/timestamp.proto";
+import "validate/validate.proto";
+
+option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/trace/v1";
+option java_package = "org.apache.skywalking.banyandb.trace.v1";
+
+message WriteRequest {
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
+  repeated model.v1.TagValue tags = 2 [(validate.rules).repeated.min_items = 1];
+  bytes span = 3;
+  uint64 version = 4 [(validate.rules).uint64.gt = 0];
+  google.protobuf.Timestamp timestamp = 5;
+}
+
+message WriteResponse {
+  common.v1.Metadata metadata = 1;
+  uint64 version = 2;
+  string status = 3;
+}
diff --git a/docs/api-reference.md b/docs/api-reference.md
index ef9e1efd..6467c0a8 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -85,6 +85,8 @@
     - [TagFamilySpec](#banyandb-database-v1-TagFamilySpec)
     - [TagSpec](#banyandb-database-v1-TagSpec)
     - [TopNAggregation](#banyandb-database-v1-TopNAggregation)
+    - [Trace](#banyandb-database-v1-Trace)
+    - [TraceTagSpec](#banyandb-database-v1-TraceTagSpec)
   
     - [CompressionMethod](#banyandb-database-v1-CompressionMethod)
     - [EncodingMethod](#banyandb-database-v1-EncodingMethod)
@@ -256,6 +258,18 @@
   
     - [StreamService](#banyandb-stream-v1-StreamService)
   
+- [banyandb/trace/v1/query.proto](#banyandb_trace_v1_query-proto)
+    - [QueryRequest](#banyandb-trace-v1-QueryRequest)
+    - [QueryResponse](#banyandb-trace-v1-QueryResponse)
+    - [Span](#banyandb-trace-v1-Span)
+  
+- [banyandb/trace/v1/write.proto](#banyandb_trace_v1_write-proto)
+    - [WriteRequest](#banyandb-trace-v1-WriteRequest)
+    - [WriteResponse](#banyandb-trace-v1-WriteResponse)
+  
+- [banyandb/trace/v1/rpc.proto](#banyandb_trace_v1_rpc-proto)
+    - [TraceService](#banyandb-trace-v1-TraceService)
+  
 - [Scalar Value Types](#scalar-value-types)
 
 
@@ -502,6 +516,7 @@ Metadata is for multi-tenant, multi-model use
 | CATALOG_STREAM | 1 |  |
 | CATALOG_MEASURE | 2 |  |
 | CATALOG_PROPERTY | 3 |  |
+| CATALOG_TRACE | 4 |  |
 
 
 
@@ -1390,6 +1405,43 @@ TopNAggregation generates offline TopN statistics for a measure&#39;s TopN appro
 
 
 
+
+<a name="banyandb-database-v1-Trace"></a>
+
+### Trace
+Trace defines a tracing-specific storage resource.
+It is suitable for storing traces and spans.
+The name of a Trace is a logical namespace within a group,
+while the group of a Trace corresponds to a physical directory.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| metadata | [banyandb.common.v1.Metadata](#banyandb-common-v1-Metadata) |  | metadata is the identity of the trace resource. |
+| tags | [TraceTagSpec](#banyandb-database-v1-TraceTagSpec) | repeated | tags are the specification of tags. |
+| trace_id_tag_name | [string](#string) |  | trace_id_tag_name is the name of the tag that stores the trace ID. |
+| updated_at | [google.protobuf.Timestamp](#google-protobuf-Timestamp) |  | updated_at indicates when the trace resource is updated. |
+
+
+
+
+
+
+<a name="banyandb-database-v1-TraceTagSpec"></a>
+
+### TraceTagSpec
+TraceTagSpec defines the specification of a tag in a trace.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| name | [string](#string) |  | name is the name of the tag. |
+| type | [TagType](#banyandb-database-v1-TagType) |  | type is the type of the tag. |
+
+
+
+
+
  
 
 
@@ -1441,6 +1493,7 @@ Type determine the index structure under the hood
 | ---- | ------ | ----------- |
 | TYPE_UNSPECIFIED | 0 |  |
 | TYPE_INVERTED | 1 |  |
+| TYPE_TREE | 3 | TYPE_TREE is a tree index, which is used for storing hierarchical data. |
 
 
 
@@ -3744,6 +3797,158 @@ QueryResponse is the response for a query to the Query module.
 
 
 
+<a name="banyandb_trace_v1_query-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## banyandb/trace/v1/query.proto
+
+
+
+<a name="banyandb-trace-v1-QueryRequest"></a>
+
+### QueryRequest
+QueryRequest is the request contract for query.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| groups | [string](#string) | repeated | groups indicate the physical data location. |
+| name | [string](#string) |  | name is the identity of a trace. |
+| time_range | [banyandb.model.v1.TimeRange](#banyandb-model-v1-TimeRange) |  | time_range is a range query with begin/end time of entities in the timeunit of milliseconds. In the context of trace, it represents the range of the `startTime` for spans/segments, it is always recommended to specify time range for performance reason |
+| offset | [uint32](#uint32) |  | offset is used to support pagination, together with the following limit |
+| limit | [uint32](#uint32) |  | limit is used to impose a boundary on the number of spans being returned |
+| order_by | [banyandb.model.v1.QueryOrder](#banyandb-model-v1-QueryOrder) |  | order_by is given to specify the sort for a tag. So far, only fields in the type of Integer are supported |
+| criteria | [banyandb.model.v1.Criteria](#banyandb-model-v1-Criteria) |  | criteria is the filter criteria. |
+| tag_projection | [string](#string) | repeated | projection can be used to select the names of the tags in the response |
+| trace | [bool](#bool) |  | trace is used to enable trace for the query |
+| stages | [string](#string) | repeated | stage is used to specify the stage of the query in the lifecycle |
+
+
+
+
+
+
+<a name="banyandb-trace-v1-QueryResponse"></a>
+
+### QueryResponse
+QueryResponse is the response of a query.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| spans | [Span](#banyandb-trace-v1-Span) | repeated | spans is a list of spans that match the query. |
+| trace_query_result | [banyandb.common.v1.Trace](#banyandb-common-v1-Trace) |  | trace_query_result contains the trace of the query execution if tracing is enabled. |
+
+
+
+
+
+
+<a name="banyandb-trace-v1-Span"></a>
+
+### Span
+Span is a single operation within a trace.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| tags | [banyandb.model.v1.Tag](#banyandb-model-v1-Tag) | repeated | tags are the indexed tags of the span. |
+| span | [bytes](#bytes) |  | span is the raw span data. |
+| timestamp | [google.protobuf.Timestamp](#google-protobuf-Timestamp) |  | timestamp is the timestamp of the span. |
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+
+<a name="banyandb_trace_v1_write-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## banyandb/trace/v1/write.proto
+
+
+
+<a name="banyandb-trace-v1-WriteRequest"></a>
+
+### WriteRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| metadata | [banyandb.common.v1.Metadata](#banyandb-common-v1-Metadata) |  |  |
+| tags | [banyandb.model.v1.TagValue](#banyandb-model-v1-TagValue) | repeated |  |
+| span | [bytes](#bytes) |  |  |
+| version | [uint64](#uint64) |  |  |
+| timestamp | [google.protobuf.Timestamp](#google-protobuf-Timestamp) |  |  |
+
+
+
+
+
+
+<a name="banyandb-trace-v1-WriteResponse"></a>
+
+### WriteResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| metadata | [banyandb.common.v1.Metadata](#banyandb-common-v1-Metadata) |  |  |
+| version | [uint64](#uint64) |  |  |
+| status | [string](#string) |  |  |
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+
+<a name="banyandb_trace_v1_rpc-proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## banyandb/trace/v1/rpc.proto
+
+
+ 
+
+ 
+
+ 
+
+
+<a name="banyandb-trace-v1-TraceService"></a>
+
+### TraceService
+
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+| Query | [QueryRequest](#banyandb-trace-v1-QueryRequest) | [QueryResponse](#banyandb-trace-v1-QueryResponse) |  |
+| Write | [WriteRequest](#banyandb-trace-v1-WriteRequest) stream | [WriteResponse](#banyandb-trace-v1-WriteResponse) stream |  |
+
+ 
+
+
+
 ## Scalar Value Types
 
 | .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |