When troubleshooting message delivery failures or consumer lag in ApsaraMQ for RocketMQ, client logs are your primary diagnostic tool. The SDK for Java automatically generates log files that capture runtime exceptions, connection events, and message lifecycle details.
We recommend that you use the latest RocketMQ 5.x SDKs. These SDKs are fully compatible with ApsaraMQ for RocketMQ 5.x brokers and provide more functions and enhanced features. For more information, see Version guide.
Alibaba Cloud only maintains RocketMQ 3.x, 4.x, and TCP client SDKs. We recommend that you use them only for existing business.
Default log settings
The client generates log files automatically with the following defaults:
| Setting | Default value | Customizable | System property |
|---|---|---|---|
| Log storage path | /{user.home}/logs/ons.log | Yes | ons.client.logRoot |
| Log level | INFO | Yes | ons.client.logLevel |
| Maximum retained log files | 10 | Yes | ons.client.logFileMaxIndex |
| Log file size | 64 MB | No | N/A |
In the default path, {user.home} is the home directory of the account running the Java process.
Log levels
The valid log levels are:
| Level |
|---|
ERROR |
WARN |
INFO |
DEBUG |
Enable log printing
The SDK for Java uses the SLF4J API for logging. Setup depends on your SDK version.
SDK for Java 1.7.8.Final or later
No setup required. These versions include a built-in logging framework that handles log output automatically.
SDK for Java versions earlier than 1.7.8.Final
Add a dependency on a supported logging framework (Log4j or Logback) to your pom.xml or .lib file.
SDK for Java 1.7.8.Final and earlier supports only Log4j and Logback. Log4j2 is not supported.
If your application includes both Log4j and Logback, logging conflicts prevent client logs from printing correctly. Use only one logging framework. To identify conflicts, run:
mvn clean dependency:tree | grep logTo avoid these limitations, upgrade to the latest version of the SDK for Java.
Customize client logs
Custom log configuration requires SDK for Java 1.2.5 or later.
Pass Java system properties through the -D flag in your startup script or integrated development environment (IDE) virtual machine (VM) options.
Available properties
| Property | Description | Valid values |
|---|---|---|
ons.client.logRoot | Log file directory | Any writable path on your system |
ons.client.logLevel | Minimum log level | ERROR, WARN, INFO, DEBUG |
ons.client.logFileMaxIndex | Maximum number of retained log files | 1 to 100 (defaults to 10 if the value is out of range or invalid) |
Examples
Linux or macOS:
-Dons.client.logRoot=/home/admin/logs -Dons.client.logLevel=WARN -Dons.client.logFileMaxIndex=20Windows:
-Dons.client.logRoot=D:\logs -Dons.client.logLevel=WARN -Dons.client.logFileMaxIndex=20Replace /home/admin/logs and D:\logs with actual directories on your system. The application process must have write permission on the specified path, otherwise logs cannot be printed.
Troubleshoot logging issues
| Symptom | Cause | Solution |
|---|---|---|
| No log files generated | Missing logging framework dependency (SDK earlier than 1.7.8.Final) | Add a Log4j or Logback dependency to your pom.xml |
| Empty or missing log output | Both Log4j and Logback present on the classpath | Remove one framework. Run mvn clean dependency:tree and search the output for log to identify conflicts |
| Logs written to unexpected directory | Default {user.home} resolves differently at runtime | Set ons.client.logRoot explicitly to a known path |
| Log files grow without bound | Default retention keeps 10 files at 64 MB each (640 MB total) | Lower ons.client.logFileMaxIndex or set up external log rotation |