If your SDK client fails to connect to an ApsaraMQ for Kafka instance, or messages cannot be sent or received, run a health check to diagnose the issue. The health check verifies network connectivity, instance availability, and client configuration in three sequential steps:
Test network connectivity -- Confirm that the client can reach the instance endpoint.
Test message sending -- Send a test message to verify producer functionality.
Test message consumption -- Pull test messages to verify consumer functionality.
Run these tests in order. A connectivity failure causes all subsequent tests to fail.
Prerequisites
Before you begin, make sure that you have:
JDK 1.8 or later installed. See Java Downloads
The self-check tool kafka-checker.zip downloaded and extracted
A topic and a consumer group created on the ApsaraMQ for Kafka instance, dedicated to health-check testing. See Step 3: Create resources
Placeholders
Replace the following placeholders with your actual values in all commands:
| Placeholder | Description | Example |
|---|---|---|
<endpoint> | Broker endpoint of the instance | alikafka-pre-cn-zv****-1-vpc.alikafka.aliyuncs.com |
<topic> | Name of the test topic | test |
<group> | Name of the test consumer group | test-group |
<username> | SASL username | test |
<password> | SASL password | test**** |
<path-to-kafka-checker> | Local directory containing KafkaChecker.jar | /usr/opt/kafka-checker |
Connection types
ApsaraMQ for Kafka supports three connection types. Each uses a different port and security configuration:
| Connection type | Port | Encryption | Authentication | Flag |
|---|---|---|---|---|
| VPC default | 9092 | None | None | (none) |
| Internet SSL | 9093 | SSL | SASL (PLAIN or SCRAM-SHA-256) | -ss true |
| VPC SSL | 9094 | SSL | SASL (PLAIN or SCRAM-SHA-256) | -sp true |
For VPC connections (ports 9092 and 9094), the client and the instance must be in the same virtual private cloud (VPC). For differences between endpoint types, see Comparison among endpoints.
Step 1: Get the instance endpoint
Log on to the ApsaraMQ for Kafka console.
In the Resource Distribution section of the Overview page, select the region where the instance resides.
On the Instances page, click the instance name.
In the Endpoint Information section of the Instance Details page, copy the endpoint that matches your connection type.
Step 2: Test network connectivity
Navigate to the directory where KafkaChecker.jar is located:
cd <path-to-kafka-checker>Run the telnet test. Pass the full endpoint string from the console, which includes all broker addresses with ports: Example (VPC default endpoint with three brokers):
java -jar KafkaChecker.jar telnet -s <endpoint>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
Interpret the results
Success: All brokers are reachable.
Whitelist error: The endpoint whitelist is not configured for the ApsaraMQ for Kafka instance. For information about how to configure a whitelist, see Configure whitelists.
Step 3: Test message sending
Sending test messages generates real data. Use a dedicated test topic to avoid affecting production data.
Run the command that matches your connection type.
VPC default (port 9092)
java -jar KafkaChecker.jar send -s <endpoint>:9092 --topic <topic>Internet SSL (port 9093)
Internet connections require Simple Authentication and Security Layer (SASL) authentication. The default SASL user uses the PLAIN mechanism. To create a SASL user with SCRAM-SHA-256, see Grant permissions to SASL users.
PLAIN mechanism:
java -jar KafkaChecker.jar send -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint>:9093 --topic <topic>SCRAM-SHA-256 mechanism:
java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -ss true -u <username> -psw <password> -s <endpoint>:9093 --topic <topic>VPC SSL (port 9094)
PLAIN mechanism:
java -jar KafkaChecker.jar send -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint>:9094 --topic <topic>SCRAM-SHA-256 mechanism:
java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -sp true -u <username> -psw <password> -s <endpoint>:9094 --topic <topic>Verify the result
A successful send produces output similar to the following:
Step 4: Test message consumption
Run the command that matches your connection type. All pull commands read up to 10 messages from partition 0, starting at offset 0.
VPC default (port 9092)
java -jar KafkaChecker.jar pull -s <endpoint>:9092 --topic <topic> --group <group> --partition 0 --offset 0 --count 10Internet SSL (port 9093)
If a client is connected to an ApsaraMQ for Kafka instance over the Internet, the default SASL user of the instance uses the PLAIN mechanism for authentication.
You can create a SASL user to perform fine-grained access control. You can specify the authentication mechanism as 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 to consume messages.
PLAIN mechanism:
java -jar KafkaChecker.jar pull -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint>:9093 --topic <topic> --group <group> --partition 0 --offset 0 --count 10SCRAM-SHA-256 mechanism:
java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -ss true -u <username> -psw <password> -s <endpoint>:9093 --topic <topic> --group <group> --partition 0 --offset 0 --count 10VPC SSL (port 9094)
PLAIN mechanism:
java -jar KafkaChecker.jar pull -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint>:9094 --topic <topic> --group <group> --partition 0 --offset 0 --count 10SCRAM-SHA-256 mechanism:
java -jar KafkaChecker.jar pull -sm SCRAM-SHA-256 -sp true -u <username> -psw <password> -s <endpoint>:9094 --topic <topic> --group <group> --partition 0 --offset 0 --count 10Verify the result
A successful pull produces output similar to the following:
