Instgo is a Golang application compilation tool provided by Application Real-Time Monitoring Service (ARMS). When you compile your Golang project with instgo, you enable ARMS to monitor your Golang application. This lets you view monitoring data such as application topology, call stacks, and SQL analysis.
This topic applies only to instgo tool versions 1.3.0 and later. To check your version, you can run the instgo version command. If your version is earlier than 1.3.0, you must upgrade it. For more information, see Start monitoring a Go application.
Prerequisites
Ensure that your compilation environment can connect to the internet or an Alibaba Cloud internal network. The security group for your compilation environment must allow outbound TCP traffic on port 80.
To deploy compiled artifacts in a production environment, you must set the LicenseKey and RegionId parameters. For more information, see Start monitoring a Go application.
Download instgo
Run the
wgetcommand to download the compilation tool. Select the download address that corresponds to your compilation environment and region.Instgo automatically updates during compilation. Therefore, you must save the instgo tool in a directory where the compilation user has write permissions.
NoteThe compilation tools are the same for all regions. If your environment can access Object Storage Service (OSS) over the internet, you can use the public endpoint for your operating system and architecture in the China (Hangzhou) region to download the tool.
Grant executable permissions to the compilation tool.
Linux/Darwin
# Grant executable permissions chmod +x instgoWindows
You do not need to grant executable permissions in Windows.
Verify that instgo is available.
Run the version command to check the instgo version. If the output is similar to
Instgo version 1.3.0_dea8285, the download was successful.Linux/Darwin
./instgo versionWindows
.\instgo.exe version(Optional) Add the instgo tool to the PATH environment variable of your compilation environment.
Use instgo to compile a Golang application
Before you compile a Golang application, ensure that the go command is in the PATH environment variable of your compilation environment. You can run the go version command to verify this.
The original compilation command for the Golang application is:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goThe compilation command that uses the instgo prefix mode is:
instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goIf instgo is not in your PATH, replace the prefix with the relative or absolute path to the instgo executable:
/path/to/instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goConfigure compilation parameters for instgo
Instgo provides compilation parameters to control its compilation behavior. You can run the instgo list command to view all compilation parameters and their current preset values.
You can use the default parameters to compile and deploy your Golang application. However, if you want to deploy artifacts to a production environment, you must specify the LicenseKey and RegionId before you compile.
Flag Key | Env Key | Parameter type | Default value | Description |
--agentVersion | INSTGO_AGENT_VERSION | String | None | Specifies the Golang agent version. |
--agentPath | INSTGO_AGENT_PATH | String | None | Specifies a local path for the Golang agent. |
--cacheDir | INSTGO_CACHE_DIR | String | None | Specifies the cache directory for the Golang agent. |
--dev | INSTGO_DEV | Bool | true | Specifies whether to use development mode. This mode is for testing basic features and may have some functional limitations. For production use, specify a LicenseKey. |
--disableDefaultRule | INSTGO_DISABLE_DEFAULT_RULE | Bool | false | Disables automatic code enhancement from ARMS. Use this with caution. |
--licenseKey | INSTGO_LICENSE_KEY | String | None | Specifies the ARMS LicenseKey. Setting this parameter disables development mode. To obtain your LicenseKey, see DescribeTraceLicenseKey. |
--regionId | INSTGO_REGION_ID | String | cn-hangzhou | Specifies the region for pulling the agent package and reporting compilation logs. If you are in a VPC environment, set this to the region of your compilation environment. |
--rule | INSTGO_RULE | String | None | Adds a code enhancement template for the Golang agent. For more information, see Use the custom extension capabilities of the Golang agent. |
--timeout | INSTGO_TIMEOUT | Int | 180 | Specifies the timeout in seconds for pulling the Golang agent. |
--verbose | INSTGO_VERBOSE | Bool | false | Prints detailed compilation logs. |
--vpc | INSTGO_VPC | Bool | false | Pulls the Golang agent from the internal network by default. |
--vendored | INSTGO_VENDORED | Bool | false | Compiles the project in vendor mode. |
--extra | INSTGO_EXTRA_RULES | String | None | Uses non-base rules provided by the ARMS Agent. For example, to inject the Python agent for the Dify Plugin, set the value to dify_python. Currently, only dify_python is supported. |
Use the set command to specify compilation parameters
You can use the set command to modify compilation parameters. The command saves the parameters to the $HOME/.instgo.yaml file. Subsequent compilations automatically read the preset values from this file.
For example, to set the compilation parameters for production mode and specify the LicenseKey and RegionId, run the following command:
instgo set --licenseKey=${ARMS_LICENSEKEY} --regionId=${ARMS_REGIONID} --dev=falseSubsequent compilations use these preset parameters by default.
instgo go build -aReset compilation parameters
If you have modified compilation parameters using the set command, you can run the reset command to restore all parameters to their default values.
instgo resetSpecify compilation parameters using environment variables
To add additional compilation parameters for a single compilation without saving them, you can set environment variables before you compile. Environment variables apply only to the current command-line session and do not affect other compilations.
For example, to set the compilation parameters for production mode and specify the licenseKey and regionId:
You can obtain the LicenseKey by calling the DescribeTraceLicenseKey OpenAPI operation.
Linux/Darwin
export INSTGO_LICENSE_KEY=${ARMS_LICENSEKEY}
export INSTGO_REGION_ID=${ARMS_REGIONID}
export INSTGO_DEV="false"Windows
$env:INSTGO_LICENSE_KEY=${ARMS_LICENSEKEY}
$env:INSTGO_REGION_ID=${ARMS_REGIONID}
$env:INSTGO_DEV="false"The compilation process first checks for corresponding environment variables. If they are not set, the process uses the compilation parameters that are preset by the set command.
instgo go build -aYou can also configure the compilation environment variables and the compilation command on the same line:
Linux/Darwin
INSTGO_LICENSE_KEY=${ARMS_LICENSEKEY} INSTGO_REGION_ID=${ARMS_REGIONID} INSTGO_DEV="false" instgo go build -aWindows
$env:INSTGO_LICENSE_KEY=${ARMS_LICENSEKEY}; $env:INSTGO_REGION_ID=${ARMS_REGIONID}; $env:INSTGO_DEV="false"; instgo.exe go build -aClean up Golang observability temporary files
You can run the clean command to clean up temporary compilation and runtime files in the current directory. For example:
instgo cleanTo delete the locally cached Golang agent, add the --localAgents flag:
instgo clean --localAgentsManually upgrade the instgo tool
If you have an older version of instgo, you can run the update command to update your instgo tool and Golang agent to the latest version available online. For example:
instgo updateBy default, instgo automatically updates at compile-time based on the ARMS release schedule. In some edge cases, a compilation failure may occur. If this happens, you can try to compile the application again to resolve the issue.
If your instgo version is earlier than 1.3.0, the
updatecommand may not be available. In this case, you must delete the instgo tool and download the latest version.
Instgo release notes
Version | Release date | Description |
1.4.2 | October 28, 2025 |
|
1.4.1 | October 14, 2025 |
|
1.4.0 | September 11, 2025 |
|
1.3.9 | August 5, 2025 |
|
1.3.8 | May 29, 2025 |
|
1.3.7 | May 19, 2025 |
|
1.3.6 | April 28, 2025 |
|
1.3.5 | April 17, 2025 | Added support for compiling projects in vendor mode. |
1.3.4 | March 31, 2025 | Added support for proxying native Go commands. |
1.3.3 | February 28, 2025 | Updated the default agent version to 1.6.0. |
1.3.2 | January 17, 2025 | Fixed an issue where repeated update attempts occurred due to automatic update failures when the user lacked write permissions for instgo. Note If you encounter this issue, delete the instgo tool and download the latest version. |
1.3.1 | January 10, 2025 | For Linux and Darwin operating systems, the default agent cache directory is changed to |
1.3.0 | December 5, 2024 |
|