All Products
Search
Document Center

ApsaraMQ for RocketMQ:OnsConsumerStatus

Last Updated:Mar 03, 2024

Queries the detailed information about the status of a specified consumer group. This operation returns the transactions per second (TPS) for message consumption, load balancing status, consumer connection status, and whether all consumers in the consumer group subscribe to the same topics and tags.

Operation description

Note API operations provided by Alibaba Cloud are used to manage and query resources of Alibaba Cloud services. We recommend that you integrate these API operations only in management systems. Do not use these API operations in the core system of messaging services. Otherwise, system risks may occur.
  • You can call this operation in scenarios in which consumers are online and messages are accumulated. You can troubleshoot errors based on the information that is returned by this operation. You can check whether all consumers in the consumer group subscribe to the same topics and tags, and whether load balancing is performed as expected. You can also obtain the information about thread stack traces of online consumers.
  • This operation uses multiple backend operations to query and aggregate data. The system requires a long period of time to process a request. We recommend that you do not frequently call this operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
mq:QueryConsumerStatusRead
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
GroupIdstringYes

The ID of the consumer group whose details you want to query.

GID_test_group_id
DetailbooleanNo

Specifies whether to query the details of the consumer group. Valid values:

  • true: The details of the consumer group are queried. You can obtain details from the ConsumerConnectionInfoList and DetailInTopicList response parameters.
  • false: The details of the consumer group are not queried. The values of the ConsumerConnectionInfoList and DetailInTopicList response parameters are empty. This value is the default value of the Detail parameter.
true
NeedJstackbooleanNo

Specifies whether to query the information about thread stack traces. Valid values:

  • true: The information about thread stack traces is queried. You can obtain the information from the Jstack response parameter.
Note If you want to obtain the information about thread stack traces, make sure that the Detail parameter in the request is set to true.
  • false: The information about thread stack traces is not queried. The value of the Jstack response parameter is empty. This value is the default value of the NeedJstack parameter.
true
InstanceIdstringYes

The ID of the instance to which the consumer group belongs.

MQ_INST_111111111111_DOxxxxxx

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The ID of the request. This parameter is a common parameter. Each request has a unique ID. You can use this ID to troubleshoot issues.

10EDC518-10E7-4B34-92FB-171235FA****
Dataobject

The data returned.

ConsumeTpsfloat

The TPS for message consumption.

0
ConsumeModelstring

The consumption mode. Valid values:

  • CLUSTERING: the clustering consumption mode
  • BROADCASTING: the broadcasting consumption mode

For more information about consumption modes, see Clustering consumption and broadcasting consumption.

CLUSTERING
ConnectionSetobject []

The information about online consumers in the consumer group.

RemoteIPstring

The private or public IP address of the host.

42.120.74.**
Versionstring

The version of the consumer client.

V4_3_6_SNAPSHOT
ClientAddrstring

The IP address and port number of the consumer instance.

30.5.121.**
Languagestring

The programming language in which the consumer is developed.

JAVA
ClientIdstring

The ID of the consumer instance.

30.5.121.**@25560#-1999745829#-1737591554#458773089270275
TotalDifflong

The total number of accumulated messages.

197
ConsumerConnectionInfoListobject []

The details of online consumers in the consumer group, including the information about the thread stack traces and the consumption response time (RT). If you want to obtain the details of online consumers in the consumer group, make sure that the Detail parameter in the request is set to true. If the Detail parameter is not set to true, the value of this parameter is empty.

ConsumeModelstring

The consumption mode. Valid values:

  • CLUSTERING: the clustering consumption mode
  • BROADCASTING: the broadcasting consumption mode

For more information about consumption modes, see Clustering consumption and broadcasting consumption.

CLUSTERING
RunningDataListobject []

The real-time statistics.

GroupIdstring

The ID of the consumer group.

0
Rtfloat

The consumption RT. Unit: milliseconds.

0
Topicstring

The name of the topic to which the consumer subscribes.

test-mq_topic
FailedCountPerHourlong

The number of messages that failed to be consumed each hour.

0
OkTpsfloat

The TPS for successful message consumption.

0
FailedTpsfloat

The TPS for failed message consumption.

0
SubscriptionSetobject []

The information about subscriptions.

SubStringstring

The expression that is used to specify the tags of messages in the subscribed topic.

*
SubVersionlong

The subscription version. The value is of the LONG type and is automatically incremented.

1570701364301
Topicstring

The name of the topic to which the consumer subscribes.

test-mq_topic
TagsSetarray

The information about the tags of the topic to which the consumer subscribes.

string

The information about the tags of the topic to which the consumer subscribes.

ff
Jstackobject []

The information about thread stack traces. If you want to obtain the information about thread stack traces, make sure that the NeedJstack parameter in the request is set to true. If the NeedJstack parameter is not set to true, the value of this parameter is empty.

TrackListarray

The details of thread stack traces.

string

The details of thread stack traces.

