All Products
Search

This Product

    ApsaraMQ for Kafka:Instance health check

    Document Center

    ApsaraMQ for Kafka:Instance health check

    Last Updated:Jun 20, 2026

    If an SDK client cannot send or receive messages, or fails to connect to an instance, use the Kafka health check tool to verify the instance's health. This tool verifies network connectivity and the instance status. If the tool confirms the instance is healthy, investigate your client's network connection and code configuration.

    Prerequisites

    Test network connectivity

    1. Obtain an endpoint.

      1. Log on to the ApsaraMQ for Kafka console.

      2. In the Resource Distribution section of the Overview page, select a region.

      3. On the Instances page, click the name of the target instance.

      4. In the Endpoint Information section of the Instance Details page, obtain an endpoint for your instance.

        This section displays three types of endpoints: a VPC default endpoint (VPC network, PLAINTEXT protocol), an internet SSL endpoint (internet, SASL_SSL protocol), and a VPC SASL endpoint (VPC network, SASL_PLAINTEXT protocol). Choose and copy the endpoint domain based on your connection requirements.

        Note

        For more information about the differences between endpoints, see Comparison of endpoints.

    2. Run a telnet test to verify endpoint connectivity. The following example uses a Linux operating system.

      1. Log on to your Linux system and navigate to the directory where the KafkaChecker.jar tool is located.

        cd /usr/opt/kafka-checker

        Replace /usr/opt/kafka-checker with the actual local path.

      2. Run the following command to test the connection to ApsaraMQ for Kafka.

        java -jar KafkaChecker.jar telnet -s <endpoint-string>

        For example, if your client connects to ApsaraMQ for Kafka over a VPC default endpoint, run the following command: java -jar KafkaChecker.jar telnet -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9092,alikafka-pre-cn-zv**********-2-vpc.alikafka.aliyuncs.com:9092,alikafka-pre-cn-zv**********-3-vpc.alikafka.aliyuncs.com:9092.

        Note

        When you connect by using a Virtual Private Cloud (VPC) endpoint, your device must be in the same VPC as the instance.

        Output similar to the following indicates a successful network connection.

        telnet xxx 9092  success
telnet xxx:xxx:xxx 9092  success
telnet xxx:xxx:xxx 9092  success

        If the following output is returned, a whitelist is not configured for the ApsaraMQ for Kafka instance. For more information, see Configure a whitelist.

        telnet xxx 9092 failure, please add ip to white list in Alikafka console
telnet xxx 9092 failure, please add ip to white list in Alikafka console
telnet xxx 9092 failure, please add ip to white list in Alikafka console

    Test sending messages

    Note

    Sending messages generates test data. To avoid affecting production data, create a topic specifically for health check testing.

    Run the command for your endpoint type to send a message.

    • Connect through a VPC default endpoint on port 9092:

      java -jar KafkaChecker.jar send -s <endpoint-domain>:9092 --topic <topic-name>

      Example: java -jar KafkaChecker.jar send -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9092 --topic test

    • Connect through an internet SSL endpoint on port 9093. SASL supports authentication with the PLAIN or SCRAM-SHA-256 mechanism. Run the command for your authentication mechanism.

      Note

      • In an internet environment, the default SASL user of an instance uses the PLAIN mechanism for authentication.

      • You can create SASL users for more granular access control and configure the authentication mechanism to either PLAIN or SCRAM-SHA-256. For more information, see Grant permissions to SASL users.

      PLAIN mechanism

      java -jar KafkaChecker.jar send -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint-domain>:9093 --topic <topic-name>

      Example: java -jar KafkaChecker.jar send -sm PLAIN -ss true -u test -psw test**** -s alikafka-pre-cn-zv**********-1.alikafka.aliyuncs.com:9093 --topic test

      SCRAM-SHA-256 mechanism

      java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -ss true -u <username> -psw <password> -s <endpoint-domain>:9093 --topic <topic-name>

      Example: java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -ss true -u test -psw test**** -s alikafka-pre-cn-zv**********-1.alikafka.aliyuncs.com:9093 --topic test

    • Connect through a VPC SASL endpoint on port 9094. SASL supports authentication with the PLAIN or SCRAM-SHA-256 mechanism. Run the command for your authentication mechanism.

      PLAIN mechanism

      java -jar KafkaChecker.jar send -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint-domain>:9094 --topic <topic-name>

      Example: java -jar KafkaChecker.jar send -sm PLAIN -sp true -u test -psw test**** -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9094 --topic test

      SCRAM-SHA-256 mechanism

      java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -sp true -u <username> -psw <password> -s <endpoint-domain>:9094 --topic <topic-name>

      Example: java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -sp true -u test -psw test**** -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9094 --topic test

    Output similar to the following indicates that messages were sent successfully.

    [2021-08-27 11:29:18.838]Produce ok number:0 p:2 offset:21 response:test-2@21 cost:1342 ms
