Query monitoring data by tag|V4.3.5|OceanBase Cloud Platform|docs|OceanBase Documentations

Query monitoring data by tag

Last Updated：2026-09-04 02:20:48 Updated

Feature description

Queries monitoring data of specified metrics and the values of the group tags. The query time interval and metric array must be specified. The query range is specified by the tags, and the data is summarized by the specified tags. The query result contains several groups, each group contains time series data.

Call instructions

Interface constraints

The caller must be authenticated by using the OCP application service.

Request path

GET /api/v2/monitor/metricsWithLabel

Request parameters

body:

Parameter	Type	Required	Example Value	Description
startTime	Datetime	Yes	2020-02-16T05:32:16+08:00	The start time of the monitored data.
endTime	Datetime	Yes	2020-02-16T07:32:16+08:00	The end time of the monitored data.
metrics	StringArray	Yes	io_read_time,io_write_time	The array of monitored metrics.
groupBy	StringArray	Yes	app,ob_cluster_name,ob_cluster_id	The summary labels of the monitored data.
interval	Integer	Yes	60	The time granularity of the monitored data, in seconds.
minStep	Integer	No	10	The query sampling interval, which represents the minimum sampling interval for the monitored results. The default value is 0.
maxPoints	Integer	No	360	The maximum number of points of the monitored results. The default value is 1440.
labels	StringArray	Yes	app:ob,ob_cluster_name=foo	The filter conditions of the monitored data.

Note

Starting from OCP V4.2.1, the parameter name obregion is updated to ob_cluster_name. The parameter is still valid for interface calls.

Return result

Basic data structure

Parameter	Type	Description
data	Object	The requested data.
├─ contents	Array	The array of monitoring samples. The data structure of the monitoring samples varies based on the monitoring metrics queried. For more information, see Monitoring sample group data structure.
├─ page	Object	The pagination information. For more information, see page data structure.
successful	Boolean	Indicates whether the request is successful.
timestamp	Datetime	The timestamp when the server finishes the request.
duration	Integer	The time taken by the server to process the request, in milliseconds.
status	Integer	The HTTP status code that conforms to the HTTP status specification.
traceId	String	The Trace ID of the request, which is used to troubleshoot issues.
server	String	The address of the server that responds to the request.

Monitoring sample group data structure

Parameter	Type	Description
LabelA	String	The value of the corresponding label.
LabelB	String	The value of the corresponding label.
data	Array	The array of monitoring samples. The data structure of the monitoring samples varies based on the monitoring metrics queried. For more information, see Monitoring sample data structure.

Monitoring sample data structure

Parameter	Type	Description
timestamp	Integer	The sampling time point, which is the number of seconds since 1970-01-01 00:00:00.
MetricA	Float	The sampling value of the corresponding metric.
MetricB	Float	The sampling value of the corresponding metric.

page data structure

Parameter	Type	Description
totalElements	Integer	The total number of records.
totalPages	Integer	The total number of pages.
number	Integer	The current page number.
size	Integer	The size of the current page.

Example

Request example

Request monitoring data from 2020-11-11 18:30:00.000+08:00 to 2020-11-11 19:00:00.000+08:00; the monitoring metric is sql_all_count, and the output time granularity is 1 second; the filter condition is app=ob; the monitoring data is aggregated by the app, ob_cluster_name, and ob_cluster_id tags:

api/v2/monitor/metricsWithLabel?labels=app%3Aob&groupBy=app%2Cob_cluster_name%2Cob_cluster_id&metrics=sql_all_count&interval=1&limit=5&startTime=2025-05-19T18%3A30%3A00.000%2B08%3A00&endTime=2025-05-19T19%3A00%3A00.000%2B08%3A00

Response example

{
    "duration": 514,
    "server": "a83ad33525",
    "status": 200,
    "successful": true,
    "timestamp": "2020-11-17T19:19:30.209+08:00",
    "traceId": "d972475d85b0405a",
    "data": {
        "contents": [
            {
                "app": "OB",
                "ob_cluster_name": "ob1",
               "ob_cluster_id": "2",
                "data": [
                    {
                        "sql_all_count": 38.00,
                        "timestamp": 1605608370
                    },
                    {
                        "sql_all_count": 43.50,
                        "timestamp": 1605608372
                    },
                    {
                        "sql_all_count": 38.50,
                        "timestamp": 1605608374
                    }
                ]
            },
            {
                "app": "OB",
                "ob_cluster_name": "ob2",
               "ob_cluster_id": "3",
                "data": [
                    {
                        "sql_all_count": 85.00,
                        "timestamp": 1605608370
                    },
                    {
                        "sql_all_count": 91.00,
                        "timestamp": 1605608372
                    },
                    {
                        "sql_all_count": 187.50,
                        "timestamp": 1605608374
                    }
                ]
            }
        ],
        "page": {
            "number": 2,
            "size": 2147483647,
            "totalElements": 3,
            "totalPages": 1
        }
    }
}

OceanBase

Customer Stories

Documentation