You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2021/08/12 15:24:06 UTC
[skywalking] branch banyandb-client-api created (now c02f4ac)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a change to branch banyandb-client-api
in repository https://gitbox.apache.org/repos/asf/skywalking.git.
at c02f4ac Init module structure.
This branch includes the following new commits:
new c02f4ac Init module structure.
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[skywalking] 01/01: Init module structure.
Posted by wu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch banyandb-client-api
in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit c02f4acadd8e850dd990e8c94beee0e121589cde
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Aug 12 23:23:49 2021 +0800
Init module structure.
---
oap-server/banyandb-java-client/pom.xml | 95 ++++++++++
.../banyandb/v1/client/BanyanDBClient.java | 91 +++++++++
.../src/main/proto/banyandb/v1/banyandb.proto | 210 +++++++++++++++++++++
pom.xml | 1 +
4 files changed, 397 insertions(+)
diff --git a/oap-server/banyandb-java-client/pom.xml b/oap-server/banyandb-java-client/pom.xml
new file mode 100644
index 0000000..2213c3b
--- /dev/null
+++ b/oap-server/banyandb-java-client/pom.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <!-- This module is going to release in a new repo, apache/skywalking-banyandb-java-api -->
+ <parent>
+ <artifactId>oap-server</artifactId>
+ <groupId>org.apache.skywalking</groupId>
+ <version>8.8.0-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>banyandb-java-client</artifactId>
+ <packaging>jar</packaging>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>io.grpc</groupId>
+ <artifactId>grpc-netty-shaded</artifactId>
+ <version>${grpc.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>io.grpc</groupId>
+ <artifactId>grpc-protobuf</artifactId>
+ <version>${grpc.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>io.grpc</groupId>
+ <artifactId>grpc-stub</artifactId>
+ <version>${grpc.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>io.netty</groupId>
+ <artifactId>netty-tcnative-boringssl-static</artifactId>
+ <version>${netty-tcnative-boringssl-static.version}</version>
+ </dependency>
+ <dependency> <!-- necessary for Java 9+ -->
+ <groupId>org.apache.tomcat</groupId>
+ <artifactId>annotations-api</artifactId>
+ <version>${org.apache.tomcat.annotations-api.version}</version>
+ <scope>provided</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+
+ <plugins>
+ <plugin>
+ <groupId>kr.motd.maven</groupId>
+ <artifactId>os-maven-plugin</artifactId>
+ <version>${os-maven-plugin.version}</version>
+ <executions>
+ <execution>
+ <phase>initialize</phase>
+ <goals>
+ <goal>detect</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.xolstice.maven.plugins</groupId>
+ <artifactId>protobuf-maven-plugin</artifactId>
+ <version>${protobuf-maven-plugin.version}</version>
+ <configuration>
+ <!--
+ The version of protoc must match protobuf-java. If you don't depend on
+ protobuf-java directly, you will be transitively depending on the
+ protobuf-java version that grpc depends on.
+ -->
+ <protocArtifact>
+ com.google.protobuf:protoc:${com.google.protobuf.protoc.version}:exe:${os.detected.classifier}
+ </protocArtifact>
+ <pluginId>grpc-java</pluginId>
+ <pluginArtifact>
+ io.grpc:protoc-gen-grpc-java:${protoc-gen-grpc-java.plugin.version}:exe:${os.detected.classifier}
+ </pluginArtifact>
+ </configuration>
+ <executions>
+ <execution>
+ <id>grpc-build</id>
+ <goals>
+ <goal>compile</goal>
+ <goal>compile-custom</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
\ No newline at end of file
diff --git a/oap-server/banyandb-java-client/src/main/java/org/apache/skywalking/banyandb/v1/client/BanyanDBClient.java b/oap-server/banyandb-java-client/src/main/java/org/apache/skywalking/banyandb/v1/client/BanyanDBClient.java
new file mode 100644
index 0000000..a9e5610
--- /dev/null
+++ b/oap-server/banyandb-java-client/src/main/java/org/apache/skywalking/banyandb/v1/client/BanyanDBClient.java
@@ -0,0 +1,91 @@
+/*
+ * Licensed to the 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.
+ * The 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.
+ *
+ */
+
+package org.apache.skywalking.banyandb.v1.client;
+
+import io.grpc.ManagedChannel;
+import io.grpc.ManagedChannelBuilder;
+import io.grpc.NameResolverRegistry;
+import io.grpc.internal.DnsNameResolverProvider;
+import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.Setter;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * BanyanDBClient represents a client instance interacting with BanyanDB server. This is built on the top of BanyanDB v1
+ * gRPC APIs.
+ */
+@RequiredArgsConstructor
+@Slf4j
+public class BanyanDBClient {
+ /**
+ * The hostname of BanyanDB server.
+ */
+ private final String host;
+ /**
+ * The port of BanyanDB server.
+ */
+ private final int port;
+ /**
+ * The instance name.
+ */
+ private final String group;
+ /**
+ * Options for server connection.
+ */
+ @Setter
+ private Options options = new Options();
+ /**
+ * Managed gRPC connection.
+ */
+ private volatile ManagedChannel managedChannel;
+ /**
+ * The connection status.
+ */
+ private volatile boolean isConnected = false;
+
+ /**
+ * Connect to the server.
+ *
+ * @throws RuntimeException if server is not reachable.
+ */
+ public void connect() {
+ NameResolverRegistry.getDefaultRegistry().register(new DnsNameResolverProvider());
+
+ final ManagedChannelBuilder nettyChannelBuilder = NettyChannelBuilder.forAddress(host, port);
+ nettyChannelBuilder.maxInboundMessageSize(options.getMaxInboundMessageSize());
+
+ managedChannel = nettyChannelBuilder.build();
+ isConnected = true;
+ }
+
+ /**
+ * Client connection options.
+ */
+ @Setter
+ @Getter
+ public class Options {
+ private int maxInboundMessageSize = 1024 * 1024 * 50;
+
+ private Options() {
+ }
+
+ }
+}
diff --git a/oap-server/banyandb-java-client/src/main/proto/banyandb/v1/banyandb.proto b/oap-server/banyandb-java-client/src/main/proto/banyandb/v1/banyandb.proto
new file mode 100644
index 0000000..a468d3b
--- /dev/null
+++ b/oap-server/banyandb-java-client/src/main/proto/banyandb/v1/banyandb.proto
@@ -0,0 +1,210 @@
+// 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";
+
+option java_package = "org.apache.skywalking.banyandb.v1";
+
+package banyandb.v1;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/struct.proto";
+
+service TraceService {
+ rpc Query(banyandb.v1.QueryRequest) returns (banyandb.v1.QueryResponse);
+ rpc Write(stream banyandb.v1.WriteRequest) returns (stream banyandb.v1.WriteResponse);
+}
+
+// Metadata is for multi-tenant, multi-model use
+message Metadata {
+ // group contains a set of options, like retention policy, max
+ string group = 1;
+ // name of the entity
+ string name = 2;
+}
+
+// IntPair in a typed pair with an array of int64 as values
+message IntPair {
+ string key = 1;
+ repeated int64 values = 2;
+}
+
+// StrPair in a typed pair with an array of string as values
+message StrPair {
+ string key = 1;
+ repeated string values = 2;
+}
+
+// Pair is the building block of a record which is equivalent to a key-value pair.
+// In the context of Trace, it could be metadata of a trace such as service_name, service_instance, etc.
+// Besides, other fields/tags are organized in key-value pair in the underlying storage layer.
+// One should notice that the values can be a multi-value.
+message TypedPair {
+ oneof typed {
+ IntPair int_pair = 1;
+ StrPair str_pair = 2;
+ }
+}
+
+// PairQuery consists of the query condition with a single binary operator to be imposed
+// For 1:1 BinaryOp, values in condition must be an array with length = 1,
+// while for 1:N BinaryOp, values can be an array with length >= 1.
+message PairQuery {
+ // BinaryOp specifies the operation imposed to the given query condition
+ // For EQ, NE, LT, GT, LE and GE, only one operand should be given, i.e. one-to-one relationship.
+ // HAVING and NOT_HAVING allow multi-value to be the operand such as array/vector, i.e. one-to-many relationship.
+ // For example, "keyA" contains "valueA" **and** "valueB"
+ enum BinaryOp {
+ BINARY_OP_UNSPECIFIED = 0;
+ BINARY_OP_EQ = 1;
+ BINARY_OP_NE = 2;
+ BINARY_OP_LT = 3;
+ BINARY_OP_GT = 4;
+ BINARY_OP_LE = 5;
+ BINARY_OP_GE = 6;
+ BINARY_OP_HAVING = 7;
+ BINARY_OP_NOT_HAVING = 8;
+ }
+ BinaryOp op = 1;
+ TypedPair condition = 2;
+}
+
+// QueryOrder means a Sort operation to be done for a given field.
+// The key_name refers to the key of a Pair.
+message QueryOrder {
+ string key_name = 1;
+ enum Sort {
+ SORT_UNSPECIFIED = 0;
+ SORT_DESC = 1;
+ SORT_ASC = 2;
+ }
+ Sort sort = 2;
+}
+
+// Entity represents
+// (Trace context) a Span defined in Google Dapper paper or equivalently a Segment in Skywalking.
+// (Log context) a log
+message Entity {
+ // entity_id could be span_id of a Span or segment_id of a Segment in the context of Trace
+ string entity_id = 1;
+ // timestamp represents
+ // 1) either the start time of a Span/Segment,
+ // 2) or the timestamp of a log
+ google.protobuf.Timestamp timestamp = 2;
+ // data_binary contains all un-indexed Tags and other key-value pairs
+ bytes data_binary = 3;
+ // fields contains all indexed Field. Some typical names,
+ // - trace_id
+ // - duration
+ // - service_name
+ // - service_instance_id
+ // - end_time_nanoseconds
+ repeated TypedPair fields = 4;
+}
+
+// QueryResponse is the response for a query to the Query module.
+message QueryResponse {
+ // entities are the actual data returned
+ repeated Entity entities = 1;
+}
+
+// Projection is used to select the names of keys to be returned.
+message Projection {
+ // The key_name refers to the key(s) of Pair(s).
+ repeated string key_names = 1;
+}
+
+// TimeRange is a range query for uint64,
+// the range here follows left-inclusive and right-exclusive rule, i.e. [begin, end) if both edges exist
+message TimeRange {
+ google.protobuf.Timestamp begin = 1;
+ google.protobuf.Timestamp end = 2;
+}
+
+// QueryRequest is the request contract for query.
+message QueryRequest {
+ // metadata is required
+ Metadata metadata = 1;
+ // time_range is a range query with begin/end time of entities in the timeunit of nanoseconds.
+ // In the context of Trace, it represents the range of the `startTime` for spans/segments,
+ // while in the context of Log, it means the range of the timestamp(s) for logs.
+ // it is always recommended to specify time range for performance reason
+ TimeRange time_range = 2;
+ // offset is used to support pagination, together with the following limit
+ uint32 offset = 3;
+ // limit is used to impose a boundary on the number of records being returned
+ uint32 limit = 4;
+ // order_by is given to specify the sort for a field. So far, only fields in the type of Integer are supported
+ QueryOrder order_by = 5;
+ // fields are indexed. Some typical fields are listed below,
+ // - trace_id: if given, it takes precedence over other fields and will be used to retrieve entities before other conditions are imposed
+ // - duration: typical for trace context
+ repeated PairQuery fields = 6;
+ // projection can be used to select the key names of the entities in the response
+ Projection projection = 7;
+}
+
+message Str {
+ string value = 1;
+}
+
+message Int {
+ int64 value = 1;
+}
+
+message StrArray {
+ repeated string value = 1;
+}
+
+message IntArray {
+ repeated int64 value = 1;
+}
+
+message Field {
+ oneof value_type {
+ google.protobuf.NullValue null = 1;
+ Str str = 2;
+ StrArray str_array = 3;
+ Int int = 4;
+ IntArray int_array = 5;
+ }
+}
+
+message EntityValue {
+ // entity_id could be span_id of a Span or segment_id of a Segment in the context of Trace
+ string entity_id = 1;
+ // timestamp_nanoseconds is in the timeunit of nanoseconds. It represents
+ // 1) either the start time of a Span/Segment,
+ // 2) or the timestamp of a log
+ google.protobuf.Timestamp timestamp = 2;
+ // binary representation of segments, including tags, spans...
+ bytes data_binary = 3;
+ // support all of indexed fields in the fields.
+ // Pair only has value, as the value of PairValue match with the key
+ // by the index rules and index rule bindings of Metadata group.
+ // indexed fields of multiple entities are compression in the fields.
+ repeated Field fields = 4;
+}
+
+message WriteRequest {
+ // the metadata is only required in the first write.
+ Metadata metadata = 1;
+ // the entity is required.
+ EntityValue entity = 2;
+}
+
+message WriteResponse {}
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index 1a7ad56..d2ab39b 100755
--- a/pom.xml
+++ b/pom.xml
@@ -34,6 +34,7 @@
<modules>
<module>apm-commons</module>
<module>apm-protocol</module>
+ <module>oap-server/banyandb-java-client</module>
</modules>
<packaging>pom</packaging>