Enhancements to Quick Start Documentation for New Users

[oriana19993926782]

What is the purpose of the change The current Quick Start documentation is succinct and provides a smooth onboarding experience for new users. However, during my setup process, I encountered a few non-trivial issues that required additional steps to resolve. These issues are likely common among new users and could significantly impact their initial experience with RocketMQ. I propose adding a "Some Tips" section to the Quick Start guide to address these potential stumbling blocks.

Detailed description of the issues and proposed additions 1. About slf4j While following step 5 of the Quick Start guide to create and run a program for sending normal messages, I encountered an error: Could not find artifact org.slf4j:slf4j-api:jar:27.0.0-SNAPSHOT This suggests that Maven could not find the specified dependency version in its configured repositories, particularly for versions marked as SNAPSHOT, which are generally unstable and subject to frequent changes. A simpler solution is to try an earlier stable release version.

Additionally, using the slf4j-api version 2.0.x might lead to the following error: SLF4J: No SLF4J providers were found. SLF4J: Defaulting to no-operation (NOP) logger implementation This indicates that SLF4J did not find any logging implementation in the project. Since version 2.0.x, SLF4J is only a logging facade, not an implementation. The solution is to add a logging implementation to the pom.xml, such as slf4j-nop.jar, slf4j-simple.jar, slf4j-reload4j.jar, slf4j-jdk14.jar, or logback-classic.jar. Here is an example:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.3</version>
</dependency>

2. InternalErrorException：The broker's disk is full When trying to send messages, clients might encounter the InternalErrorException: service not available now. It may be caused by one of the following reasons: the broker's disk is full. This can be confusing as there might still be several GBs of space available on the disk. The term "full" here refers to a high space utilization rate, not an absolute lack of space.

For MAC OS systems, running df -h in the terminal to check the disk partition usage could reveal that the /System/Volumes/Data partition has a high utilization rate, which RocketMQ might be using, almost filled to capacity. The solution is to free up space in this partition until the utilization rate drops to a reasonable level.

3. java.lang.RuntimeException: Lock failed, MQ already started After executing step 3 (Start Broker + Proxy) in the document, if you encounter some challenging issues, be sure to run step 6 (Shut Down the Server) to safely close the nameserver and broker.

If you directly close the terminal and forcefully exit, the next time you try to start the Broker + Proxy, you'll find the Lock failed, MQ already started error in the broker's log. This usually means that a RocketMQ Broker instance is already running, or the previous instance abnormally terminated without properly releasing the lock file.

To resolve this, you need to:

1. Run ps aux | grep mqbroker to check if another Broker instance is indeed running. If you find any mqbroker processes other than the current grep command, you can terminate them with the kill command.
2. Locate and delete the lock file. The lock file is located in the RocketMQ runtime data storage (Store) directory, which is usually specified in the broker's configuration file (i.e., broker.conf) through the storePathRootDir parameter. If not specified, RocketMQ uses a default storage path depending on its installation and operating environment:

Linux / macOS: ~/store or /home/{username}/store.
Windows: C:\Users\{username}\store.

For MacOS, you can directly run the following command in the terminal to find the lock file:

find ~/store -name "lock" 2>/dev/null

Importance of this issue This documentation enhancement is a must-have for new users to avoid common pitfalls and improve their initial experience with RocketMQ. Currently, the workaround has been to search for solutions online, which can be time-consuming and may not always lead to accurate information.