All Products
Search

This Product

    ApsaraMQ for Kafka:ApsaraMQ for Kafka instance health check

    Document Center

    ApsaraMQ for Kafka:ApsaraMQ for Kafka instance health check

    Last Updated:Jun 24, 2026

    If a client using an SDK cannot send or receive messages or connect to an instance, use the Kafka health check tool to diagnose the issue. This tool helps you check for network connectivity issues and instance anomalies. If the instance is healthy, verify your client-side code and network configuration to rule out issues with your application.

    Prerequisites

    • JDK 1.8 or later is installed. For more information, see Java Downloads.

    • You have downloaded and extracted the health check tool kafka-checker.zip.

    • You have created a topic and a consumer group for testing message sending and consumption. For more information, see Create resources.

    Test network connectivity

    1. Obtain an endpoint.

      1. Log on to the ApsaraMQ for Kafka console.

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

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

      4. On the Instance Details page, find the Endpoint Information section and obtain the endpoint of your instance.

        This section displays three types of endpoints: VPC default endpoint (VPC, PLAINTEXT protocol), Internet SSL endpoint (internet, SASL_SSL protocol), and VPC SSL endpoint (VPC, SASL_PLAINTEXT protocol). Copy the endpoint address that corresponds to your network environment.

        Note

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

    2. Use the health check tool to test network connectivity to the endpoint. The following steps use a Linux operating system as an example.

      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 path.

      2. Run the following command to test the connectivity to the ApsaraMQ for Kafka instance.

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

        For example, if your client connects to ApsaraMQ for Kafka by using the 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 use a VPC endpoint, ensure that your client and the instance are in the same VPC.

        If the output is similar to the following, the network connection is working correctly.

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

        If a message similar to the following is displayed, this indicates that the whitelist for accessing ApsaraMQ for Kafka is not configured. 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 message sending

    Note

    Sending messages generates test data. To avoid impacting your production data, create a dedicated topic for health checks.

    Run the command that corresponds to your connection method.

    • Connect through the VPC default endpoint over 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 the Internet SSL endpoint over port 9093. This connection requires SASL authentication. Run the command that corresponds to the authentication mechanism that you use.

      Note

      • For connections over the internet, the instance's default SASL user uses the PLAIN mechanism for authentication.

      • You can create SASL users for more fine-grained permission control and configure the authentication mechanism to PLAIN or SCRAM-SHA-256. For more information, see Grant permissions to SASL users. You must run the command that corresponds to the authentication mechanism that you use.

      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 the VPC SSL endpoint over port 9094. This connection requires SASL authentication. Run the command that corresponds to the authentication mechanism that you use.

      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 the 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 that corresponds to your connection method.

    • Connect through the VPC default endpoint over port 9092:

      java -jar KafkaChecker.jar pull -s <endpoint_domain:9092> --topic <topic_name> --group <consumer_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 the Internet SSL endpoint over port 9093. This connection requires SASL authentication. Run the command that corresponds to the authentication mechanism that you use to consume messages.

      Note

      • For connections over the internet, the instance's default SASL user uses the PLAIN mechanism for authentication.

      • You can create SASL users for more fine-grained permission control and configure the authentication mechanism to PLAIN or SCRAM-SHA-256. For more information, see Grant permissions to SASL users. You must run the command that corresponds to the authentication mechanism that you use.

      PLAIN mechanism

      java -jar KafkaChecker.jar pull -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint_domain:9093> --topic <topic_name> --group <consumer_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 <consumer_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 the VPC SSL endpoint over port 9094. This connection requires SASL authentication. Run the command that corresponds to the authentication mechanism that you use to consume messages.

      PLAIN mechanism

      java -jar KafkaChecker.jar pull -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint_domain:9094> --topic <topic_name> --group <consumer_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 <consumer_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 the 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

    References

    For information about the relevant SDKs, see SDK overview.