Instgo compilation tool
Instgo is a compile-time instrumentation tool that adds Application Real-Time Monitoring Service (ARMS) monitoring to Go applications. Prepend instgo to your standard go build command, and the compiled binary automatically reports the following monitoring data to ARMS:
Application topology
Call chains
SQL analysis
No source code changes are required.
The following instructions apply to instgo 1.3.0 and later. Run instgo version to check your version. If it is earlier than 1.3.0, upgrade by following Start monitoring a Go application.Prerequisites
The build environment must have internet access or connectivity to an Alibaba Cloud internal network. The security group must allow outbound TCP traffic on port 80.
To deploy the compiled binary in a production environment, configure the LicenseKey and RegionId compilation parameters. For details, see Start monitoring a Go application.
Download instgo
Download the binary for your platform and region. Use
wgetto download instgo. Select the command that matches your operating system, CPU architecture, and region. Save instgo to a directory where the build user has write permissions, because instgo triggers an automatic update during compilation.The binary is identical across all regions. If your environment can reach Object Storage Service (OSS) public endpoints, use any region's public endpoint.
Grant execute permissions.
Linux/Darwin
chmod +x instgoWindows
No additional permissions are required.
Verify the installation.
Run the version command. A successful installation outputs a message similar to
Instgo version 1.3.0_dea8285.Linux/Darwin
Instgo version 1.3.0_dea8285Windows
./instgo version(Optional) Add instgo to your PATH for easier access.
Compile a Go application
Make sure the go command is in your PATH before compiling. Verify by running go version.
Prepend instgo to your existing go build command. All standard go build flags and arguments pass through unchanged.
Original command:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goWith instgo:
instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goIf instgo is not in your PATH, specify its full or relative path:
/path/to/instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goCompilation parameters
Run instgo list to view all available parameters and their current values.
Default parameters work for local development and testing. For production deployments, set the LicenseKey and RegionId before compiling.
Parameter reference
Required for production
Flag | Environment variable | Type | Default | Description |
|
| String | None | ARMS LicenseKey. Setting this disables developer mode. Retrieve it by calling the DescribeTraceLicenseKey API operation. |
|
| String | cn-hangzhou | Region for pulling the agent package and reporting compilation logs. If the build environment is in a VPC, set this to the region of that environment. |
|
| Bool | true | Developer mode. Enables testing with degraded features. Automatically disabled when LicenseKey is set. |
Agent configuration
Flag | Environment variable | Type | Default | Description |
|
| String | None | Pin a specific Golang agent version. |
|
| String | None | Local path to a pre-downloaded Golang agent. |
|
| String | None | Cache directory for the Golang agent. |
|
| Int | 180 | Timeout in seconds for pulling the Golang agent. |
|
| Bool | false | Pull the Golang agent over the internal network. |
Instrumentation control
Flag | Environment variable | Type | Default | Description |
|
| Bool | false | Disable all automatic code enhancements from ARMS. Use with caution. |
|
| String | None | Add a custom code enhancement template. See Use the custom extension feature of the Golang agent. |
|
| String | None | Apply non-base rules provided by the ARMS agent, such as |
|
| String | None | SDKs to exclude from instrumentation (for example, |
Build options
Flag | Environment variable | Type | Default | Description |
|
| Bool | false | Compile in vendor mode. |
|
| Bool | false | Print detailed compilation logs. |
|
| String | None | User ID for compilation, to prevent license key leakage. |
|
| String | None | Go cache path (for example, |
Persist parameters with the set command
The set command saves parameters to $HOME/.instgo.yaml. Subsequent compilations read these values automatically.
Configure instgo for production:
instgo set --licenseKey=${ARMS_LICENSEKEY} --regionId=${ARMS_REGIONID} --dev=falseThen compile as usual:
instgo go build -aReset parameters to defaults
instgo resetOverride parameters with environment variables
Environment variables apply only to the current shell session and take precedence over values saved with set.
Retrieve the LicenseKey by calling the DescribeTraceLicenseKey API 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"Then compile:
instgo go build -aAlternatively, set environment variables inline with the build command:
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 temporary files
Remove temporary compilation and runtime files from the current directory:
instgo cleanTo also delete locally cached Golang agents:
instgo clean --localAgentsUpdate instgo
Update instgo and the Golang agent to the latest versions:
instgo updateInstgo automatically updates at the start of each compilation based on the ARMS release schedule. In rare cases, this may cause the build to fail. Retry the build to resolve the issue.
If your instgo version is earlier than 1.3.0, the
updatecommand may not be available. Delete the existing binary and download the latest version instead.
Release history
Version | Release date | Changes |
1.4.7 | September 20, 2026 | Changed the default agent version to 2.11.0. |
1.4.6 | January 27, 2026 | Changed the default agent version to 2.3.0. Added the |
1.4.5 | January 9, 2026 | Changed the default agent version to 2.2.3. Added the |
1.4.4 | December 22, 2025 | Fixed Go version detection on Red Hat. Added the |
1.4.3 | December 9, 2025 | Changed the default agent version to 2.2.0. Reduced log output. |
1.4.2 | October 28, 2025 | Changed the default agent version to 2.0.4. Added |
1.4.1 | October 14, 2025 | Changed the default agent version to 2.0.4. Fixed incorrect Go version detection. |
1.4.0 | September 11, 2025 | Changed the default agent version to 1.8.6. Added pkg directory setting. Added conversion of custom rules from 1.x to 2.x format. |
1.3.9 | August 5, 2025 | Changed the default agent version to 1.8.5. Fixed |
1.3.8 | May 29, 2025 | Fixed a compilation failure when |
1.3.7 | May 19, 2025 | Added support for |
1.3.6 | April 28, 2025 | Changed the default agent version to 1.7.0. Added debug logs. |
1.3.5 | April 17, 2025 | Added vendor mode support. |
1.3.4 | March 31, 2025 | Added support for proxying native Go commands. |
1.3.3 | February 28, 2025 | Changed the default agent version to 1.6.0. |
1.3.2 | January 17, 2025 | Fixed an issue where users without write permissions on the instgo binary triggered repeated auto-updates. If you encounter this issue, delete instgo and download it again. |
1.3.1 | January 10, 2025 | Changed the default agent cache directory to |
1.3.0 | December 5, 2024 | Added prefix compilation mode. Added |