TID: 52 STATE: WAITING
Threadstring

The name of the thread.

ConsumeMessageThread_0
LastTimeStamplong

The most recent point in time when a message was consumed.

The value of this parameter is a UNIX timestamp in milliseconds.

1570701368114
StartTimeStamplong

The earliest point in time when a message was consumed.

The value of this parameter is a UNIX timestamp in milliseconds.

1570701361528
Languagestring

The programming language that the consumer supports.

JAVA
ClientIdstring

The ID of the consumer instance.

30.5.**.**@25560#-1999745829#-1737591554#458773089270275
Connectionstring

The connection information.

**
Versionstring

The version of the consumer client.

V4_3_6
ConsumeTypestring

The mode in which the consumer consumes messages. Valid values:

  • PUSH: The ApsaraMQ for RocketMQ broker pushes messages to the consumer.
  • PULL: The consumer pulls messages from the ApsaraMQ for RocketMQ broker.
PUSH
ThreadCountinteger

The number of consumer threads.

20
InstanceIdstring

The ID of the instance

MQ_INST_111111111111_DOxxxxxx
DetailInTopicListobject []

The information about message consumption by topic. If you want to obtain the information about the consumption status of each topic, make sure that the Detail parameter in the request is set to true. If the Detail parameter is not set to true, the value of this parameter is empty.

DelayTimelong

The latency of message consumption in the topic. Unit: milliseconds.

0
TotalDifflong

The number of accumulated messages in the topic.

0
LastTimestamplong

The most recent point in time when a message was consumed.

The value of this parameter is a UNIX timestamp in milliseconds.

1570701259403
Topicstring

The topic name.

test-mq_topic
SubscriptionSameboolean

Indicates whether all consumers in the consumer group subscribe to the same topics and tags.

true
DelayTimelong

The maximum latency of message consumption in all topics to which the consumer group subscribes. Unit: milliseconds.

100857
LastTimestamplong

The most recent point in time when a message was consumed.

The value of this parameter is a UNIX timestamp in milliseconds.

1566883844954
Onlineboolean

Indicates whether the consumer group is online.

true
RebalanceOKboolean

Indicates whether load balancing is performed as expected. Valid values:

  • true: Load balancing is performed as expected.
  • false: Load balancing is not performed as expected.
true

Examples

Sample success responses

JSONformat

{
  "RequestId": "10EDC518-10E7-4B34-92FB-171235FA****",
  "Data": {
    "ConsumeTps": 0,
    "ConsumeModel": "CLUSTERING",
    "ConnectionSet": {
      "ConnectionDo": [
        {
          "RemoteIP": "42.120.74.**",
          "Version": "V4_3_6_SNAPSHOT",
          "ClientAddr": "30.5.121.**",
          "Language": "JAVA",
          "ClientId": "30.5.121.**@25560#-1999745829#-1737591554#458773089270275"
        }
      ]
    },
    "TotalDiff": 197,
    "ConsumerConnectionInfoList": {
      "ConsumerConnectionInfoDo": [
        {
          "ConsumeModel": "CLUSTERING",
          "RunningDataList": {
            "ConsumerRunningDataDo": [
              {
                "GroupId": "0",
                "Rt": 0,
                "Topic": "test-mq_topic",
                "FailedCountPerHour": 0,
                "OkTps": 0,
                "FailedTps": 0
              }
            ]
          },
          "SubscriptionSet": {
            "SubscriptionData": [
              {
                "SubString": "*",
                "SubVersion": 1570701364301,
                "Topic": "test-mq_topic",
                "TagsSet": {
                  "Tag": [
                    "ff"
                  ]
                }
              }
            ]
          },
          "Jstack": {
            "ThreadTrackDo": [
              {
                "TrackList": {
                  "Track": [
                    "TID: 52 STATE: WAITING"
                  ]
                },
                "Thread": "ConsumeMessageThread_0"
              }
            ]
          },
          "LastTimeStamp": 1570701368114,
          "StartTimeStamp": 1570701361528,
          "Language": "JAVA",
          "ClientId": "30.5.**.**@25560#-1999745829#-1737591554#458773089270275",
          "Connection": "**",
          "Version": "V4_3_6",
          "ConsumeType": "PUSH",
          "ThreadCount": 20
        }
      ]
    },
    "InstanceId": "MQ_INST_111111111111_DOxxxxxx",
    "DetailInTopicList": {
      "DetailInTopicDo": [
        {
          "DelayTime": 0,
          "TotalDiff": 0,
          "LastTimestamp": 1570701259403,
          "Topic": "test-mq_topic"
        }
      ]
    },
    "SubscriptionSame": true,
    "DelayTime": 100857,
    "LastTimestamp": 1566883844954,
    "Online": true,
    "RebalanceOK": true
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-12-08The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.

View the details of a consumer group in the console

You can also view the details of a consumer group in the ApsaraMQ for RocketMQ console. For more information, see View the status of consumers.