This is an automated email from the ASF dual-hosted git repository. wusheng pushed a commit to branch metadata-v2 in repository https://gitbox.apache.org/repos/asf/skywalking-query-protocol.git
commit a262868bc2be0a602031cec4e04aa0572c2b3dec Author: Wu Sheng <[email protected]> AuthorDate: Thu Dec 9 14:31:36 2021 +0800 Introduce SkyWalking v9 core query protocol. --- metadata-v2.graphqls | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++ metadata.graphqls | 43 ++------------------- metrics-v2.graphqls | 21 ++++++----- topology.graphqls | 38 +++++++++---------- 4 files changed, 136 insertions(+), 70 deletions(-) diff --git a/metadata-v2.graphqls b/metadata-v2.graphqls new file mode 100644 index 0000000..b57c9ca --- /dev/null +++ b/metadata-v2.graphqls @@ -0,0 +1,104 @@ +# 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. + +# Metadata query v2 protocol provides the layer-based query to various services monitored by SkyWalking ecosystem. +# It would adopt multiple-layer modern cloud native infrastructure. +# In the v9 core, v1 protocol is provided on the top of the v2 implementation. +# The v1's services, Databases, Browsers are all services with layer=general, layer=database, layer=browser. +# Each service would have native definition about instance and endpoint. + +# Service is a logic concept, representing a collection of runnable context. +type Service { + id: ID! + name: String! + # The custom/logi group of the service + group: String! + # Layer represents an abstract framework in the computer science, such as operation system(VM layer), Kubernetes(k8s layer), + # Service Mesh(typical Istio+Envoy layer). + # The name of layer is a string, but we would reserve some for visualization(UI) + # - os-linux + # - k8s + # - general(agent-installed) + # - faas + # - mesh + # - mesh-cp + # - mesh-dp + # - database + # - cache + # - browser + # + # UI uses this literal string names to provide various layout for their services with metrics. + layer: String! +} + +# The minimal runnable unit in the service. It provides consistent and fundamental capabilities in physical perspective. +# A service, as a logic unit, have multiple instances in the runtime. +# Such as, an OS-level processor, a pod in k8s, a running function in the FAAS engine. +type ServiceInstance { + id: ID! + name: String! + attributes: [Attribute!]! + language: Language! + instanceUUID: String! +} + +type Attribute { + name: String! + value: String! +} + +# The endpoint is the minimal functional unit. +# Typically, it presents a URI or gRPC service name in the service. +# Different from instance, this is a logical functional unit. +type Endpoint { + id: ID! + name: String! +} + +type EndpointInfo { + id: ID! + name: String! + serviceId: ID! + serviceName: String! +} + +type Database { + id: ID! + name: String! + type: String! +} + +type TimeInfo { + # server current timezone, format: +0800 + timezone: String + # server current timestamp, format: 1569124528392 + currentTimestamp: Long +} + +extend type Query { + # Read the service list according to layer. + listServices(layer: String!): [Service!]! + # Read service instance list. + listInstances(duration: Duration!, serviceId: ID!): [ServiceInstance!]! + + findService(serviceId: String!): Service + # Search and find matched endpoints. + findEndpoint(keyword: String!, serviceId: ID!, limit: Int!): [Endpoint!]! + + # Legacy query(s) from v1 + getEndpointInfo(endpointId: ID!): EndpointInfo + getTimeInfo: TimeInfo +} diff --git a/metadata.graphqls b/metadata.graphqls index c4f3ab5..76f4ec3 100644 --- a/metadata.graphqls +++ b/metadata.graphqls @@ -14,6 +14,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +# Legacy metrics query protocol +# Replaced by the metadata-v2 in the future + # Query the cluster brief based on the given duration type ClusterBrief { numOfService: Int! @@ -23,50 +26,12 @@ type ClusterBrief { numOfMQ: Int! } -type Service { - id: ID! - name: String! - group: String! -} - -type ServiceInstance { - id: ID! - name: String! - attributes: [Attribute!]! - language: Language! - instanceUUID: String! -} - -type Attribute { - name: String! - value: String! -} - -type Endpoint { - id: ID! - name: String! -} - -type EndpointInfo { - id: ID! - name: String! - serviceId: ID! - serviceName: String! -} - type Database { id: ID! name: String! type: String! } -type TimeInfo { - # server current timezone, format: +0800 - timezone: String - # server current timestamp, format: 1569124528392 - currentTimestamp: Long -} - extend type Query { # Normal service related meta info getAllServices(duration: Duration!, group: String): [Service!]! @@ -85,11 +50,9 @@ extend type Query { # Consider there are huge numbers of endpoint, # must use endpoint owner's service id, keyword and limit filter to do query. searchEndpoint(keyword: String!, serviceId: ID!, limit: Int!): [Endpoint!]! - getEndpointInfo(endpointId: ID!): EndpointInfo # Database related meta info. getAllDatabases(duration: Duration!): [Database!]! - getTimeInfo: TimeInfo # Deprecated query, left only for not breaking UI for short term. getGlobalBrief(duration: Duration!): ClusterBrief diff --git a/metrics-v2.graphqls b/metrics-v2.graphqls index d1cf512..be5b4a3 100644 --- a/metrics-v2.graphqls +++ b/metrics-v2.graphqls @@ -18,6 +18,10 @@ # defined in the metric.graphql, top-n-records.graphqls, and aggregation.graphqls. # By leveraging the new ID rule(no register) in the v8, we could query metrics based on name(s) directly. +# Metrics v2.1 is introduced since SkyWalking v9 core. +# Change logs: +# - The normal and destNormal tags have been deprecated. + # Metrics type is a new concept since v8. enum MetricsType { # Can't find the metrics type definition. @@ -42,17 +46,16 @@ input Entity { # set necessary names of sources and destinations. scope: Scope! serviceName: String - # Normal service is the service having installed agent or metrics reported directly. - # Unnormal service is conjectural service, usually detected by the agent. - normal: Boolean serviceInstanceName: String endpointName: String destServiceName: String - # Normal service is the service having installed agent or metrics reported directly. - # Unnormal service is conjectural service, usually detected by the agent. - destNormal: Boolean destServiceInstanceName: String destEndpointName: String + + # Deprecated since 9.0.0. Don't need to use this anymore + normal: Boolean + # Deprecated since 9.0.0. Don't need to use this anymore + destNormal: Boolean } input MetricsCondition { @@ -70,15 +73,15 @@ input TopNCondition { name: String! # Could be null if query the global top N. parentService: String - # Normal service is the service having installed agent or metrics reported directly. - # Unnormal service is conjectural service, usually detected by the agent. - normal: Boolean # Indicate the metrics entity scope. # This is required in sortMetrics query. # Only accept scope = Service/ServiceInstance/Endpoint, ignore others due to those are pointless. scope: Scope topN: Int! order: Order! + + # Deprecated since 9.0.0. Don't need to use this anymore + normal: Boolean } # Define the metrics provided in the OAP server. diff --git a/topology.graphqls b/topology.graphqls index 48a76b1..f4217a3 100644 --- a/topology.graphqls +++ b/topology.graphqls @@ -14,6 +14,12 @@ # See the License for the specific language governing permissions and # limitations under the License. +# Topology v1.1 is introduced from SkyWalking v9 core. +# Change logs +# - Deprecated `isReal`, due to in v9, service is about real or not real, it has native layer attribute to determine its type and scope. +# - Deprecated `type` in instance topology and endpoint dependency, because by their latest definitions, they are subsets of services, no point has specific type. +# - All deprecated fields are kept for keeping back-forward compatibility. `isReal=true` and `type=(empty string)` are default values only. + # The overview topology of the whole application cluster or services, type Topology { nodes: [Node!]! @@ -34,9 +40,7 @@ type EndpointTopology { # Node in Topology type Node { - # The global id of each node, - # 1. Service id - # 2. Endpoint id + # The service ID of the node. id: ID! # The literal name of the #id. name: String! @@ -44,7 +48,8 @@ type Node { # 1. The service provider/middleware tech, such as: Tomcat, SpringMVC # 2. Conjectural Service, e.g. MySQL, Redis, Kafka type: String - # It is a conjecture node or real node, to represent a service or endpoint. + + # Deprecated since 9.0.0. Don't need to use this anymore isReal: Boolean! } @@ -58,12 +63,11 @@ type ServiceInstanceNode { serviceId: ID! # The literal name of the #serviceId. serviceName: String! - # The type name may be - # 1. The service provider/middleware tech, such as: Tomcat, SpringMVC - # 2. Conjectural Service, e.g. MySQL, Redis, Kafka + + # Deprecated since 9.0.0. Instance is an executable unit of service, it doesn't have its own type. type: String - # It is a conjecture node or real node, to represent an instance. - isReal: Boolean! + # Deprecated since 9.0.0. Don't need to use this anymore + isReal: Boolean } # Node in EndpointTopology @@ -76,12 +80,11 @@ type EndpointNode { serviceId: ID! # The literal name of the #serviceId. serviceName: String! - # The type name may be - # 1. The service provider/middleware tech, such as: Tomcat, SpringMVC - # 2. Conjectural Service, e.g. MySQL, Redis, Kafka + + # Deprecated since 9.0.0. The endpoint is the minimal functional unit., it doesn't have its own type. type: String - # It is a conjuecture node or real node, to represent an instance. - isReal: Boolean! + # Deprecated since 9.0.0. Don't need to use this anymore + isReal: Boolean } # The Call represents a directed distributed call, @@ -98,13 +101,6 @@ type Call { detectPoints: [DetectPoint!]! } -enum NodeType { - SERVICE, - ENDPOINT, - USER -} - - extend type Query { # Query the global topology getGlobalTopology(duration: Duration!): Topology
