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:07 UTC
[skywalking] 01/01: Init module structure.
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>