Connect an ECS microservice application to the MSE governance center - Microservices Engine

Microservices Engine (MSE) provides a Java agent that adds governance capabilities to your existing Spring Cloud or Dubbo applications without code changes. The agent attaches to your application's JVM, intercepts service calls at runtime, and applies the governance policies you configure in the MSE console.

This guide walks you through downloading the MSE Java agent, configuring it on an Elastic Compute Service (ECS) instance, and verifying the connection. The same steps apply to applications on non-Alibaba Cloud virtual machines (VMs).

How the agent works

The MSE Java agent runs as a JVM plugin (-javaagent). On startup, it authenticates with the MSE control plane using your region-specific license key, then intercepts inbound and outbound service calls to enforce governance policies. The agent reports application metadata to the MSE console, where your application appears under Microservices Governance > Application Governance.

Because MSE and Application Real-Time Monitoring Service (ARMS) share the same underlying agent, a single -javaagent attachment handles both governance and monitoring if you use both services.

Prerequisites

Before you begin, make sure that you have:

An ECS instance. For more information, see Create an ECS instance
A Java Development Kit (JDK) installed with the JAVA_HOME environment variable configured. For download links, see Java Downloads
JVM heap memory greater than 256 MB. The MSE Java agent cannot start with a smaller heap
An MSE Microservices Governance instance in the same region as your ECS instance. License keys are region-specific, so a region mismatch causes the agent to fail authentication

Note

MSE Microservices Governance is available in three editions: Basic Edition, Professional Edition, and Enterprise Edition. Choose the edition that matches your governance requirements.

Step 1: Download the MSE Java agent

Log on to the ECS console.
In the left-side navigation pane, choose Instances & Images > Instances.
In the top navigation bar, select a region.
On the Instances page, find the instance for which you want to enable Microservices Governance and click Connect in the Actions column.
In the Remote connection dialog box, select a connection method. For details, see Methods for connecting to an ECS instance.

Download the agent package. Replace ${regionId} with your actual region ID (for example, cn-hangzhou). For a full list of supported region IDs, see Supported regions. Download over the internet: Download over a VPC (recommended if your instance has no internet access): For example, to download the agent in the China (Hangzhou) region over the internet:

   wget http://arms-apm-${regionId}.oss-${regionId}.aliyuncs.com/AliyunJavaAgent.zip \
     -O AliyunJavaAgent.zip

   wget http://arms-apm-${regionId}.oss-${regionId}-internal.aliyuncs.com/AliyunJavaAgent.zip \
     -O AliyunJavaAgent.zip

   wget http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/AliyunJavaAgent.zip \
     -O AliyunJavaAgent.zip

Important

The agent package is region-specific. Always download the package that matches the region of your Microservices Governance instance.

Step 2: Install and configure the agent

Extract the agent package to a directory of your choice: Replace <your-install-dir> with the actual directory path, such as /opt/mse.
```
   unzip AliyunJavaAgent.zip -d /<your-install-dir>/
```

Add the following JVM parameters to your application's startup command: Replace the following placeholders with your actual values:

Important

The JVM heap memory must be greater than 256 MB. The agent fails to start with a smaller heap.

Placeholder	Description	Example
`<your-install-dir>`	Directory where you extracted the agent	`/opt/mse`
`<your-license-key>`	License key from the MSE console. Go to Microservices Governance > Overview to find it. Do not share this key.	`abcdef1234****`
`<your-app-name>`	A name that identifies your application in the MSE console	`order-service`

   java \
     -javaagent:/<your-install-dir>/AliyunJavaAgent/aliyun-java-agent.jar \
     -Dmse.licenseKey=<your-license-key> \
     -Dmse.appName=<your-app-name> \
     -Dprofiler.micro.service.mse.version=pro \
     -Dmse.namespace=default \
     -Dmse.enable=true \
     -jar application.jar

Parameter reference

Parameter	Description
`mse.licenseKey`	License key generated by MSE, visible on the Overview page of Microservices Governance. Region-specific. Keep it confidential.
`mse.appName`	Display name for your application in the MSE console.
`profiler.micro.service.mse.version`	Governance edition to enable. Valid values: `base` (Basic Edition), `pro` (Professional Edition), `ent` (Enterprise Edition).
`mse.namespace`	Governance namespace that this application belongs to. Query available namespaces in the MSE console.
`mse.enable`	Set to `true` to enable governance, or `false` to disable it.

If your application already uses ARMS

MSE and ARMS share the same Java agent. If the -javaagent parameter is already present in your startup command for ARMS, do not add it again. Append only the MSE-specific parameters (mse.licenseKey, mse.appName, profiler.micro.service.mse.version, mse.namespace, and mse.enable) to the existing command.

Step 3: Verify the connection

Log on to the MSE console.
In the top navigation bar, select the region that matches your application's deployment.
In the left-side navigation pane, choose Microservices Governance > Application Governance.
Confirm that your application appears in the application list. If it does, the agent is connected and governance is active.

What to do next

With Microservices Governance enabled, you can govern your Spring Cloud or Dubbo applications from the MSE console. Use the governance capabilities provided by MSE to improve the stability and development efficiency of your online microservice applications.