ebpf-profiling.graphqls - skywalking-query-protocol - Git at Google

 # 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 creation request of eBPF profiling fixed time task
 input EBPFProfilingTaskFixedTimeCreationRequest {
     # define which processes under the service need to be profiling
     serviceId: String!
     # aggregate which processes need to be profiling from labels
     processLabels: [String!]!

     # the task start timestamp(ms), if less then or equal zero means the task starts ASAP
     startTime: Long!
     # the profiling duration(s)
     duration: Int!

     # the task profiling target type
     targetType: EBPFProfilingTargetType!
 }

 # Settings for the behaviours of sampling.
 # HTTP request and response could be large between the system.
 # These settings help the agent to collect necessary data and cost reasonable resources for the agent, transforming, and OAP storage.
 input EBPFNetworkDataCollectingSettings {
     # Require to collect the complete request
     requireCompleteRequest: Boolean!
     # The max size of request context. The unit is byte.
     # Collect the whole request header and body if this is not set.
     maxRequestSize: Int

     # Require to collect the complete response
     requireCompleteResponse: Boolean!
     # The max size of response context. The unit is byte.
     # Collect the whole response header and body if this is not set.
     maxResponseSize: Int
 }

 # EBPFNetworkSamplingRule defines the URI scopes for HTTP request and response collecting under given HTTP response code circumstances.
 input EBPFNetworkSamplingRule {
     # The match pattern for HTTP request. This is HTTP URI-oriented.
     # matches all requests if not set
     uriRegex: String

     # the minimal request duration to activate the network data(HTTP request/response raw data) sampling.
     # Collecting requests without minimal request duration
     minDuration: Int
     # Collecting requests when the response code is 400-499
     when4xx: Boolean!
     # Collecting requests when the response code is 500-599
     when5xx: Boolean!

     # define the sampled data size and scopes.
     settings: EBPFNetworkDataCollectingSettings!
 }

 # The request of eBPF network profiling task
 input EBPFProfilingNetworkTaskRequest {
     # define which processes under the service instance need to be profiling
     instanceId: String!

     # The rule list for network profiling about collecting HTTP request and response raw data.
     # Set various rules for different HTTP URIs if necessary.
     samplings: [EBPFNetworkSamplingRule!]
 }

 # eBPF Profiling task creation result
 type EBPFProfilingTaskCreationResult {
     # TRUE if the task is created successfully
     status: Boolean!
     # error reason when status == FALSE
     errorReason: String

     # The task ID when status = TRUE
     id: String
 }

 # eBPF Profiling task keep alive result
 type EBPFNetworkKeepProfilingResult {
     # TRUE if the task is kept alive successfully
     # When one of the following conditions occurs, response in error status:
     # 1. The profiling task does not exist.
     # 2. The target type of profiling task is not "NETWORK".
     # 3. The profiling task is already finished when the OAP received keep-alive request.
     status: Boolean!
     # error reason when status == FALSE
     errorReason: String
 }

 # eBPF profiling task data
 type EBPFProfilingTask {
     # profiling task ID
     taskId: ID!
     # service of profiling task
     serviceId: ID!
     serviceName: String!
     # service instance of profiling task
     serviceInstanceId: ID
     serviceInstanceName: String
     # process labels for filter
     processLabels: [String!]!
     # process of profiling task triggered by continuous profiling
     processId: ID
     processName: String

     # Start time of the task, type is timestamp.
     taskStartTime: Long!
     # profiling task trigger type
     triggerType: EBPFProfilingTriggerType!
     # task profiling duration
     fixedTriggerDuration: Long
     # "CONTINUOUS_PROFILING" type task causes
     continuousProfilingCauses: [ContinuousProfilingTriggeredCause!]

     # profiling task target type
     targetType: EBPFProfilingTargetType!

     # the timestamp of creating this task
     createTime: Long!
 }

 type ContinuousProfilingTriggeredCause {
     # which type is reached the threshold
     # all causes threshold and current value has multiply with "100" for avoid float value
     type: ContinuousProfilingMonitorType!
     # single value based cause
     singleValue: ContinuousProfilingSingleValueCause
     # uri based cause
     uri: ContinuousProfilingURICause
 }

 enum ContinuousProfilingMonitorType {
     # monitoring Process CPU percent, value in [0-100]
     PROCESS_CPU,
     # monitoring process thread count, value must bigger than zero
     PROCESS_THREAD_COUNT,
     # monitoring current system load
     SYSTEM_LOAD,
     # monitoring the process HTTP response error(status>=500) percent, value in [0-100]
     HTTP_ERROR_RATE,
     # monitoring the process HTTP response duration(ms)
     HTTP_AVG_RESPONSE_TIME
 }

 type ContinuousProfilingSingleValueCause {
     # defined threshold
     threshold: Long!
     # current value of the process
     current: Long!
 }

 type ContinuousProfilingURICause {
     # which URI triggered threshold(one of)
     uriRegex: String
     uriPath: String
     # defined threshold
     threshold: Long!
     # current value of the process URI
     current: Long!
 }

 type EBPFProfilingSchedule {
     # profiling task schedule ID
     scheduleId: ID!
     # profiling task ID
     taskId: ID!
     # process entity
     process: Process!
     # profiling schedule start timestamp(ms)
     startTime: Long!
     # profiling schedule finished timestamp(ms)
     endTime: Long!
 }

 input EBPFProfilingAnalyzeTimeRange {
     # start timestamp(ms)
     start: Long!
     # end timestamp(ms)
     end: Long!
 }

 type EBPFProfilingAnalyzation {
     # if not empty means backend has information gave to the user
     tip: String
     # profiling analyzed trees
     trees: [EBPFProfilingTree!]!
 }

 type EBPFProfilingTree {
     # profiling stack elements
     elements: [EBPFProfilingStackElement!]!
 }

 type EBPFProfilingStackElement {
     # the element ID
     id: String!
     # the parent element ID
     parentId: String!
     # stack element symbol name
     symbol: String!
     # stack element type
     stackType: EBPFProfilingStackType!
     # current stack element total dump count
     dumpCount: Long!
 }

 # Prepare for creating the eBPF profiling task needs data
 type EBPFProfilingTaskPrepare {
     # have enough process could profiling
     couldProfiling: Boolean!
     # all process unique labels for filter
     processLabels: [String!]!
 }

 enum EBPFProfilingStackType {
     KERNEL_SPACE,
     USER_SPACE
 }

 # Define when the profiling task would be execute
 enum EBPFProfilingTriggerType {
     # Appoint the task executing total duration
     FIXED_TIME,
     # Trigger by the reach the continuous profiling policy
     CONTINUOUS_PROFILING
 }

 # The way of profiling the process
 # relate with Linux function: https://man7.org/linux/man-pages/man2/perf_event_open.2.html
 enum EBPFProfilingTargetType {
     # Using "PERF_COUNT_SW_CPU_CLOCK" to profiling process with CPU clock
     ON_CPU,
     # Using "finish_task_switch" of kprobe to profiling process
     # relate with blog: https://www.brendangregg.com/offcpuanalysis.html
     OFF_CPU,
     # Using many syscall to complete network topology monitoring, such as sys_connect, sys_read, sys_write, etc.
     NETWORK
 }

 enum EBPFProfilingAnalyzeAggregateType {
     # Aggregate by the total duration of stack
     # For "OFF_CPU" target type of profiling: Statics the total time spent in off cpu.
     DURATION,
     # Aggregate by the trigger count
     # For "ON_CPU" target type of profiling: Statics the number of dump count.
     # For "OFF_CPU" target type of profiling: Statics the number of times the process is switched to off cpu by the scheduler.
     COUNT
 }

 extend type Mutation {
     # create a new eBPF fixed time profiling task
     createEBPFProfilingFixedTimeTask(request: EBPFProfilingTaskFixedTimeCreationRequest!): EBPFProfilingTaskCreationResult!

     # create a new eBPF network profiling task
     createEBPFNetworkProfiling(request: EBPFProfilingNetworkTaskRequest!): EBPFProfilingTaskCreationResult!
     # keep alive the eBPF profiling task
     keepEBPFNetworkProfiling(taskId: ID!): EBPFNetworkKeepProfilingResult!
 }

 extend type Query {
     # query eBPF profiling data for prepare create task
     queryPrepareCreateEBPFProfilingTaskData(serviceId: ID!): EBPFProfilingTaskPrepare!
     # query eBPF profiling task list
     # query `triggerType == FIXED_TIME` when triggerType is absent
     queryEBPFProfilingTasks(serviceId: ID, serviceInstanceId: ID, targets: [EBPFProfilingTargetType!], triggerType: EBPFProfilingTriggerType, duration: Duration): [EBPFProfilingTask!]!
     # query schedules from profiling task
     queryEBPFProfilingSchedules(taskId: ID!): [EBPFProfilingSchedule!]!
     # analyze the profiling schedule
     # aggregateType is "EBPFProfilingAnalyzeAggregateType#COUNT" as default.
     analysisEBPFProfilingResult(scheduleIdList: [ID!]!, timeRanges: [EBPFProfilingAnalyzeTimeRange!]!, aggregateType: EBPFProfilingAnalyzeAggregateType): EBPFProfilingAnalyzation!
 }
	# 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 creation request of eBPF profiling fixed time task
	input EBPFProfilingTaskFixedTimeCreationRequest {
	# define which processes under the service need to be profiling
	serviceId: String!
	# aggregate which processes need to be profiling from labels
	processLabels: [String!]!

	# the task start timestamp(ms), if less then or equal zero means the task starts ASAP
	startTime: Long!
	# the profiling duration(s)
	duration: Int!

	# the task profiling target type
	targetType: EBPFProfilingTargetType!
	}

	# Settings for the behaviours of sampling.
	# HTTP request and response could be large between the system.
	# These settings help the agent to collect necessary data and cost reasonable resources for the agent, transforming, and OAP storage.
	input EBPFNetworkDataCollectingSettings {
	# Require to collect the complete request
	requireCompleteRequest: Boolean!
	# The max size of request context. The unit is byte.
	# Collect the whole request header and body if this is not set.
	maxRequestSize: Int

	# Require to collect the complete response
	requireCompleteResponse: Boolean!
	# The max size of response context. The unit is byte.
	# Collect the whole response header and body if this is not set.
	maxResponseSize: Int
	}

	# EBPFNetworkSamplingRule defines the URI scopes for HTTP request and response collecting under given HTTP response code circumstances.
	input EBPFNetworkSamplingRule {
	# The match pattern for HTTP request. This is HTTP URI-oriented.
	# matches all requests if not set
	uriRegex: String

	# the minimal request duration to activate the network data(HTTP request/response raw data) sampling.
	# Collecting requests without minimal request duration
	minDuration: Int
	# Collecting requests when the response code is 400-499
	when4xx: Boolean!
	# Collecting requests when the response code is 500-599
	when5xx: Boolean!

	# define the sampled data size and scopes.
	settings: EBPFNetworkDataCollectingSettings!
	}

	# The request of eBPF network profiling task
	input EBPFProfilingNetworkTaskRequest {
	# define which processes under the service instance need to be profiling
	instanceId: String!

	# The rule list for network profiling about collecting HTTP request and response raw data.
	# Set various rules for different HTTP URIs if necessary.
	samplings: [EBPFNetworkSamplingRule!]
	}

	# eBPF Profiling task creation result
	type EBPFProfilingTaskCreationResult {
	# TRUE if the task is created successfully
	status: Boolean!
	# error reason when status == FALSE
	errorReason: String

	# The task ID when status = TRUE
	id: String
	}

	# eBPF Profiling task keep alive result
	type EBPFNetworkKeepProfilingResult {
	# TRUE if the task is kept alive successfully
	# When one of the following conditions occurs, response in error status:
	# 1. The profiling task does not exist.
	# 2. The target type of profiling task is not "NETWORK".
	# 3. The profiling task is already finished when the OAP received keep-alive request.
	status: Boolean!
	# error reason when status == FALSE
	errorReason: String
	}

	# eBPF profiling task data
	type EBPFProfilingTask {
	# profiling task ID
	taskId: ID!
	# service of profiling task
	serviceId: ID!
	serviceName: String!
	# service instance of profiling task
	serviceInstanceId: ID
	serviceInstanceName: String
	# process labels for filter
	processLabels: [String!]!
	# process of profiling task triggered by continuous profiling
	processId: ID
	processName: String

	# Start time of the task, type is timestamp.
	taskStartTime: Long!
	# profiling task trigger type
	triggerType: EBPFProfilingTriggerType!
	# task profiling duration
	fixedTriggerDuration: Long
	# "CONTINUOUS_PROFILING" type task causes
	continuousProfilingCauses: [ContinuousProfilingTriggeredCause!]

	# profiling task target type
	targetType: EBPFProfilingTargetType!

	# the timestamp of creating this task
	createTime: Long!
	}

	type ContinuousProfilingTriggeredCause {
	# which type is reached the threshold
	# all causes threshold and current value has multiply with "100" for avoid float value
	type: ContinuousProfilingMonitorType!
	# single value based cause
	singleValue: ContinuousProfilingSingleValueCause
	# uri based cause
	uri: ContinuousProfilingURICause
	}

	enum ContinuousProfilingMonitorType {
	# monitoring Process CPU percent, value in [0-100]
	PROCESS_CPU,
	# monitoring process thread count, value must bigger than zero
	PROCESS_THREAD_COUNT,
	# monitoring current system load
	SYSTEM_LOAD,
	# monitoring the process HTTP response error(status>=500) percent, value in [0-100]
	HTTP_ERROR_RATE,
	# monitoring the process HTTP response duration(ms)
	HTTP_AVG_RESPONSE_TIME
	}

	type ContinuousProfilingSingleValueCause {
	# defined threshold
	threshold: Long!
	# current value of the process
	current: Long!
	}

	type ContinuousProfilingURICause {
	# which URI triggered threshold(one of)
	uriRegex: String
	uriPath: String
	# defined threshold
	threshold: Long!
	# current value of the process URI
	current: Long!
	}

	type EBPFProfilingSchedule {
	# profiling task schedule ID
	scheduleId: ID!
	# profiling task ID
	taskId: ID!
	# process entity
	process: Process!
	# profiling schedule start timestamp(ms)
	startTime: Long!
	# profiling schedule finished timestamp(ms)
	endTime: Long!
	}

	input EBPFProfilingAnalyzeTimeRange {
	# start timestamp(ms)
	start: Long!
	# end timestamp(ms)
	end: Long!
	}

	type EBPFProfilingAnalyzation {
	# if not empty means backend has information gave to the user
	tip: String
	# profiling analyzed trees
	trees: [EBPFProfilingTree!]!
	}

	type EBPFProfilingTree {
	# profiling stack elements
	elements: [EBPFProfilingStackElement!]!
	}

	type EBPFProfilingStackElement {
	# the element ID
	id: String!
	# the parent element ID
	parentId: String!
	# stack element symbol name
	symbol: String!
	# stack element type
	stackType: EBPFProfilingStackType!
	# current stack element total dump count
	dumpCount: Long!
	}

	# Prepare for creating the eBPF profiling task needs data
	type EBPFProfilingTaskPrepare {
	# have enough process could profiling
	couldProfiling: Boolean!
	# all process unique labels for filter
	processLabels: [String!]!
	}

	enum EBPFProfilingStackType {
	KERNEL_SPACE,
	USER_SPACE
	}

	# Define when the profiling task would be execute
	enum EBPFProfilingTriggerType {
	# Appoint the task executing total duration
	FIXED_TIME,
	# Trigger by the reach the continuous profiling policy
	CONTINUOUS_PROFILING
	}

	# The way of profiling the process
	# relate with Linux function: https://man7.org/linux/man-pages/man2/perf_event_open.2.html
	enum EBPFProfilingTargetType {
	# Using "PERF_COUNT_SW_CPU_CLOCK" to profiling process with CPU clock
	ON_CPU,
	# Using "finish_task_switch" of kprobe to profiling process
	# relate with blog: https://www.brendangregg.com/offcpuanalysis.html
	OFF_CPU,
	# Using many syscall to complete network topology monitoring, such as sys_connect, sys_read, sys_write, etc.
	NETWORK
	}

	enum EBPFProfilingAnalyzeAggregateType {
	# Aggregate by the total duration of stack
	# For "OFF_CPU" target type of profiling: Statics the total time spent in off cpu.
	DURATION,
	# Aggregate by the trigger count
	# For "ON_CPU" target type of profiling: Statics the number of dump count.
	# For "OFF_CPU" target type of profiling: Statics the number of times the process is switched to off cpu by the scheduler.
	COUNT
	}

	extend type Mutation {
	# create a new eBPF fixed time profiling task
	createEBPFProfilingFixedTimeTask(request: EBPFProfilingTaskFixedTimeCreationRequest!): EBPFProfilingTaskCreationResult!

	# create a new eBPF network profiling task
	createEBPFNetworkProfiling(request: EBPFProfilingNetworkTaskRequest!): EBPFProfilingTaskCreationResult!
	# keep alive the eBPF profiling task
	keepEBPFNetworkProfiling(taskId: ID!): EBPFNetworkKeepProfilingResult!
	}

	extend type Query {
	# query eBPF profiling data for prepare create task
	queryPrepareCreateEBPFProfilingTaskData(serviceId: ID!): EBPFProfilingTaskPrepare!
	# query eBPF profiling task list
	# query `triggerType == FIXED_TIME` when triggerType is absent
	queryEBPFProfilingTasks(serviceId: ID, serviceInstanceId: ID, targets: [EBPFProfilingTargetType!], triggerType: EBPFProfilingTriggerType, duration: Duration): [EBPFProfilingTask!]!
	# query schedules from profiling task
	queryEBPFProfilingSchedules(taskId: ID!): [EBPFProfilingSchedule!]!
	# analyze the profiling schedule
	# aggregateType is "EBPFProfilingAnalyzeAggregateType#COUNT" as default.
	analysisEBPFProfilingResult(scheduleIdList: [ID!]!, timeRanges: [EBPFProfilingAnalyzeTimeRange!]!, aggregateType: EBPFProfilingAnalyzeAggregateType): EBPFProfilingAnalyzation!
	}