Installing the Go agent enables Application Real-Time Monitoring Service (ARMS) to monitor your Go application, providing data on the application topology, traces, and SQL analysis.
For applications in a Kubernetes environment, do not install the agent manually. Instead, use the provided component to integrate the application with ARMS. For more information, see Install the Go agent for Container Service for Kubernetes (ACK) and Container Compute Service (ACS) using the ack-onepilot component.
If you have questions about the Go agent, contact us in our DingTalk Q&A group (ID: 159215000379).
Prerequisites
Your build environment must be able to connect to the internet or an Alibaba Cloud internal network. Ensure that your security group allows outbound TCP traffic on ports 8080, 9990, 80, and 443.
Check your network environment. For more information, see Network configurations for Go application monitoring.
Check the operating system, architecture, Go version, and framework version of your build environment. For more information, see Go components and frameworks supported by ARMS Application Monitoring.
Step 1: Compile the Go application image
To use ARMS Go application monitoring, you only need to use the instgo tool at build time by adding instgo as a prefix to your original go build command. You do not need to modify any business code or integrate the OpenTelemetry SDK. The instgo agent implements automatic instrumentation based on the OpenTelemetry standard, inserting monitoring code automatically during the AST analysis stage at compile time.
(Optional) If your project includes a vendor directory during the build, add
-mod=vendoraftergo build.Use the
wgetcommand to download the instgo build tool. Select a download URL based on your build environment's operating system and architecture.Note that instgo automatically updates during the build process. Make sure to save instgo in a directory where the build user has write permissions.
Noteinstgo is a build tool from ARMS that instruments your Go project, enabling ARMS to monitor your application.
If you have internet access to Object Storage Service (OSS), use the China (Hangzhou) download URL that corresponds to your operating system and architecture.
Make the build tool executable.
Linux/Mac
# Grant the executable permission. chmod +x instgoWindows
You do not need to grant executable permission in Windows.
(Optional) Configure a UID as a build parameter.
ImportantIf you skip this step, instgo installs the latest version of the ARMS agent by default.
Use the
setcommand to configure a UID as a build parameter.instgo set --uid={YourAliyunUid} // instgo 1.4.5 or later is required. The UID is the ID of your Alibaba Cloud primary account.Add
instgoas a prefix to your original build command and run the command.instgo go build {arg1} {arg2} {arg3}If you use
go installto build the project, you can also addinstgoas a prefix to your original build command.Use the binary file generated in the previous step to build an image.
Step 2: Configure environment variables
After the build, add the following environment variables to your Go application:
export ARMS_ENABLE=true export ARMS_APP_NAME=xxx # The name of your application. export ARMS_REGION_ID=xxx # The region ID of your Alibaba Cloud account. export ARMS_LICENSE_KEY=xxx # The license key from the ARMS console.NoteIf you want to report data over the internet by default, you can set the environment variable
ARMS_NETWORK_STRATEGY=public.Instead of exporting environment variables, you can use the -ldflags flag to specify them during the build process.
Replace
modulewith the module name configured in go mod. For other parameters, refer to environment variables.instgo go build -ldflags " -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.ArmsApmName=${appName}' -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.ArmsEnable=true' -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.LicenseKey=${licenseKey}' -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.RegionId=${regionId}'"If you use systemctl to start your application, you can use the following commands to set the environment variables:
systemctl set-environment ARMS_ENABLE=true systemctl set-environment ARMS_APP_NAME=xxx # The name of your application. systemctl set-environment ARMS_REGION_ID=xxx # The region ID of your Alibaba Cloud account. systemctl set-environment ARMS_LICENSE_KEY=xxx # The license key from the ARMS console.
(Optional) Dockerfile configuration
If you are using a Docker environment, modify your Dockerfile according to the following example.
FROM golang:1.21 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN wget "http://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/instgo/instgo-linux-amd64" -O instgo
RUN chmod +x instgo
RUN ./instgo go build -o myapp .
FROM debian:bookworm-slim
WORKDIR /app
COPY --from=builder /app/myapp .
ENV ARMS_ENABLE=true
ENV ARMS_APP_NAME=AppName
ENV ARMS_REGION_ID=regionId
ENV ARMS_LICENSE_KEY=licenseKey
EXPOSE 8080
CMD ["./myapp"]Verify the results
After about one minute, check the page in the ARMS console. If your application appears and is reporting data, the agent installation was successful.