Check whether an instance runs as expected - ApsaraMQ for Kafka

When an SDK client fails to send or receive messages, or cannot connect to an ApsaraMQ for Kafka instance, run a health check to isolate the root cause. The health check verifies:

Network connectivity between the client and the instance
Instance availability and broker operation
Client configuration including endpoint, authentication, and SASL settings

ApsaraMQ for Kafka provides a command-line tool called KafkaChecker.jar that runs these checks.

Prerequisites

Before you begin, make sure that you have:

JDK 1.8 or later installed. For download options, see Java Downloads
The kafka-checker.zip self-check tool downloaded and extracted
A topic and a consumer group created on the ApsaraMQ for Kafka instance for testing. For more information, see Step 3: Create resources

Important

Use a dedicated topic for health checks. The send test produces real messages that could interfere with production data.

Placeholders used in commands

Replace the following placeholders in all commands throughout this document:

Placeholder	Description	Example
`<kafka-checker-path>`	Local directory where you extracted KafkaChecker.jar	`/usr/opt/kafka-checker`
`<endpoint>`	Comma-separated broker addresses with port	`alikafka-pre-cn-zv****-1-vpc.alikafka.aliyuncs.com:9092`
`<topic>`	Name of the test topic	`test`
`<group>`	Name of the test consumer group	`test`
`<username>`	SASL username	`test`
`<password>`	SASL password	`test****`

Endpoint types and ports

Each connection method uses a different endpoint and port. Identify which applies to your setup:

Connection method	Port	Auth flags	When to use
VPC default endpoint	9092	None	Client and instance are in the same VPC
Internet SSL endpoint	9093	`-ss true -sm <mechanism> -u <username> -psw <password>`	Client connects over the public internet
VPC SSL endpoint	9094	`-sp true -sm <mechanism> -u <username> -psw <password>`	Client connects over VPC with SASL authentication

For details about endpoint differences, see Comparison among endpoints.

SASL authentication mechanisms:

PLAIN: The default mechanism for internet connections. Use -sm PLAIN.
SCRAM-SHA-256: An alternative mechanism. Use -sm SCRAM-SHA-256.

To create SASL users for fine-grained access control, see Grant permissions to SASL users.

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 your instance resides.
On the Instances page, click the name of your instance.
In the Endpoint Information section of the Instance Details page, copy the endpoint that matches your connection method.

Step 2: Test network connectivity

From the directory where you extracted the self-check tool, run the telnet command:

cd <kafka-checker-path>
java -jar KafkaChecker.jar telnet -s <endpoint>

Example (VPC default endpoint):

cd /usr/opt/kafka-checker
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

If you connect over VPC using the default endpoint, the client and the instance must be deployed in the same virtual private cloud (VPC).

Interpreting results:

Success: Output similar to the following confirms that the network is connected.
Failure -- whitelist not configured: The endpoint whitelist is not set up. See Configure whitelists to add the client IP address to the whitelist.

Step 3: Test message sending

Run the send command with the appropriate flags for your connection method.

Base command:

java -jar KafkaChecker.jar send -s <endpoint> --topic <topic>

Add authentication flags based on your connection method (see Endpoint types and ports):

Connection method	Full command
VPC default (port 9092)	`java -jar KafkaChecker.jar send -s <endpoint> --topic <topic>`
Internet SSL + PLAIN (port 9093)	`java -jar KafkaChecker.jar send -sm PLAIN -ss true -u <username> -psw <password> -s <endpoint> --topic <topic>`
Internet SSL + SCRAM-SHA-256 (port 9093)	`java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -ss true -u <username> -psw <password> -s <endpoint> --topic <topic>`
VPC SSL + PLAIN (port 9094)	`java -jar KafkaChecker.jar send -sm PLAIN -sp true -u <username> -psw <password> -s <endpoint> --topic <topic>`
VPC SSL + SCRAM-SHA-256 (port 9094)	`java -jar KafkaChecker.jar send -sm SCRAM-SHA-256 -sp true -u <username> -psw <password> -s <endpoint> --topic <topic>`

Example (Internet SSL with PLAIN):

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

If the message is sent successfully, output similar to the following is displayed:

Step 4: Test message consumption

Run the pull command to consume messages. This command uses the same connection flags as send, plus consumer-specific parameters: --group, --partition, --offset, and --count.