Use mseutil to diagnose instance issues - Microservices Engine

mseutil is a command-line tool. You can install mseutil on a client that runs the Linux, macOS, or Windows operating system, and use mseutil to diagnose issues of Microservices Engine (MSE) instances. You can also use mseutil to query and manage data of MSE instances. This topic describes how to install and use mseutil that runs on a Linux operating system. This topic also provides details about mseutil commands.

Prerequisites

An MSE Nacos instance or an MSE ZooKeeper instance is created. For more information, see Create a Nacos engine or Create a ZooKeeper engine.

Step 1: Download the mseutil tool

The mseutil tool can run on a Linux, macOS, or Windows operating system. You can download the mseutil tool from one of the following URLs based on the operating system that you use:

Linux x86_64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/linux/x86_64/mseutil

Linux arm64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/linux/arm64/mseutil

macOS x86_64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/darwin/x86_64/mseutil

macOS arm64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/darwin/arm64/mseutil

Windows x86_64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/windows/x86_64/mseutil

Windows arm64

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/windows/arm64/mseutil

For example, if you want to install mseutil on a Linux client, run the following command:

wget https://msetools.oss-cn-hangzhou.aliyuncs.com/mseutil/linux/x86_64/mseutil

The result in the following figure is returned.

Step 2: Obtain the endpoint of the instance in the MSE console

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance on which you want to perform operations by using mseutil.
On the Basic Information page, obtain the endpoint of the instance.
The following figure shows the internal endpoint of the instance. If you want to access the instance over the Internet, obtain the public endpoint based on the Public network address parameter.

Step 3: Use mseutil

In the mseutil command, you must specify the engine type of the instance on which you want to perform operations and the command that you want to run.

Run the following command to make mseutil executable:
```
chmod +x ./mseutil
```
Run the following command to perform operations on the instance. For more information about commands, see the Supported commands section in this topic.
```
mseutil [Subservice name] [Command for the subservice] [flags]
```
Note
In the preceding command, the subservice name indicates the engine type.

Examples

In the following examples, the connectivity issue between the client on which mseutil is installed and the MSE server on which a ZooKeeper or Nacos instance is deployed is diagnosed. API health checks are also performed. In actual situations, replace Instance endpoint in the following code with the endpoint obtained in Step 2.

ZooKeeper:

Run the following code:

mseutil zk --serverAddr ${Instance endpoint} inspect # Diagnose the connectivity issue between the mseutil client and the MSE ZooKeeper server, and perform an API health check.

The following result is returned.

Nacos:

Run the following code:

mseutil nacos --serverAddr ${Instance endpoint} inspect  # Diagnose the connectivity issue between the mseutil client and the MSE Nacos server, and perform an API health check.

The following result is returned.

Supported commands

The mseutil tool is quickly iterated. For more information about commands, run mseutil -h on the client.

The mseutil tool allows you to perform operations on Nacos instances and ZooKeeper instances. The commands for Nacos instances and ZooKeeper instances differ because their API parameters are different.

Note

The serverAddr parameter is required for both Nacos instances and ZooKeeper instances.

mseutil commands for ZooKeeper instances

Command	Description
`inspect`	This command is used to diagnose the connectivity issue between the client and the MSE server. This command can also be used to perform an API health check. The diagnostics consist of multiple steps, including basic network environment diagnostics and subservice API capability diagnostics. To obtain values of other parameters, run the `mseutil zookeeper inspect -h` command.
`get`	This command is used to obtain data in a specified path. The returned data is encoded in UTF-8. For example, you can run the following command to obtain the data in the `/zookeeper` path: `mseutil zookeeper get /zookeeper --serverAddr mse-xxxx.aliyuncs.com`
`set`	This command is used to update data in a specified path. For example, you can run the following command to update data in the `/test` path: `mseutil zookeeper set /test "testdata" --serverAddr mse-xxxx.aliyuncs.com --version=-1 #--version -v indicates the version of the data that you want to update.` Note If the update succeeds, `success` is returned.
`delete`	This command is used to delete data from a specified path. For example, you can run the following command to delete data from the `/test` path: `mseutil zookeeper delete /test --serverAddr mse-xxxx.aliyuncs.com --version=-1 #--version -v indicates the version of the data that you want to delete.` Note If data is deleted, `success` is returned.
`ls`	This command is used to list files under a specified path. For example, you can run the following command to list all files in the `/test` path: `mseutil zookeeper ls /test --serverAddr mse-xxxx.aliyuncs.com`
`stat`	This command is used to obtain the status of the znode in a specified path. For example, you can run the following command to obtain the status of the znode in the `/zookeeper` path: `mseutil zookeeper stat /zookeeper --serverAddr mse-xxxx.aliyuncs.com`
`4lw`	This command can be followed by all four-character commands of ZooKeeper instances. You can run the `mseutil zookeeper 4lw -h` command to obtain details about supported four-character commands. For example, you can run this command followed by the `stat` command to query the ZooKeeper instance status. `mseutil zookeeper 4lw stat --serverAddr mse-xxxx.aliyuncs.com`
`gs`	This command is used to obtain session IDs from a specified file. Note The specified file can only be Java logs of the client. By default, Java logs of the client are business logs.

