Instgo is a compilation tool provided by Application Real-Time Monitoring Service (ARMS) for Golang applications. After you compile your Golang project with instgo, ARMS can monitor the application. You can then view monitoring data, such as application topology, call chains, and SQL analysis.
This topic applies only to instgo versions 1.3.0 and later. You can run the instgo version command to check the instgo version. 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 the compiled artifact in a production environment, you must configure the LicenseKey and RegionId compilation parameters. For more information, see Start monitoring a Go application.
Download instgo
Use the
wgetcommand to download the compilation tool. Select the download address based on your compilation environment and the region where your machine is located.Note that instgo triggers an automatic update during compilation. Save instgo to a directory for which the compilation user has modification permissions.
NoteThe compilation tool is the same for all regions. If your public network environment can access Object Storage Service (OSS) addresses, you can use the public endpoint for China (Hangzhou) that corresponds to your operating system and architecture to obtain the tool.
Grant executable permissions to the compilation tool.
Linux/Darwin
# Grant executable permissions chmod +x instgoWindows
No executable permissions are required in Windows.
Check if instgo is available.
Run the version command to view the instgo version. If a message similar to
Instgo version 1.3.0_dea8285is displayed, the download was successful.Linux/Darwin
./instgo versionWindows
.\instgo.exe version(Optional) Add the instgo tool to the PATH of your compilation environment.
Compile a Golang application using instgo
When you compile a Golang application, ensure that the `go` command is in the PATH of your compilation environment. You can run the go version command to verify this.
Original compilation command for a Golang application:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goCompilation command using instgo in prefix mode:
instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goIf instgo is not saved in your PATH, replace the prefix with the relative or absolute path to instgo:
/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 series of compilation parameters to control its compilation behavior. You can run the instgo list command to view all available compilation parameters and their current values.
You can use the default parameters to compile and deploy your Golang application. However, to deploy the artifact to a production environment, you must specify the LicenseKey and RegionId before compilation.
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 the compilation mode as developer mode. This mode is for testing basic feature availability. Some features may be degraded. To use the application online, specify the LicenseKey. |
--disableDefaultRule | INSTGO_DISABLE_DEFAULT_RULE | Bool | false | Specifies whether to disable the code enhancement provided by ARMS. If enabled, this setting blocks all automatic code enhancements from ARMS. Use with caution. |
--licenseKey | INSTGO_LICENSE_KEY | String | None | Specifies the LicenseKey for ARMS. When this parameter is specified, developer mode is disabled by default. You can obtain the LicenseKey by calling an OpenAPI operation. For more information, see DescribeTraceLicenseKey - List LicenseKeys. |
--regionId | INSTGO_REGION_ID | String | cn-hangzhou | Specifies the region from which to pull the agent package and to which compilation logs are reported. If the compilation environment is a VPC, change this to the region where your compilation environment is located. |
--rule | INSTGO_RULE | String | None | Adds a code enhancement template for the Golang agent. For more information about how to use this parameter, see Use the custom extension feature of the Golang agent. |
--timeout | INSTGO_TIMEOUT | Int | 180 | Specifies the timeout period for pulling the Golang agent, in seconds. |
--verbose | INSTGO_VERBOSE | Bool | false | Specifies whether to print detailed compilation logs. |
--vpc | INSTGO_VPC | Bool | false | Specifies whether to pull the Golang agent over the internal network by default. |
--vendored | INSTGO_VENDORED | Bool | false | Compiles the project in vendor mode. |
--extra | INSTGO_EXTRA_RULES | String | None | Used to apply non-Base rules provided by the ARMS Agent, such as injecting the Python agent into a Dify Plugin (value: dify_python). Currently, only dify_python is supported. |
--disable | INSTGO_DISABLE_RULES | String | None | Used to specify SDKs that should not be instrumented during instrumentation (such as gin.json or fasthttp.json). If set to all, no instrumentation is performed. |
--uid | INSTGO_ARMS_UID | String | None | Used to configure the user ID for compilation. |
--goCache | INSTGO_GO_CACHE | String | None | Used to configure the Go cache path for compilation, such as /tmp/go-cache, to speed up compilation. |
Specify compilation parameters using the set command
You can use the set command to modify compilation parameters. This command saves the specified parameters to the $HOME/.instgo.yaml file. Subsequent compilation commands automatically read these preset values from the file.
For example, to set the compilation parameters for production mode and specify the LicenseKey and RegionId:
instgo set --licenseKey=${ARMS_LICENSEKEY} --regionId=${ARMS_REGIONID} --dev=falseSubsequent compilations will use the preset compilation parameters by default.
instgo go build -aReset compilation parameters
After you modify compilation parameters with the set command, you can use the reset command to reset all parameters to their default values.
instgo resetSpecify compilation parameters using environment variables
To add compilation 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 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 in the current command line session first checks for corresponding environment variables. If environment variables are not set, the process uses the compilation parameters that were preset using 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 temporary compilation and runtime files from the current directory. For example:
instgo cleanTo delete locally cached Golang agents, 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. This command updates them to the latest versions available online. For example:
instgo updateBy default, instgo automatically updates at the start of each compilation based on the ARMS release schedule. In some edge cases, this may cause the compilation to fail. Retrying the compilation 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 existing instgo tool and download the latest version.
Instgo release history
Version | Release date | Release notes |
1.4.6 | January 27, 2026 |
|
1.4.5 | January 9, 2026 |
|
1.4.4 | December 22, 2025 |
|
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 project compilation 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 users without modification permissions for instgo would trigger repeated updates due to auto-update failures during compilation. Note If you encounter this issue with your instgo tool, delete it and download it again. |
1.3.1 | January 10, 2025 | On Linux and Darwin operating systems, the default agent cache directory is changed to |
1.3.0 | December 5, 2024 |
|