Instgo is a Go application compilation tool provided by Application Real-Time Monitoring Service (ARMS). After compiling your Go project with Instgo, ARMS can begin monitoring your Go application, allowing you to view a variety of monitoring data such as application topology, traces, and SQL analysis.
This topic is only applicable to versions of the Instgo tool that are 1.3.0 or higher. You can check your Instgo tool version with the command instgo version. If your Instgo tool version is earlier than 1.3.0, upgrade it to version 1.3.0. For more information, see Monitor Go applications.
Prerequisites
The compilation environment is connected to the public network or an Alibaba Cloud internal network, and that the security group where your compilation environment resides has opened TCP outbound permissions for port 80.
The LicenseKey and RegionId parameters have been configured, which is required if you want to deploy a compilation artifact in the production environment. For more information, see Monitor Go applications.
Download Instgo
Run the
wgetcommand to download the compilation tool based on the region where the environment and tool reside. Then, store the tool in a directory where you have the write permission, because it will be automatically updated during compilation.NoteIf you are able to access Object Storage Service (OSS) over the Internet, you can directly use the public endpoint of the operating system and architecture in the China (Hangzhou) region to obtain the compilation tool.
Grant the compilation tool the permissions required to perform the related operations.
Linux/Darwin
# Grant the permissions. chmod +x instgoWindows
In Windows, you do not need to grant permissions.
Check whether Instgo is available.
Run the instgo version command to check the Instgo version. For example, the output
Instgo version 1.3.0_dea8285indicates that the Instgo version is 1.3.0.Linux/Darwin
./instgo versionWindows
.\instgo.exe versionOptional. Add Instgo to the path of the compilation environment.
Use Instgo to compile the Go application
When compiling a Go application using the prefix pattern, you need to ensure that the go command is included in the PATH of your compilation environment. You can verify if the go command is in the PATH by executing go version in your compilation environment.
(Recommended) Use the prefix pattern to compile the Go application
Starting from v1.3.0, Instgo has been providing the prefix pattern for compiling your Go applications. You only need to add the instgo prefix before your compilation command. Example:
Original compilation command of the Go application:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goCompilation command with the instgo prefix:
instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goIf Instgo is not stored in the path of the compilation environment, replace the prefix with the relative or absolute path of Instgo. Example:
/path/to/instgo go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goUse the build command to compile the Go application
The maintenance of the build command has been discontinued since v1.3.0, but your normal use is not affected. We recommend that you replace the build command with the prefix pattern.
You can replace go build in the command with ./instgo build and add the original compilation parameters after the -- symbol. For example:
Original compilation command of the Go application:
go build -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goCompilation command with the instgo prefix:
instgo build -- -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goIf Instgo is not stored in the path of the compilation environment, replace the prefix with the relative or absolute path of Instgo. Example:
/path/to/instgo build -- -ldflags "-X main.Env=prod -X main.Version=1.0.0" -o app main.goConfigure Instgo compilation parameters
Compilation parameters only take effect for the prefix pattern and automatic update commands. When using the build command method for compilation, you need to specify the compilation parameters through flag keys each time you compile.
Instgo provides a series of compilation parameters to control the behavior of the Instgo compilation process. You can use the instgo list command to view all compilation parameters and their current preset values.
You can complete the compilation and deployment of your Golang application using the default parameters. However, if you intend to deploy the artifacts to a production environment, we recommend that you specify LicenseKey and RegionId before proceeding with the compilation.
Flag key | Environment key | Parameter data type | Default value | Description |
--agentVersion | INSTGO_AGENT_VERSION | String | None | Specifies the version of the ARMS agent for Go. |
--agentPath | INSTGO_AGENT_PATH | String | None | Specifies the local path of the agent. |
--cacheDir | INSTGO_CACHE_DIR | String | None | Specifies the cache directory of the agent. |
--dev | INSTGO_DEV | Bool | true | Specifies the Development Mode as the compilation mode. This mode is used to test the availability of basic features. Some features may be degraded. For production environment use, specify the LicenseKey parameter. |
--disableDefaultRule | INSTGO_DISABLE_DEFAULT_RULE | Bool | false | Specifies whether to disable the code enhancement provided by ARMS. If you enable this, automatic code enhancement is blocked. Disable it with caution. |
--licenseKey | INSTGO_LICENSE_KEY | String | None | Specifies the LicenseKey of ARMS. Configuring this parameter will disable the Development Mode. To obtain the LicenseKey, you can call the DescribeTraceLicenseKey operation in OpenAPI Explorer. For more information, see DescribeTraceLicenseKey. |
--mse | INSTGO_MSE | Bool | false | Specifies whether to enable MSE Microservices Governance for the application. For more information, see Enable MSE Microservices Governance for Go microservice applications in an ACK cluster. |
--regionId | INSTGO_REGION_ID | String | cn-hangzhou | Specifies the region where you want to pull the agent package or report the compilation logs. If the compilation environment is a virtual private cloud (VPC), specify the region where your compilation environment is located. |
--rule | INSTGO_RULE | String | None | Specifies a code enhancement template for the agent. For more information, see Use the ARMS agent for Go to customize scalability. |
--timeout | INSTGO_TIMEOUT | Int | 180 | Specifies the timeout period for pulling the agent package. Unit: seconds. |
--verbose | INSTGO_VERBOSE | Bool | false | Specifies whether to print detailed compilation logs. |
--vpc | INSTGO_VPC | Bool | false | Specifies whether to pull the agent package through an interval network. |
Use the set command to configure compilation parameters
You can use the set command to modify compilation parameters. This command saves the set compilation parameters to a $HOME/.instgo.yaml file. Subsequent compilation commands automatically read the preset values in this file.
For example, if you select the Production Mode and specify the LicenseKey and RegionId parameters, the command is as follows:
instgo set --licenseKey=${YourLicenseKey} --regionId=${YourRegionId} --dev=falseIn the subsequent compilation process, the preceding preset compilation parameters are used by default.
instgo go build -aReset the compilation parameters
After you modify the compilation parameters using the set command, you can reset all the parameters back to their default values through the reset command.
instgo resetUse environment variables to configure compilation parameters
If you need to add extra compilation parameters for a single compilation and do not want to save these parameters to avoid affecting other compilation commands, you can specify the compilation parameters using environment variables before compiling. The environment variables will only affect the current command line and will not impact other compilation commands executed in other command lines.
For example, if you select the Production Mode and specify the LicenseKey and RegionId parameters, the command is as follows:
Linux/Darwin
export INSTGO_LICENSE_KEY=${YourLicenseKey}
export INSTGO_REGION_ID=${YourRegionId}
export INSTGO_DEV="false"Windows
$env:INSTGO_LICENSE_KEY=${YourLicenseKey}
$env:INSTGO_REGION_ID=${YourRegionId}
$env:INSTGO_DEV="false"In the compilation executed by the current command line, whether the corresponding environment variables are set will be queried first by default. If not, the compilation parameters preset by the set command will be used for image compilation.
instgo go build -aYou can also write the environment variables and the compilation command on the same line. Example:
Linux/Darwin
INSTGO_LICENSE_KEY=${YourLicenseKey} INSTGO_REGION_ID=${YourRegionId} INSTGO_DEV="false" instgo go build -aWindows
$env:INSTGO_LICENSE_KEY=${YourLicenseKey}; $env:INSTGO_REGION_ID=${YourRegionId}; $env:INSTGO_DEV="false"; instgo.exe go build -aClear temporary files of the agent
You can run the clean command to clear the compilation and runtime residues in the current directory. For example:
instgo cleanIf you need to delete the locally cached agent, you can add the --localAgents flag.
instgo clean --localAgentsManually upgrade Instgo
If your Instgo version is outdated, you can update Instgo and the agent through the update command. This command will upgrade Instgo and the agent to the latest version currently available in production environments. Example:
instgo updateBy default, Instgo will automatically update according to the ARMS release schedule during compilation. In some edge cases, occasional compilation failures may occur, which can typically be resolved by retrying once.
If your Instgo version is earlier than 1.3.0, the
updatecommand may not be available; in this case, please delete the current Instgo and download the latest version of Instgo directly.
Release notes
Version | Release date | Description |
1.3.2 | January 17, 2025 | The issue of repeated instgo update attempts due to failed automatic updates is fixed. This was caused by a lack of write permissions for instgo. Note If this issue occurs to your instgo, delete the tool and download a new one. |
1.3.1 | January 10, 2025 | In Linux and Darwin operating systems, the default agent cache directory has been changed to |
1.3.0 | December 5, 2024 |
|