[skywalking-query-protocol] branch master updated: Define SpanAttachedEvent query protocol (#101)

[wu...@apache.org]

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

wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking-query-protocol.git


The following commit(s) were added to refs/heads/master by this push:
     new 6ebb10a  Define SpanAttachedEvent query protocol (#101)
6ebb10a is described below

commit 6ebb10a411902cfca1b36e9fe6133f0e347433ea
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Oct 17 21:35:30 2022 +0800

    Define SpanAttachedEvent query protocol (#101)
---
 common.graphqls |  6 ++++++
 trace.graphqls  | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/common.graphqls b/common.graphqls
index 0fd5a03..4b48d04 100644
--- a/common.graphqls
+++ b/common.graphqls
@@ -36,6 +36,12 @@ type KeyValue {
     value: String
 }
 
+# String key, Long/Int value pair.
+type KeyNumericValue {
+    key: String!
+    value: Long!
+}
+
 # The Duration defines the start and end time for each query operation.
 # Fields: `start` and `end`
 #   represents the time span. And each of them matches the step.
diff --git a/trace.graphqls b/trace.graphqls
index 5edee31..eac965a 100644
--- a/trace.graphqls
+++ b/trace.graphqls
@@ -78,19 +78,28 @@ type Span {
     refs: [Ref!]!
     serviceCode: String!
     serviceInstanceName: ID!
+    # The start timestamp of the span in millisecond
     startTime: Long!
+    # The end timestamp of the span in millisecond
     endTime: Long!
     endpointName: String
     # There are three span types: Local, Entry and Exit
     type: String!
     # Peer network id, e.g. host+port, ip+port
     peer: String
+    # The name of the tech stack component used for the execution represented by the span.
     component: String
+    # The error status is true when the execution returns error code or throws an exception(determined by the language).
     isError: Boolean
     # There are 5 layers: Unknown, Database, RPCFramework, Http, MQ and Cache
     layer: String
+    # key-value(string) pairs to specify unique attributes of ths span
     tags: [KeyValue!]!
+    # The events happen of the span, especially in-process.
     logs: [LogEntity!]!
+    # The attached events happen in the span's context but out-of-process.
+    # Check SpanAttachedEvent definition for more details.
+    attachedEvents: [SpanAttachedEvent!]!
 }
 
 # Ref represents the link between the segment and its parents.
@@ -111,13 +120,60 @@ enum RefType {
 }
 
 type LogEntity {
+    # The timestamp of the log in millisecond
     time: Long!
     data: [KeyValue!]
 }
 
+# An instantaneous point on the time-line.
+# An instant represents a data point accurate to the nanosecond.
+# It is constituted by a long representing epoch-seconds and an int representing nanosecond-of-second,
+# which will always be between 0 and 999,999,999
+type Instant {
+    # The number of seconds from the epoch of 1970-01-01T00:00:00Z.
+    seconds: Long!
+    # The number of nanoseconds, later along the time-line, from the seconds field.
+    # This is always positive, and never exceeds 999,999,999.
+    nanos: Int!
+}
+
+# SpanAttachedEvent represents an attached event for a traced RPC.
+# When an RPC is being traced by the in-process language agent, a span would be reported by the client-side agent.
+# And the rover would be aware of this RPC due to the existing tracing header.
+# Then, the rover agent collects extra information from the OS level to provide assistance information to diagnose network performance.
+#
+# Notice, THIS IS ALSO AVAILABLE FOR ZIPKIN SPAN.
+# -----------------------------------------------
+# In SkyWalking, ZipkinQueryHandler provides full support for all Zipkin span queries.
+# SpanAttachedEvent query is supported through the trace query URI: /api/v2/trace/{traceId}
+# A new `attachedEvents` field would be added in JSONArray format with SpanAttachedEvent in JSON as elements.
+type SpanAttachedEvent {
+    # The nanosecond timestamp of the event's start time.
+    # Notice, most unit of timestamp in SkyWalking is milliseconds, but NANO-SECOND is required here.
+    # Because the attached event happens in the OS syscall level, most of them are executed rapidly.
+    startTime: Instant!
+    # The official event name.
+    # For example, the event name is a method signature from syscall stack.
+    event: String!
+    # [Optional] The nanosecond timestamp of the event's end time.
+    endTime: Instant!
+    # The tags for this event includes some extra OS level information,
+    # such as
+    # 1. net_device used for this exit span.
+    # 2. network L7 protocol
+    tags: [KeyValue]!
+    # The summary of statistics during this event.
+    # Each statistic provides a name(metric name) to represent the name, and an int64/long as the value.
+    summary: [KeyNumericValue!]!
+}
+
 extend type Query {
+    # Search segment list with given conditions
     queryBasicTraces(condition: TraceQueryCondition): TraceBrief
+    # Read the specific trace ID with given trace ID
     queryTrace(traceId: ID!): Trace
+    # Read the list of searchable keys
     queryTraceTagAutocompleteKeys(duration: Duration!):[String!]
+    # Search the available value options of the given key.
     queryTraceTagAutocompleteValues(tagKey: String! , duration: Duration!):[String!]
 }