ebpf-profiling.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 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
    # summary message of cause, including type, value or uri
    message: String!
}

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