Updated on 2025-08-07 GMT+08:00

Reporting Events and Alarms

Function

This API is used to report events and alarms to AOM. It is also used to clear alarms.

Calling Method

For details, see Calling APIs.

URI

PUT /v2/{project_id}/push/events

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID, which can be obtained from the console or by calling an API. For details, see Obtaining a Project ID.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

action

No

String

Requested action.

  • If this parameter is not transferred or other values are transferred, an alarm or event is to be reported. By default, this parameter is left blank, indicating that an alarm or event is to be reported.

  • clear: An alarm is to be cleared.

Enumeration values:

  • clear

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token obtained from IAM. For details, see Obtaining a Token.

Content-Type

Yes

String

Message body type or format. Content type, which is application/json.

Enumeration values:

  • application/json

enterprise-project-id

No

String

ID of the enterprise project to which the alarm belongs. For details, see Obtaining an Enterprise Project ID.

If this parameter is not transferred, the default enterprise project will be used (ID: 0).

Table 4 Request body parameters

Parameter

Mandatory

Type

Description

events

Yes

Array of EventModel objects

Event or alarm details.

Table 5 EventModel

Parameter

Mandatory

Type

Description

starts_at

No

Long

Time when an event or alarm is generated (UTC timestamp precise down to the millisecond).

Example: 2024-10-16 16:03:01 needs to be converted to UTC timestamp 1702759381000 using a tool.

This parameter needs to be specified if the value of action is left blank (which indicates that an event or alarm is to be reported).

ends_at

No

Long

Time when an event or alarm is cleared (UTC timestamp precise down to the millisecond). 0 (default): The alarm is not cleared.

Example: 2024-10-16 16:03:01 needs to be converted to UTC timestamp 1702759381000 using a tool.

This parameter needs to be specified if the value of action is set to clear.

timeout

No

Long

After how long will an alarm be automatically cleared. Unit: ms. For example, if an alarm is cleared after 1 minute, set this parameter to 60000 By default, alarms older than five days will be cleared. The corresponding value is 7,200 × 60,000 (5 days × 24 hours × 60 minutes × 60,000 ms). Max.: 15 days.This parameter needs to be specified if the value of action is left blank (which indicates that an alarm is to be reported).

metadata

Yes

Map<String,String>

Details about an event or alarm to be reported. The value is a key-value pair. Mandatory fields:

  • event_name: event or alarm name, which is a string.

  • event_severity: event or alarm severity, which is a string. Options:

    • Critical

    • Major

    • Minor

    • Info

  • event_type: event or alarm type, which is a string. Options:

    • event

    • alarm

  • resource_provider: name of a cloud service corresponding to an event, which is a string.

  • resource_type: type of the resource corresponding to an event, which is a string.

  • resource_id: resource ID corresponding to an event, which is a string.

Length: 1 to 2,048 characters.

annotations

No

Map<String,Object>

Additional field for an event or alarm, which can be left blank.

attach_rule

No

Map<String,Object>

Reserved field for an event or alarm, which can be left blank.

id

No

String

Event or alarm ID, which is automatically generated when an event or alarm is generated.

This parameter needs to be specified if the value of action is set to clear.

Response Parameters

Status code: 204

No Content: The request is successful, but no content is returned.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error description.

error_type

String

API call failure type.

trace_id

String

Request ID.

Example Requests

Report an alarm named "test".

https://{EndPoint}/v2/{project_id}/push/events

{
  "events" : [ {
    "starts_at" : 1605232501000,
    "timeout" : 60000,
    "metadata" : {
      "event_name" : "test",
      "event_severity" : "Major",
      "event_type" : "alarm",
      "resource_provider" : "ecs",
      "resource_type" : "vm",
      "resource_id" : "ecs123"
    },
    "annotations" : {
      "alarm_probableCause_zh_cn" : "Possible Causes",
      "alarm_fix_suggestion_zh_cn" : "Suggestions",
      "message" : "Alarm Details"
    },
    "attach_rule" : { }
  } ]
}

Example Responses

Status code: 400

Bad Request: The request is invalid. The client should not repeat the request without modifications.

{
  "error_code" : "AOM.0400",
  "error_msg" : "parse eventParam failed",
  "error_type" : "SC_BAD_REQUEST"
}

Status Codes

Status Code

Description

204

No Content: The request is successful, but no content is returned.

400

Bad Request: The request is invalid. The client should not repeat the request without modifications.

401

Unauthorized: The authentication information is incorrect or invalid.

403

Forbidden: The request is rejected. The server has received the request and understood it, but the server refuses to respond to it. The client should not repeat the request without modifications.

500

Internal Server Error: The server is able to receive the request but unable to understand the request.

503

Service Unavailable: The requested service is invalid. The client should not repeat the request without modifications.

Error Codes

See Error Codes.