[skywalking-query-protocol] 01/01: Define SpanAttachedEvent query protocol

[wu...@apache.org]

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

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

commit 6b170d0d8d302825d11f561bb8715b1bacca40e4
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Oct 17 21:09:28 2022 +0800

    Define SpanAttachedEvent query protocol
---
 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..fb25a26 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 a fully support for all Zipkin span query.
+# SpanAttachedEvent query is supported through a new URI: /api/v2/trace/{traceId}/ext/spanAttachedEvents
+# The response is in JSON as usually, includes all fields of SpanAttachedEvent, and `spanId` as an additional field.
+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!]
 }