Call the DescribeHistoryMonitorValues API to query historical performance data - Tair (Redis® OSS-Compatible) - Alibaba Cloud - Tair (Redis® OSS-Compatible)

Operation description

For the console equivalent, see performance monitoring.

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

kvstore:DescribeHistoryMonitorValues

get

*DBInstance

acs:kvstore:{#regionId}:{#accountId}:instance/{#instanceId}

kvstore:ResourceTag
kvstore:ResourceTag
kvstore:ResourceTag
kvstore:ResourceTag

None

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The ID of the instance.	r-bp1zxszhcgatnx******
StartTime	string	Yes	The beginning of the time range to query. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.	2022-11-06T00:00:00Z
EndTime	string	Yes	The end of the time range to query. The end time must be later than the start time. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Note You can query monitoring data within the past month. The maximum time range to query is 7 days.	2022-11-06T00:30:00Z
IntervalForHistory	string	Yes	This parameter is deprecated and its value is fixed at `01m`. The system automatically determines the query interval based on the specified start and end times. For example, if the specified time range is 10 minutes or less, data is aggregated every 5 seconds, and the query results are returned at 5-second intervals. Note If the specified `StartTime` is not at a data aggregation point, the first time point returned by the system is the nearest preceding data aggregation point. For example, if you set StartTime to `2022-01-20T12:01:48Z`, the first time point returned is `2022-01-20T12:01:45Z`. If the instance has 32 or more data shards, the minimum data aggregation frequency is 1 minute.	01m
MonitorKeys	string	No	The monitoring metric to query, such as `CpuUsage`. To specify multiple metrics, separate them with a comma (,). For instances that use the cluster or read/write splitting architecture: To query the overall CPU utilization of all data nodes, set this parameter to CpuUsage$db. To query the CPU utilization of a single data node, set this parameter to CpuUsage and specify the node in the `NodeId` parameter. For instances that use the standard architecture (primary/standby), set this parameter to CpuUsage. For more information about monitoring metrics, see Additional information about the MonitorKeys parameter below. Note If you do not specify this parameter, the `UsedMemory` and `quotaMemory` metrics are returned by default. To ensure query efficiency, we recommend that you specify a maximum of 5 monitoring metrics for a single node and a maximum of 1 aggregate monitoring metric per query.	CpuUsage
NodeId	string	No	The ID of a node in the instance. You can use this parameter to query the monitoring data of a specific node. Note This parameter is available only for instances that use the read/write splitting or cluster architecture. You can call the DescribeLogicInstanceTopology operation to query node IDs.	r-bp1zxszhcgatnx**-db-0#1679**
NodeRole	string	No	If you want to query the metrics of a read-only node in a cloud-native instance that uses a read/write splitting architecture, you must specify the NodeId and set this parameter to READONLY. Note In all other cases, you do not need to specify this parameter. You can also set it to MASTER.	READONLY
Type	string	No

MonitorKeys parameter

When you make an API call, pass a parameter from the MonitorKeys column in the following tables. The API returns the corresponding sub-metrics. An instance supports both general-purpose metrics and command statistics metrics.

General-purpose metrics

This section describes how to use general-purpose metrics, using CpuUsage as an example.

For instances that use the cluster or read/write splitting architecture:
- To query the overall CPU utilization of all data nodes (DB), pass CpuUsage$db.
- To query the overall CPU utilization of all proxy nodes, pass CpuUsage$proxy.
- To query the CPU utilization of a single data node or proxy node, pass CpuUsage and set the NodeId parameter to the ID of the data or proxy node.
For instances that use the standard architecture (primary/standby), pass CpuUsage.

MonitorKeys	Sub-metric	Unit	Description	Supported scope
CpuUsage	CpuUsage	%	CPU utilization. The value ranges from 0 to 100. Note If your instance previously used the `RedisCpuUsage` parameter, you can continue to use it.	DB DB aggregate Proxy Proxy aggregate
MemoryUsage	memoryUsage	%	Memory usage.	DB DB aggregate
quotaMemory	quotaMemory	Bytes	The total memory of the current shard.	DB DB aggregate
UsedMemory	UsedMemory	Bytes	Used memory, which includes data and cache.	DB DB aggregate
Tair_PmemUsage	PmemUsage	%	These metrics represent the persistent memory usage, used persistent memory, and total persistent memory, respectively. Supported only by persistent memory instances.	DB DB aggregate
Tair_Pmem	PmemUsed	Bytes
Tair_Pmem	PmemQuota	Bytes
Redis_DetailedSpaceUsage	ins_size	MB	These metrics represent the total disk space occupied by the instance, the disk space occupied by data files (including AOF and RDB files), and the disk space occupied by log files (including runtime logs), respectively. Supported only by memory-optimized instances that use the classic deployment mode (local disks).	DB DB aggregate
	data_size	MB
	log_size	MB
Redis_Memory_Monitor	used_memory_rss	Bytes	The physical memory that the operating system allocates to the Tair process.	DB
	used_memory_lua	Bytes	The amount of memory used by Lua scripts.
	used_memory_startup	Bytes	The memory consumed when Tair starts.
	lazyfree_pending_objects	Counts	The number of keys pending reclamation when Tair performs a lazy free operation.
	used_memory_overhead	Bytes	The memory overhead required by Tair to maintain its internal data structures. This includes the output buffers of all clients, query buffers, and AOF.
	used_memory_dataset	Bytes	The memory space occupied by data.
CustomerMemoryUsage	CustomerMemoryUsage	%	User memory usage. The value ranges from 0 to 100.	DB DB aggregate
UsedQPS	TotalQps	Counts/s	The total number of requests per second, including read and write commands.	DB DB aggregate Proxy Proxy aggregate
	GetQps	Counts/s	The number of read and write requests per second, respectively. The instance must be compatible with Redis 4.0 or later.
	PutQps	Counts/s
	OtherOps	Counts/s	The number of requests that do not have read or write attributes, such as `PING`, `INFO`, `SELECT`, and `AUTH`. Because proxy nodes have special processing for requests, if the instance has proxy nodes, this metric includes only some `INFO` requests.
ConnectionUsage	connectionUsage	%	Connection usage is calculated by using the following formula: Established connections ÷ Total connections supported by the instance. This metric is a useful reference when a client connects to a Tair instance (cluster architecture) using a direct connection address.	DB DB aggregate
UsedConnection	ConnCount	Counts	The number of used connections.	DB DB aggregate
IntranetIn	InFlow	KB/s	The inbound and outbound traffic rates.	DB DB aggregate Proxy Proxy aggregate
IntranetOut	OutFlow	KB/s	The inbound and outbound traffic rates.	DB DB aggregate Proxy Proxy aggregate
IntranetInRatio	intranetInRatio	%	The usage percentage of the inbound and outbound traffic bandwidth.	DB DB aggregate
IntranetOutRatio	intranetOutRatio	%		DB DB aggregate
Redis_Avg_Rt_Monitor	AvgRt	us	The average latency, which is the average time a backend node takes to process a command from receipt to response. For a data node, this metric does not include the latency of proxy nodes and load balancing. For a proxy node, this metric includes the latency of data nodes and proxy nodes, but does not include the latency of load balancing.	DB DB aggregate Proxy Proxy aggregate
Redis_Max_Rt_Monitor	MaxRt	us	The maximum latency, which is the maximum time a node takes to process a command from receipt to response. For a data node, this metric does not include the latency of proxy nodes and load balancing. For a proxy node, this metric includes the latency of data nodes and proxy nodes, but does not include the latency of load balancing.	DB DB aggregate Proxy Proxy aggregate
Redis_Basic_Monitor	Keys	Counts	The total number of top-level keys stored in the instance.	DB DB aggregate
	Expires	Counts	The number of keys with an expiration time set. This is an instantaneous value measured at the time of collection.
	ExpiredKeys	Counts	The cumulative number of expired keys.
	EvictedKeys	Counts	The cumulative number of evicted keys.
	ExpiredKeysPerSecond	Counts/s	The number of keys that expire per second.
	EvictedKeysPerSecond	Counts/s	The number of keys that are evicted per second.
	inmem_keys	Counts	These metrics are supported only by hybrid storage instances (discontinued) and can be ignored.
	swapped_keys	Counts
Hit_Rate_Monitor	hit_rate	%	The percentage of successful key lookups. Formula: Number of key hits / (Number of key hits + Number of key misses).	DB DB aggregate
	hit	Counts	The number of key hits per second.
	miss	Counts	The number of key misses per second.
	evicted_keys_per_sec	Counts/s	The number of keys evicted per second.
DiskUsage	disk_usage	%	These metrics represent disk usage, input buffer size, output buffer size, and disk performance. Supported only by disk-based instances.	DB
Tair_Connection_Monitor	UsedInputBuffer	Bytes
Tair_Connection_Monitor	UsedOutputBuffer	Bytes
Tair_Disk_Monitor	`io_bandwidth_kbps`, `iops`, `iops_usage`, and more.	%, ms, Counts, and more.
UsedConnection	ConnectionUsage	%	Connection usage, calculated as: Used connections ÷ Maximum connections supported by the node. This metric is a useful reference when a client connects to a Tair instance (cluster or read/write splitting architecture) through a proxy node.	Proxy Proxy aggregate
	UsedConnection	Counts	The number of used connections.
	NewUserConnQps	Counts/s	The number of connections established per second from clients to proxy nodes.
Redis_Package_Monitor	request	Byte	The average size of a single request in bytes.	Proxy
	response	Byte	The average size of a single response in bytes.
	request_max	Byte	The maximum size of a single request in bytes.
	response_max	Byte	The maximum size of a single response in bytes.
RedisProxyConn	RedisUsedConnection	Counts	The number of connections from proxy nodes to data nodes.
	NewDBConnQps	Counts/s	The number of connections established per second from proxy nodes to data nodes.
	DisconnectDBConn	Counts	The cumulative number of disconnections from proxy nodes to data nodes.
	DisconnectUserConn	Counts	The cumulative number of disconnections from clients to proxy nodes.
TotalCalls	TotalRefusedCommands	Counts	The cumulative number of rejected commands.
	TotalCallsPerSecCalls	Counts/s	The number of requests per second.
	TotalCallsPerSecRetryCalls	Counts/s	The number of retried requests per second.
	TotalCallsPerSecRetryFailed	Counts/s	The number of failed requests per second.

Command statistics metrics

Command statistics metrics can be queried only for a specific data node. To query these metrics, pass the corresponding MonitorKeys parameter and specify the data node in the NodeId parameter.

Note

The Tair extension command monitoring group is supported only by memory-optimized instances that use the classic deployment mode (local disks).

MonitorKeys	Sub-metric	Unit	Description
Redis_Keys_Monitor	del, dump, exists, expire, expireat, move, persist, pexpire, pexpireat, pttl, randomkey, rename, renamenx, restore, sort, ttl, type, scan	Counts/s	The number of calls per second for key-related commands, such as DEL and EXISTS.
Redis_String_Monitor	append, bitcount, bitop, decr, decrby, get, getbit, getrange, getset, incr, incrby, incrbyfloat, mget, mset, msetnx, psetex, set, setbit, setex, setnx, setrange, strlen	Counts/s	The number of calls per second for String-related commands, such as APPEND and MGET.
Redis_Hashes_Monitor	hdel, hexists, hget, hgetall, hincrby, hincrbyfloat, hkeys, hlen, hmget, hmset, hset, hsetnx, hvals, hscan	Counts/s	The number of calls per second for Hash-related commands, such as HGET and HDEL.
Redis_Lists_Monitor	blpop, brpop, brpoplpush, lindex, linsert, llen, lpop, lpush, lpushx, lrange, lrem, lset, ltrim, rpop, rpoplpush, rpush, rpushx	Counts/s	The number of calls per second for List-related commands, such as BLPOP and BRPOP.
Redis_Sets_Monitor	sadd, scard, sdiff, sdiffstore, sinter, sinterstore, sismember, smembers, smove, spop, srandmember, srem, sunion, sunionstore, sscan	Counts/s	The number of calls per second for Set-related commands, such as SADD and SCARD.
Redis_Zset_Monitor	zadd, zcard, zcount, zincrby, zrange, zrangebyscore, zrank, zrem, zremrangebyrank, zremrangebyscore, zrevrange, zrevrangebyscore, zrevrank, zscore, zunionstore, zinterstore, zscan, zrangebylex, zlexcount, zremrangebylex, zpopmin, zpopmax, bzpopmin, bzpopmax	Counts/s	The number of calls per second for Sorted Set-related commands, such as ZADD and ZCARD.
Redis_Hyperlog_Monitor	pfadd, pfcount, pfmerge	Counts/s	The number of calls per second for HyperLogLog-related commands, such as PFADD and PFCOUNT.
Redis_Pub_Sub_Monitor	psubscribe, publish, pubsub, punsubscribe, subscribe, unsubscribe	Counts/s	The number of calls per second for publish/subscribe-related commands, such as PUBLISH and SUBSCRIBE.
Redis_Transaction_Monitor	discard, exec, multi, unwatch, watch	Counts/s	The number of calls per second for transaction-related commands, such as WATCH and MULTI.
Redis_Scripting_Monitor	eval, evalsha, script	Counts/s	The number of calls per second for scripting-related commands, such as EVAL and EVALSHA.
Calls_Monitor	flushall_calls, flushdb_calls, keys_calls	Counts	The cumulative number of calls for the FLUSHALL, FLUSHDB, and KEYS commands.
Redis_Connection_Monitor	auth, echo, ping, quit, select	Counts/s	The number of calls per second for connection-related commands, such as AUTH and ECHO.
Redis_Server_Monitor	bgsave, client, command, config, dbsize, debug, flushall, flushdb, info, monitor, slowlog, time	Counts/s	The number of calls per second for server-related commands, such as BGSAVE and CONFIG.
Redis_Geo_Monitor	geoadd, geohash, geopos, geodist, georadius, georadiusbymember	Counts/s	The number of calls per second for Geo-related commands, such as GEOADD and GEOHASH.
Redis_Streams_Monitor	xinfo, xadd, xtrim, xdel, xrange, xrevrange, xlen, xread, xgroup, xreadgroup, xack, xclaim, xpending	Counts/s	The number of calls per second for Streams-related commands, such as XINFO and XADD.
Redis_TairDoc_Monitor	jsondel, jsonget, jsonmget, jsonset, jsontype, jsonnumincrby, jsonstrappend, jsonstrlen, jsonarrappend, jsonarrpop, jsonarrinsert, jsonarrlen, jsonarrtrim	Counts/s	The number of calls per second for Doc-related commands, such as JSON.SET and JSON.GET.
Redis_TairHash_Monitor	exhset, exhsetnx, exhmset, exhexpireat, exhexpire, exhmsetwithopts, exhpexpireat, exhpexpire, exhpttl, exhttl, exhver, exhsetver, exhincrby, exhincrbyfloat, exhget, exhgetwithver, exhmget, exhdel, exhlen, exhexists, exhkeys, exhvals, exhgetall, exhmgetwithver, exhsterlen, exhscan	Counts/s	The number of calls per second for exHash-related commands, such as EXHSET and EXHMSET.
Redis_TairString_Monitor	cas, cad, exset, exget, exsetver, exincrby, exincrbyfloat, excas, excad	Counts/s	The number of calls per second for exString-related commands, such as EXSET and EXGET.
Redis_TairGis_Monitor	gisadd, gisget, gisdel, gissearch, giscontains, gisintersects, gisgetall	Counts/s	The number of calls per second for GIS-related commands, such as GIS.ADD, GIS.GET, and GIS.DEL.
Redis_TairBloom_Monitor	bfadd, bfmadd, bfexists, bfmexists, bfinsert, bfreserve, bfdebug	Counts/s	The number of calls per second for Bloom-related commands, such as BF.RESERVE and BF.ADD.

Response elements

Element	Type	Description	Example
	object
MonitorHistory	string	The monitoring data returned as a JSON-formatted string. For more information, see Monitoring parameters. Note To improve data transfer efficiency, the system returns only monitoring data for metrics with non-zero values. If a metric is not returned, its value is 0.	"{\"2022-11-06T00:00:00Z\":{\"memoryUsage\":\"6.67\"},\"2022-11-06T00:00:05Z\":{\"memoryUsage\":\"6.67\"},\"2022-11-06T00:00:10Z\":{\"memoryUsage\":\"6.67\"},\"2022-11-06T00:00:15Z\":{\"memoryUsage\":\"6.67\"},\"2022-11-06T00:00:20Z\":{\"memoryUsage\":\"6.67\"},\"2022-11-06T00:00:25Z\":{\"memoryUsage\":\"6.67\"}}"
RequestId	string	The ID of the request.	F0997EE8-F4C2-4503-9168-85177ED7****

Examples

Success response

JSON format

{
  "MonitorHistory": "\"{\\\"2022-11-06T00:00:00Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"},\\\"2022-11-06T00:00:05Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"},\\\"2022-11-06T00:00:10Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"},\\\"2022-11-06T00:00:15Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"},\\\"2022-11-06T00:00:20Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"},\\\"2022-11-06T00:00:25Z\\\":{\\\"memoryUsage\\\":\\\"6.67\\\"}}\"",
  "RequestId": "F0997EE8-F4C2-4503-9168-85177ED7****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidStartTime.Malformed	The Specified parameter "StartTime" is not valid.
400	InvalidEndTime.Malformed	The Specified parameter "EndTime" is not valid.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.