trace.graphqls

# 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.

# The list of traces
type TraceBrief {
    traces: [BasicTrace!]!
    #For OAP internal query debugging
    debuggingTrace: DebuggingTrace
}

# Trace basic info
type BasicTrace {
    segmentId: String!
    endpointNames: [String!]!
    duration: Int!
    start: String!
    isError: Boolean
    traceIds: [String!]!
}

# Represent the conditions used for query TraceBrief
input TraceQueryCondition {
    # The value of 0 means all services.
    serviceId: ID
    serviceInstanceId: ID
    traceId: String
    endpointId: ID
    # The time range of traces started
    queryDuration: Duration
    # The min time of trace
    minTraceDuration: Int
    # The max time of trace
    maxTraceDuration: Int
    traceState: TraceState!
    queryOrder: QueryOrder!
    # Map to the tags included in the traces
    tags: [SpanTag!]
    paging: Pagination!
}

input SpanTag {
    key: String!
    value: String
}

enum TraceState {
    ALL
    SUCCESS
    ERROR
}

enum QueryOrder {
    BY_START_TIME
    BY_DURATION
}

# The trace represents a distributed trace, includes all segments and spans.
type Trace {
    spans: [Span!]!
    #For OAP internal query debugging
    debuggingTrace: DebuggingTrace
}

type Span {
    traceId: ID!
    segmentId: ID!
    spanId: Int!
    parentSpanId: Int!
    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.
# The parent(ref) may not exists, which means batch process.
# The UI should display a list, representing the other trace IDs.
type Ref {
    traceId: ID!
    parentSegmentId: ID!
    parentSpanId: Int!
    # Ref type represents why did the ref happen.
    # Include: 1) CrossProcess 2) CrossThread
    type: RefType!
}

enum RefType {
    CROSS_PROCESS,
    CROSS_THREAD
}

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!]!
}

# Param, if debug is true will enable the query tracing and return DebuggingTrace in the result.
extend type Query {
    # Search segment list with given conditions
    queryBasicTraces(condition: TraceQueryCondition, debug: Boolean): TraceBrief
    # Read the specific trace ID with given trace ID
    queryTrace(traceId: ID!, debug: Boolean): 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!]
}