mseutil commands for Nacos instances

Common item	Required	Default value	Description
`--namespaceId/-n`	No	<Null>	Specifies the ID of a namespace.
`--serviceName/-s`	Yes for the naming module	No default value	Specifies the name of a service.
`--groupName/-g`	No	`<DEFAULT_GROUP>`	Specifies the group of a service.
`--dataId/-D`	Yes for the config module	No default value	Specifies the name of a service.
`--groupName/-G`	No	`<DEFAULT_GROUP>`	Specifies the configuration group.
`--accessKey/-i`	No	No default value	Specifies the AccessKey ID for RAM authentication. This parameter is valid if authentication is enabled for MSE Nacos instances.
`--secretKey/-k`	No	No default value	Specifies the AccessKey secret for RAM authentication. This parameter is valid if authentication is enabled for MSE Nacos instances.

Subcommand	Parameter	Description
`inspect`	None	This command is used to diagnose the connectivity issue between the client and the server. This command can also be used to test the API availability for the server. The diagnostics consist of multiple steps. The execution result or failure reason of each step are returned. For more information about other items, you can run the `mseutil nacos inspect -h` command.
`get`	instance	This command is used to obtain all instances that are deployed for a specified service in a specified group in a specified namespace. Common items are inherited. For more information about other items, run the `mseutil nacos get -h` command.
`create`	instance	This command is used to register a specified `ip:port` with a specified service in a specified group in a specified namespace. Common items are inherited. The following items are additional items: `--clusterName/-c`: specifies the name of the cluster in which an instance resides. This item is optional and the default value is `DEFAULT`. `--ephemeral`: specifies whether an instance is a non-persistent instance. This item is optional and the default value is `false`. `--weight`: specifies the instance weight. This item is optional and the default value is `1.0`. For more information about other items, run the `mseutil nacos create -h` command.
`put`	instance

Diagnostics examples

DNS lookup fails, and the error message "no such host" is returned.

DNS resolution fails. Check whether the value of serverAddr is valid. If a container is used, check whether CoreDNS works properly.

The error message "dial tcp ip:port: i/o timeout" is returned for a connection test.

The test on the connection to an instance port times out. Check the network environment.

On the Basic Information page, check whether the MSE instance is in the Running state.
If you access the instance over the Internet, make sure that the public IP address of the environment in which mseutil runs is added to the public IP address whitelist of the instance. For more information about how to configure a public IP address whitelist for an instance, see Configure an IP address whitelist for Nacos instances or Configure an IP address whitelist for ZooKeeper instances.
Make sure that the port number is valid. The port number of the ZooKeeper instance is 2181. The port number of the Nacos instance is 8848.
Make sure that mseutil runs in the same virtual private cloud (VPC) as the MSE instance that you create.

The error message "ZooKeeper Api test error: zk: could not connect to a server" is returned.

Run the following code. If the message This ZooKeeper instance is not currently serving requests is returned, make sure that the MSE instance is in the Running state. In this case, the server is selecting a primary server. Perform the diagnostics again later.

mseutil zk --serverAddr ${Instance endpoint} 4lw stat

References

What do I do if the connection between an application and an MSE Nacos instance times out?