InvokeDiagnosis - Alibaba Cloud Linux - Alibaba Cloud Documentation Center

Operation description

The following requirements must be met to diagnose a target ECS instance:

The target ECS instance status must be Running.
Cloud Assistant must be installed on the target ECS instance. If it is not installed, refer to Install the Cloud Assistant Agent for installation.
You must invoke the AuthDiagnosis operation to authorize SysOM to diagnose the target ECS instance. If authorization is not granted, this operation directly fails.
This operation depends on the SysOM service-linked role (AliyunServiceRoleForSysom) being created. This operation does not automatically create the service-linked role. If the service-linked role does not exist, first invoke AuthDiagnosis to associate the authorization. That operation creates the aforementioned service-linked role.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

sysom:InvokeDiagnosis

create

*Diagnosis

acs:sysom::{#accountId}:diagnosis/*

None

Request syntax

POST /api/v1/openapi/diagnosis/invoke_diagnosis HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
body	object	No	The request body parameters.
channel	string	Yes	The diagnostic channel. Currently fixed to the ECS channel. Valid values: ecs : ECS channel.	ecs
params	string	Yes	The diagnostic parameters. Different diagnostic types require different parameters. For the parameters required by each diagnostic type, see the supplementary description of request parameters below. Important Pass a JSON-formatted string.	{ "instance": "i-wz9gdv7qmdhusamc4dl01", "uid": "xxxxxxxxxxxxxx", "region": "cn-shenzhen" }
service_name	string	Yes	The diagnostic type. Specifies the type of diagnostic to perform. Valid values: iofsstat : I/O traffic analysis. iodiagnose : One-click I/O diagnostics. oomcheck : OOM diagnostics. diskanalysis : Disk analysis diagnostics. javamem : Java memory diagnostics. iolatency : I/O latency analysis. netjitter : Network jitter diagnostics. loadtask : System load diagnostics. vmcore : Crash diagnostics. packetdrop : Network packet loss diagnostics. memgraph : Memory overview diagnostics.	memgraph

Diagnostic parameter description

Memory overview diagnostics (memgraph) parameters

The memgraph (memory panoramic analysis) tool is designed for scenarios where memory usage is high but the specific memory consumption cannot be clearly identified. By using the memory panoramic analysis diagnostic feature, you can scan the current system memory usage and obtain a detailed breakdown of memory usage. The tool shows the distribution of system memory and application memory, and lists the top 30 application memory usage, file cache, and shared memory cache usage rankings.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.
pod	string	Pod name	No		The pod name.

Java memory diagnostics (javamem) parameters

The javamem (Java memory diagnostics) tool is used to diagnose the memory usage of Java applications. It helps you understand the distribution and composition of Java heap memory and non-heap memory, identify potential memory leaks and out-of-memory issues, and achieve observable, measurable, and traceable Java memory management.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.
Pid	string	Java process PID	No		The PID of the Java process. Specify at least one of Pid or pod.
pod	string	Pod name	No		The pod name. Specify at least one of pid or pod.
duration	string	JNI memory allocation profiling duration	No		The JNI memory allocation profiling duration. To perform JNI diagnostics, specify a non-zero value. Otherwise, JNI diagnostics is not performed by default.

Memory OOM diagnostics (oomcheck) parameters

The oomcheck (OOM diagnostics) tool is used to analyze and identify OOM (Out of Memory) issues, determine the root cause of OOM events, and provide corresponding recommendations to help you resolve OOM issues and improve system availability and performance.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.
pod	string	Pod name	No		The pod name.
time	string	Diagnostic time	No		Enter the point in time for OOM diagnostics. The default value is the most recent occurrence.

System load diagnostics (loadtask) parameters

The loadtask (system load diagnostics) tool analyzes the causes of abnormal average load (load1 metric) over one minute and provides detailed information.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.

Scheduling jitter diagnostics (delay) parameters

The delay (scheduling jitter diagnostics) tool analyzes issues caused by the CPU not performing task switching for an extended period, which prevents user-space processes from being scheduled (for example, during memory reclamation).

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.
duration	string	Diagnostic duration	No	20	The diagnostic duration in seconds. Default value: 20.
threshold	string	Diagnostic threshold	No	20	The latency threshold. Events exceeding this threshold are recorded. Default value: 20 ms.

I/O traffic analysis diagnostics (iofsstat) parameters

The iofsstat (I/O traffic analysis) tool analyzes the attribution of I/O traffic in the system. The results include I/O traffic statistics for each disk or partition and I/O traffic statistics for each process.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. I/O traffic statistics are collected inside this instance.
timeout	string	Diagnostic duration	No	15	The diagnostic duration, which is also the I/O traffic statistics collection period. Unit: seconds. Do not exceed 60 seconds.
disk	string	Target disk	No	""	Enter the disk to diagnose, such as vda or sda. By default, all disks are diagnosed.

One-click I/O diagnostics (iodiagnose) parameters

The iodiagnose (one-click I/O diagnostics) tool focuses on frequently occurring issues such as high I/O latency, I/O burst, and I/O wait. It identifies various I/O issue types and invokes the corresponding sub-tools to analyze I/O data, providing conclusions and recommendations.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. I/O hang diagnostics is initiated inside this instance.
timeout	string	Diagnostic duration	No	30	The diagnostic duration in seconds. Default value: 30. Set this value to at least 30 seconds.

Network packet loss diagnostics (packetdrop) parameters

The packetdrop (network packet loss diagnostics) tool analyzes packet loss issues that occur at the operating system kernel level during network transmission due to various causes.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.

Network jitter diagnostics (netjitter) parameters

The netjitter (network jitter diagnostics) tool analyzes instability at the operating system kernel level caused by various factors during network packet transmission.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.
duration	string	Diagnostic duration	No	20	The diagnostic duration in seconds. Default value: 20.
threshold	string	Jitter threshold	No	10	The threshold in milliseconds for determining jitter. Default value: 10 ms.

Crash diagnostics (vmcore) parameters

The vmcore (crash diagnostics) tool analyzes the causes of operating system crashes. It analyzes the core dump file generated by a kernel panic, combined with dmesg logs, to determine the cause of the crash.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.

Disk analysis diagnostics (diskanalysis) parameters

The diskanalysis (disk analysis diagnostics) tool analyzes disk usage in the system.

Parameter	Type	Parameter description	Required	Default	Remarks
uid	string	User UID	Yes		The user UID.
region	string	Instance region	Yes		The region where the instance resides.
instance	string	Instance ID	Yes		Enter the ID of the instance to diagnose. The diagnostic is initiated inside this instance.

Response elements

Element	Type	Description	Example
	object	Schema of Response
code	string	The status code. `code == Success` indicates that the authorization is successful. Other status codes indicate that the authorization has failed. Check the `message` field for the detailed fault information.	Success
data	object	The returned result.
task_id	string	The diagnostic task ID. You can use this ID to call the `GetDiagnosisResult` operation to query the diagnostic result.	ihqhAcrt
message	string	The error message. If `code == Success`, this field is empty. Otherwise, this field contains the request error message.	SysomOpenAPIAssumeRoleException: EntityNotExist.Role The role not exists: acs:ram::xxxxx:role/aliyunserviceroleforsysom
request_id	string	The request ID.	43A910E9-A739-525E-855D-A32C257F1826

Examples

Success response

JSON format

{
  "code": "Success",
  "data": {
    "task_id": "ihqhAcrt"
  },
  "message": "SysomOpenAPIAssumeRoleException: EntityNotExist.Role The role not exists: acs:ram::xxxxx:role/aliyunserviceroleforsysom",
  "request_id": "43A910E9-A739-525E-855D-A32C257F1826"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.