Project: SkyWalking (Observability and Analysis / Observability)
File: query-protocol.md

Query Protocol defines a set of APIs in GraphQL grammar to provide data query and interactive capabilities with SkyWalking native visualization tool or 3rd party system, including Web UI, CLI or private system. Query protocol official repository, https://github.com/apache/skywalking-query-protocol. All deprecated APIs are moved . Metadata contains concise information on all services and their instances, endpoints, etc. under monitoring. You may query the metadata in different ways. Provide Metadata V2 query APIs since 9.0.0, including Layer concept. ```graphql extend type Query { listLayers: [String!]! listServices(layer: String): [Service!]! getService(serviceId: String!): Service findService(serviceName: String!): Service listInstances(duration: Duration!, serviceId: ID!): [ServiceInstance!]! getInstance(instanceId: String!): ServiceInstance findEndpoint(keyword: String, serviceId: ID!, limit: Int!): [Endpoint!]! getEndpointInfo(endpointId: ID!): EndpointInfo listProcesses(duration: Duration!, instanceId: ID!): [Process!]! getProcess(processId: ID!): Process estimateProcessScale(serviceId: ID!, labels: [String!]!): Long! getTimeInfo: TimeInfo } ``` The topology and dependency graphs among services, instances and endpoints. Includes direct relationships or global maps. ```graphql extend type Query { getGlobalTopology(duration: Duration!, layer: String): Topology getServiceTopology(serviceId: ID!, duration: Duration!): Topology getServicesTopology(serviceIds: [ID!]!, duration: Duration!): Topology getServiceInstanceTopology(clientServiceId: ID!, serverServiceId: ID!, duration: Duration!): ServiceInstanceTopology getEndpointTopology(endpointId: ID!, duration: Duration!): Topology getEndpointDependencies(endpointId: ID!, duration: Duration!): EndpointTopology getProcessTopology(serviceInstanceId: ID!, duration: Duration!): ProcessTopology } ``` Metrics query targets all objects defined in and . Provide Metrics V3 query APIs since 9.5.0, including metadata and MQE. SkyWalking Metrics Query Expression(MQE) is an extension query mechanism. MQE allows users to do simple query-stage calculation like well known PromQL through GraphQL. The expression's syntax can refer to . ```graphql extend type Query { typeOfMetrics(name: String!): MetricsType! listMetrics(regex: String): [MetricDefinition!]! execExpression(expression: String!, entity: Entity!, duration: Duration!): ExpressionResult! } ``` ```graphql type ExpressionResult { type: ExpressionResultType! results: [MQEValues!]! error: String } ``` ```graphql enum ExpressionResultType { UNKNOWN SINGLE_VALUE TIMESERIESVALUES SORTED_LIST RECORD_LIST } ``` ```graphql extend type Query { supportQueryLogsByKeywords: Boolean! queryLogs(condition: LogQueryCondition): Logs test(requests: LogTestRequest!): LogTestResponse! queryLogTagAutocompleteKeys(duration: Duration!):[String!] queryLogTagAutocompleteValues(tagKey: String! , duration: Duration!):[String!] } ``` Log implementations vary between different database

Some search engines like ElasticSearch and OpenSearch can support full log text fuzzy queries, while others do not due to considerations related to performance impact and end user experience. `test` API serves as the debugging tool for native LAL parsing. ```graphql extend type Query { queryBasicTraces(condition: TraceQueryCondition): TraceBrief queryTrace(traceId: ID!): Trace queryTraceTagAutocompleteKeys(duration: Duration!):[String!] queryTraceTagAutocompleteValues(tagKey: String! , duration: Duration!):[String!] } ``` Trace query fetches trace segment lists and spans of given trace IDs. ```graphql extend type Query { getAlarmTrend(duration: Duration!): AlarmTrend! getAlarm(duration: Duration!, scope: Scope, keyword: String, paging: Pagination!, tags: [AlarmTag]): Alarms } ``` Alarm query identifies alarms and related events. ```graphql extend type Query { queryEvents(condition: EventQueryCondition): Events } ``` Event query fetches the event list based on given sources and time range conditions. SkyWalking offers two types of , in-process and out-process, allowing users to create tasks and check their execution status. ```graphql extend type Mutation { createProfileTask(creationRequest: ProfileTaskCreationRequest): ProfileTaskCreationResult! } extend type Query { getProfileTaskList(serviceId: ID, endpointName: String): [ProfileTask!]! getProfileTaskLogs(taskID: String): [ProfileTaskLog!]! getProfileTaskSegments(taskID: ID!): [ProfiledTraceSegments!]! getSegmentsProfileAnalyze(queries: [SegmentProfileAnalyzeQuery!]!): ProfileAnalyzation! } ``` ```graphql extend type Mutation { createEBPFProfilingFixedTimeTask(request: EBPFProfilingTaskFixedTimeCreationRequest!): EBPFProfilingTaskCreationResult! createEBPFNetworkProfiling(request: EBPFProfilingNetworkTaskRequest!): EBPFProfilingTaskCreationResult! keepEBPFNetworkProfiling(taskId: ID!): EBPFNetworkKeepProfilingResult! } extend type Query { queryPrepareCreateEBPFProfilingTaskData(serviceId: ID!): EBPFProfilingTaskPrepare! queryEBPFProfilingTasks(serviceId: ID, serviceInstanceId: ID, targets: [EBPFProfilingTargetType!], triggerType: EBPFProfilingTriggerType, duration: Duration): [EBPFProfilingTask!]! queryEBPFProfilingSchedules(taskId: ID!): [EBPFProfilingSchedule!]! analysisEBPFProfilingResult(scheduleIdList: [ID!]!, timeRanges: [EBPFProfilingAnalyzeTimeRange!]!, aggregateType: EBPFProfilingAnalyzeAggregateType): EBPFProfilingAnalyzation! } ``` Provide APIs to query since 9.1.0. ```graphql extend type Query { listContainers(condition: OndemandContainergQueryCondition): PodContainers ondemandPodLogs(condition: OndemandLogQueryCondition): Logs } ``` Provide query APIs since 10.0.0, including service and instance hierarchy. ```graphql extend type Query { getServiceHierarchy(serviceId: ID!, layer: String!): ServiceHierarchy! getInstanceHierarchy(instanceId: ID!, layer: String!): InstanceHierarchy! listLayerLevels: [LayerLevel!]! } ``` Duration is a widely used parameter type as the APM data is time-related. See the following for more details. Step relates to precision. ```graphql input Duration { start: String! end: String! step: Step! } enum Step { MONTH DAY HOUR MINUTE SECOND } ```