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 <hanahm...@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 <hanahm...@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'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 |
