Instgo is a Golang compilation tool provided by ARMS. After you compile your Golang project with Instgo, ARMS can monitor your Golang application. You can then view monitoring data such as application topology, call traces, and SQL analysis.
This topic applies only to Instgo versions 1.3.0 and later. You can run instgo version to check your tool version. If your tool is earlier than version 1.3.0, see Start monitoring Go applications to upgrade it to version 1.3.0.
Prerequisites
Ensure that your compilation environment can connect to the internet or an Alibaba Cloud private network. The security group for the environment must allow outbound TCP traffic on port 80.
To deploy the compiled artifact in a production environment, you must configure the `LicenseKey` and `RegionId` compilation parameters. For more information, see Start monitoring Go applications.
Download instgo
You can use the
wgetcommand to download the compilation tool. Select the download address that corresponds to your compilation environment and region.Note: Instgo automatically updates during compilation. Save the Instgo tool in a directory where the user has modification permissions.
NoteThe compilation tool is the same for all regions. If your environment can access Object Storage Service (OSS) over the internet, you can use the public network address for the China (Hangzhou) region to download the tool for your operating system and architecture.
Make the compilation tool executable.
Linux/Darwin
# Make the file executable chmod +x instgoWindows
Executable permissions are not required in Windows.
Check if Instgo is available.
You can run the `version` command to check the Instgo version. If the output shows
Instgo version 1.3.0_dea8285, the download is successful.Linux/Darwin
./instgo versionWindows
.\instgo.exe version(Optional) You can add the Instgo tool to the PATH of your compilation environment.
Use instgo to compile a Golang application
When you compile a Golang application, ensure that the `go` command is in your environment's PATH. You can run go version to verify this.
Original compilation command for the Golang application:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goCompilation command using the Instgo prefix mode:
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 tool:
/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 a set of compilation parameters to control its compilation behavior. You can run the instgo list command to view all parameters and their current values.
You can use the default parameters to compile and deploy your Golang application. However, if you plan to deploy the artifact 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 probe version. |
--agentPath | INSTGO_AGENT_PATH | String | None | Specifies a local path for the Golang probe. |
--cacheDir | INSTGO_CACHE_DIR | String | None | Specifies the cache directory for the Golang probe. |
--dev | INSTGO_DEV | Bool | true | Specifies development mode for compilation. This mode is for testing basic features. Some features may be degraded. For production use, specify a `LicenseKey`. |
--disableDefaultRule | INSTGO_DISABLE_DEFAULT_RULE | Bool | false | Disables code enhancement provided by ARMS. If enabled, all automatic code enhancements from ARMS are blocked. Use with caution. |
--licenseKey | INSTGO_LICENSE_KEY | String | None | Specifies the ARMS LicenseKey. When this parameter is set, development mode is disabled by default. You can get the LicenseKey using an OpenAPI. For more information, see DescribeTraceLicenseKey - List LicenseKeys. |
--regionId | INSTGO_REGION_ID | String | cn-hangzhou | Specifies the region for pulling the probe package and reporting compilation logs. If your compilation environment is in a VPC, set this to the region of your environment. |
--rule | INSTGO_RULE | String | None | Adds a Golang probe code enhancement template. For more information, see Use the custom extension feature of the Golang probe. |
--timeout | INSTGO_TIMEOUT | Int | 180 | Specifies the timeout for pulling the Golang probe, in seconds. |
--verbose | INSTGO_VERBOSE | Bool | false | Prints detailed compilation logs. |
--vpc | INSTGO_VPC | Bool | false | Pulls the Golang probe from the private network by default. |
--vendored | INSTGO_VENDORED | Bool | false | Compiles using vendor mode. |
--extra | INSTGO_EXTRA_RULES | String | None | Applies non-base rules from the ARMS Agent. For example, set the value to `dify_python` to inject the Python probe into the Dify Plugin. Currently, only `dify_python` is supported. |
Specify compilation parameters with the set command
You can use the set command to modify compilation parameters. The command saves the parameters to the $HOME/.instgo.yaml file. Subsequent compilation commands automatically read the preset values from this file.
For example, to specify production mode and set the LicenseKey and RegionId:
instgo set --licenseKey=${ARMS_LICENSEKEY} --regionId=${ARMS_REGIONID} --dev=falseSubsequent compilations use these preset parameters by default.
instgo go build -aReset compilation parameters
After you modify parameters with the set command, you can use the reset command to restore all parameters to their default values.
instgo resetSpecify compilation parameters using environment variables
To add parameters for a single compilation without affecting other compilations, you can use environment variables. Environment variables apply only to the current command line session.
For example, to specify production mode and set the licenseKey and regionId:
You can obtain the LicenseKey by calling the DescribeTraceLicenseKey OpenAPI.
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 environment variables. If they are not set, the process uses the parameters configured with 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 remove compilation and runtime artifacts from the current directory. For example:
instgo cleanTo delete the locally cached Golang probe, you can 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 both Instgo and the Golang probe to the latest available versions. For example:
instgo updateBy default, Instgo automatically updates during compilation based on the ARMS release schedule. In some edge cases, compilation might fail. A retry usually resolves 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 old Instgo tool and download the latest version.
Instgo release history
Version | Release date | Release notes |
1.4.3 | December 9, 2025 |
|
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 | instgo now supports compiling projects in vendor mode. |
1.3.4 | March 31, 2025 | instgo now supports 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 a failed auto-update caused repeated update attempts during compilation for users without modification permissions for the instgo file. Note If you encounter this issue, delete your instgo file and download it again. |
1.3.1 | January 10, 2025 | On Linux/Darwin operating systems, the probe cache is now located in the |
1.3.0 | December 5, 2024 |
|