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

Adding Monitoring Data

Function

This API is used to add one or more pieces of custom metric monitoring data to solve the problem that the system metrics cannot meet specific service requirements.

For details about the monitoring data retention period, see How Long Is Metric Data Retained? in Cloud Eye User Guide.

Debugging

You can debug the API in API Explorer which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.

URI

POST /V1.0/{project_id}/metric-data

  • Parameter description
    Table 1 Parameter description

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Definition

    Project ID, which is used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID from the API or console. For details about how to obtain the project ID, see Obtaining a Project ID.

    Constraints

    N/A

    Range

    1 to 64 characters

    Default Value

    N/A

  • Example
    POST https://{Cloud Eye endpoint}/V1.0/{project_id}/metric-data

For details about Cloud Eye endpoints, go to Endpoints to query the URL of each region.

Request

  1. The size of a POST request cannot exceed 512 KB. Otherwise, the request will be denied.
  2. The period for sending POST requests must be shorter than the minimum aggregation period. Otherwise, the aggregated data will be noncontinuous. For example, if the aggregation period is 5 minutes and the POST request sending period is 7 minutes, the data will be aggregated every 10 minutes, rather than 5 minutes.
  3. Timestamp (collect_time) in the POST request body value must be within the period that starts from three days before the current time to 10 minutes after the current time. If it is not in this range, you are not allowed to insert the metric data.
  • Request parameters
    Table 2 Parameter description

    Parameter

    Type

    Mandatory

    Description

    Array elements

    Array of objects

    Yes

    Definition

    Request parameters for adding one or more pieces of custom metric data record.

    For details, see Table 3.

    Constraints

    At least one metric data record must be added. A maximum of 10,000 metric data records are allowed. The message body of a single POST request cannot exceed 512 KB.

    Table 3 Array elements

    Parameter

    Mandatory

    Type

    Description

    metric

    Yes

    Object

    Definition

    Metric data.

    For details, see Table 4.

    Constraints

    N/A

    ttl

    Yes

    Integer

    Definition

    Data validity period, in seconds. If the validity period expires, data will be automatically deleted.

    Constraints

    N/A

    Range

    1 to 604800

    Default Value

    N/A

    collect_time

    Yes

    Long

    Definition

    Time when the data was collected. The value is a UNIX timestamp, in milliseconds.

    Constraints

    N/A

    Range

    Since there is a latency between the client and the server, the timestamp when data was inserted must be within the time range [Current time – 3d + 10s, Current time + 10 mins – 10s]. In this way, the data will be inserted to the database without being affected by the latency.

    Default Value

    N/A

    value

    Yes

    Double

    Definition

    Value of the monitored metric data to be added.

    Constraints

    N/A

    Range

    The value can be an integer or a floating point number.

    Default Value

    N/A

    unit

    No

    String

    Definition

    Data unit.

    Constraints

    N/A

    Range

    0 to 32

    Default Value

    N/A

    type

    No

    String

    Definition

    Data type.

    Constraints

    N/A

    Range

    The value can be:

    • int: integer
    • float: floating point number

    Default Value

    N/A

    Table 4 metric data structure description

    Parameter

    Mandatory

    Type

    Description

    namespace

    Yes

    String

    Definition

    Custom namespace. For details, see Services Interconnected with Cloud Eye.

    Constraints

    N/A

    Range

    The namespace must be in the service.item format. service and item must be strings, and each must start with a letter and contain only letters (case-insensitive), digits, and underscores (_). In addition, service cannot start with SYS, AGT, or SRE. namespace cannot be SERVICE.BMS because this namespace has been used by the system. The value can contain 3 to 32 characters. For example, the ECS namespace is SYS.ECS, and the DDS namespace is SYS.DDS.

    Default Value

    N/A

    dimensions

    Yes

    Array of objects

    Definition

    Dimension of a metric. For details, see Table 5.

    Constraints

    A maximum of four dimensions are supported.

    metric_name

    Yes

    String

    Definition

    Metric ID. For example, metric_name of ECS CPU usage is cpu_util. For details about the metrics of each service, see Services Interconnected with Cloud Eye.

    Constraints

    N/A

    Range

    The value must start with a letter and can contain only digits, letters (case-insensitive), underscores (_), and hyphens (-). For example, the ECS metric cpu_util indicates the CPU usage of an ECS. The DDS metric mongo001_command_ps indicates the command execution frequency. The value can contain 1 to 96 characters.

    Default Value

    N/A

    Table 5 dimensions data structure description

    Parameter

    Mandatory

    Type

    Description

    name

    Yes

    String

    Definition

    Monitoring dimension name. For example, the dimension of an ECS is instance_id. For details about the dimension of each service, see the key column in Services Interconnected with Cloud Eye.

    Constraints

    The value allows 1 to 32 characters. It must start with a letter and can contain only digits, letters, underscores (_), and hyphens (-).

    Range

    N/A

    Default Value

    N/A

    value

    Yes

    String

    Definition

    Dimension value, for example, an ECS ID.

    Constraints

    N/A

    Range

    The value allows 1 to 256 characters. It must start with a letter or digit and can contain only digits, letters, underscores (_), and hyphens (-).

    Default Value

    N/A

  • Example request
    Example request 1: Add cpu_util data of a custom dimension. The instance ID is 6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d.
    [
        {
            "metric": {
                "namespace": "MINE.APP",
                "dimensions": [
                    {
                        "name": "instance_id",
                        "value": "6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d"
                    }
                ],
                "metric_name": "cpu_util"
            },
            "ttl": 172800,
            "collect_time": 1463598260000,
            "type": "float",
            "value": 0.09,
            "unit": "%"
        },
        {
            "metric": {
                "namespace": "MINE.APP",
                "dimensions": [
                    {
                        "name": "instance_id",
                        "value": "6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d"
                    }
                ],
                "metric_name": "cpu_util"
            },
            "ttl": 172800,
            "collect_time": 1463598270000,
            "type": "float",
            "value": 0.12,
            "unit": "%"
        }
    ]
    Example request 2: Add rds021_myisam_buf_usage data of the RDS instance whose rds_cluster_id is 3c8cc15614ab46f5b8743317555e0de2in01.
    [
        {
            "metric": {
                "namespace": "SYS.RDS",
                "dimensions": [
        {
                        "name": "rds_cluster_id",
                        "value": "3c8cc15614ab46f5b8743317555e0de2in01"
                    }
                ],
                "metric_name": "rds021_myisam_buf_usage"
            },
            "ttl": 172800,
            "collect_time": 1463598260000,
            "type": "float",
            "value": 0.01,
            "unit": "Ratio"
        }
    ]
    Example request 3: Add connections_usage data of the DCS instance whose dcs_instance_id is 1598b5d4-3cb5-4f4d-8d99-2425d8e9ed54 and dcs_cluster_redis_node is 6666cd76f96956469e7be39d750cc7d9.
    [
        {
            "metric": {
                "namespace": "SYS.DCS",
                "dimensions": [
        {
                        "name": "dcs_instance_id",
                        "value": "1598b5d4-3cb5-4f4d-8d99-2425d8e9ed54"
            },
        {
                        "name": "dcs_cluster_redis_node",
                        "value": "6666cd76f96956469e7be39d750cc7d9"
                    }
                ],
                "metric_name": "connections_usage"
            },
            "ttl": 172800,
            "collect_time": 1463598260000,
            "type": "float",
            "value": 8.3,
            "unit": "%"
        }
    ]

Response

The response has no message body.

Returned Values

  • Normal

    201

  • Abnormal

    Returned Value

    Description

    400 Bad Request

    Request error.

    401 Unauthorized

    The authentication information is not provided or is incorrect.

    403 Forbidden

    Access to the requested page is forbidden.

    408 Request Timeout

    The request timed out.

    429 Too Many Requests

    Concurrent requests are excessive.

    500 Internal Server Error

    Failed to complete the request because of an internal service error.

    503 Service Unavailable

    The service is currently unavailable.

Error Codes

See Error Codes.