[2021-08-27 11:29:19.252]Produce ok number:1 p:2 offset:22 response:test-2@22 cost:410 ms
[2021-08-27 11:29:19.254]Produce ok number:1 p:6 offset:9 response:test-6@9 cost:412 ms
[2021-08-27 11:29:19.301]Produce ok number:2 p:5 offset:25 response:test-5@25 cost:47 ms
[2021-08-27 11:29:19.302]Produce ok number:2 p:4 offset:20 response:test-4@20 cost:48 ms
[2021-08-27 11:29:19.347]Produce ok number:3 p:1 offset:19 response:test-1@19 cost:45 ms
[2021-08-27 11:29:19.348]Produce ok number:3 p:8 offset:17 response:test-8@17 cost:46 ms

    Test message consumption

    Run the command for your endpoint type to consume messages.

    • Connect through a VPC default endpoint on port 9092:

      java -jar KafkaChecker.jar pull -s <endpoint-domain>:9092 --topic <topic-name> --group <group-name> --partition 0 --offset 0 --count 10

      Example: java -jar KafkaChecker.jar pull -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9092 --topic test --group test --partition 0 --offset 0 --count 10

    • Connect through an internet SSL endpoint on port 9093. SASL supports authentication with the PLAIN or SCRAM-SHA-256 mechanism. Run the command for your authentication mechanism.

      Note

      • In an internet environment, the default SASL user of an instance uses the PLAIN mechanism for authentication.

      • You can create SASL users for more granular access control and configure the authentication mechanism to either PLAIN or SCRAM-SHA-256. For more information, see Grant permissions to SASL users.

      PLAIN mechanism

      java -jar KafkaChecker.jar pull -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint-domain>:9093 --topic <topic-name> --group <group-name> --partition 0 --offset 0 --count 10

      Example: java -jar KafkaChecker.jar pull -sm PLAIN -ss true -u test -psw test**** -s alikafka-pre-cn-zv**********-1.alikafka.aliyuncs.com:9093 --topic test --group test --partition 0 --offset 0 --count 10

      SCRAM-SHA-256 mechanism

      java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -ss true -u <username> -psw <password> -s <endpoint-domain>:9093 --topic <topic-name> --group <group-name> --partition 0 --offset 0 --count 10

      Example: java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -ss true -u test -psw test**** -s alikafka-pre-cn-zv**********-1.alikafka.aliyuncs.com:9093 --topic test --group test --partition 0 --offset 0 --count 10

    • Connect through a VPC SASL endpoint on port 9094. SASL supports authentication with the PLAIN or SCRAM-SHA-256 mechanism. Run the command for your authentication mechanism.

      PLAIN mechanism

      java -jar KafkaChecker.jar pull -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint-domain>:9094 --topic <topic-name> --group <group-name> --partition 0 --offset 0 --count 10

      Example: java -jar KafkaChecker.jar pull -sm PLAIN -sp true -u test -psw test**** -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9094 --topic test --group test --partition 0 --offset 0 --count 10

      SCRAM-SHA-256 mechanism

      java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -sp true -u <username> -psw <password> -s <endpoint-domain>:9094 --topic <topic-name> --group <group-name> --partition 0 --offset 0 --count 10

      Example: java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -sp true -u test -psw test**** -s alikafka-pre-cn-zv**********-1-vpc.alikafka.aliyuncs.com:9094 --topic test --group test --partition 0 --offset 0 --count 10

    Output similar to the following indicates that messages were consumed successfully.

    [2021-08-27 11:32:37.917]Pull Succ topic:test partition:0 offset:0 key:demo value: time:2021-08-10 15:08:10.629 cha:1455867288
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:1 key:demo value: time:2021-08-10 15:16:08.386 cha:1455389532
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:2 key:demo value: time:2021-08-10 15:16:50.374 cha:1455347544
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:3 key:null value: time:2021-08-18 21:08:23.532 cha:743054386
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:4 key:null value: time:2021-08-18 21:08:23.778 cha:743054140
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:5 key:null value: time:2021-08-18 21:08:23.892 cha:743054026
[2021-08-27 11:32:37.918]Pull Succ topic:test partition:0 offset:6 key:null value: time:2021-08-18 21:08:24.352 cha:743053566
[2021-08-27 11:32:37.919]Pull Succ topic:test partition:0 offset:7 key:null value: time:2021-08-18 21:08:24.452 cha:743053467

    Related documents

    For information about related SDK packages, see SDK overview.