You can use Application Real-Time Monitoring Service (ARMS) to monitor Go applications that run in a general-purpose Kubernetes environment. This lets you monitor metrics such as application topology, API calls, slow transactions, and SQL analysis. This topic describes how to integrate a Go application in a general-purpose Kubernetes environment with Application Monitoring.
This topic does not apply if your Kubernetes cluster is an Alibaba Cloud Container Service for Kubernetes (ACK) cluster. To connect an ACK cluster to ARMS, see Install a Go agent in a Container Service for Kubernetes (ACK) or Container Compute Service (ACS) cluster using the ack-onepilot component.
Prerequisites
The kube-apiserver component in your Kubernetes cluster must be version 1.10 or later.
If your Kubernetes cluster is not deployed on Alibaba Cloud, ensure that it can access the Internet. Alternatively, you can establish a network connection between an Alibaba Cloud Virtual Private Cloud (VPC) and the cluster using a method such as Cloud Enterprise Network (CEN).
Your Go application must be version 1.18 or later.
Step 1: Compile the Go application image
If your project uses go vendor to manage dependencies, make sure the go.mod file includes the google.golang.org/protobuf dependency, which can be direct or indirect. Then, add the -mod=vendor flag to your compile command.
If your project is not compiled using go vendor, you do not need to perform these operations.
Method 1 (recommended): Manually build the Go application image
Use the
wgetcommand to download the compile tool instgo. Select the download address based on your compile-time environment and your machine's region.instgo automatically updates during compilation. Save the instgo file in a directory where the current user has write permissions.
NoteInstgo is a compile tool for Go applications provided by ARMS. Compiling your Go project with instgo allows ARMS to monitor your application.
The compile tools for all regions are the same. If your environment can access Object Storage Service (OSS) over the Internet, you can use the public endpoint for the corresponding operating system and architecture in the China (Hangzhou) region to download the tool.
Add executable permissions to the compile tool.
Linux/Darwin
# Add executable permissions. chmod +x instgoWindows
You do not need to add executable permissions in Windows.
Obtain the LicenseKey and configure compile parameters.
ImportantIf you skip this step, instgo enters dev mode and installs the latest version of the ARMS probe by default. To deploy in a production environment, configure the following parameters.
You can obtain the LicenseKey by calling the DescribeTraceLicenseKey OpenAPI operation.
On the DescribeTraceLicenseKey documentation page, click Debug. Select a region and then click Initiate Call to obtain the LicenseKey.
After you obtain the LicenseKey, use the
setcommand to configure the compile parameters.instgo set --licenseKey=${YourLicenseKey} --regionId=${YourRegionId} --dev=false
Add instgo as a prefix to your original compile command and run it.
instgo go build {arg1} {arg2} {arg3}If you use go install to compile your project, you can also add instgo as a prefix to your original compile command and run it.
Use the binary file compiled in the previous step to build an image.
Related information
During the first compilation, the probe is downloaded to the
/optdirectory (C:\ProgramDatafor Windows) by default. If the directory does not have the required permissions, runinstgo set --cacheDir="./"to set the cache directory to the current directory, or run thesudo -Ecommand to perform the compilation. For Windows, you must run the compile command with administrator permissions.If the compilation is forcibly stopped or exits unexpectedly, residual files may remain. To clean up residual files from the Go probe compilation, see Clean up residual files from Go probe compilation.
Method 2: Non-intrusive build of the Go application image
This method is supported only for Go 1.23 and earlier versions.
Replace the base image in the Go binary file build stage with an ARMS compile image to non-intrusively build the Go application image.
ARMS provides compile images for AMD64 and ARM64 architectures on Alpine Linux and Debian Linux.
For example, the following Dockerfile shows how to use Docker multi-stage builds to build a Go application image:
# stage 1
FROM golang:1.22-alpine3.19 as builder
RUN --mount=type=ssh \
go build -v -buildmode=pie -ldflags "-linkmode external -extldflags -static" \
-o /workspace/demo
# stage 2
FROM alpine
COPY --from=builder /workspace/demo /demo
# Specify the default startup command.
CMD ["/demo"]The example Dockerfile has two stages:
The first stage builds the Go binary file.
The second stage copies the binary file from the first stage into the runtime image and uses it to build the runtime image for the Go application.
Replace the base image in the Go binary file build stage with an ARMS compile image. All other commands can remain the same. The following code shows the modified Dockerfile:
# stage 1
# Replace with the ARMS compile image. The rest remains the same.
# Replace with the image of the corresponding region as needed.
FROM registry-cn-hangzhou.ack.aliyuncs.com/acs/golangbuilder-alpine-linux-amd64:0.0.1 as builder
RUN --mount=type=ssh \
go build -v -buildmode=pie -ldflags "-linkmode external -extldflags -static" \
-o /workspace/demo
# stage 2
FROM alpine
COPY --from=builder /workspace/demo /demo
# Specify the default startup command.
CMD ["/demo"]Step 2: Install Helm 3
Step 3: Install the agent
Application Monitoring supports stateless applications (deployments) and stateful applications (StatefulSets). The integration method is the same for both application types. This section uses a stateless application (deployment) as an example.
Run the following
wgetcommand to download the ack-onepilot installation package.wget 'https://aliacs-app-catalog.oss-cn-hangzhou.aliyuncs.com/charts-incubator/ack-onepilot-5.1.1.tgz'Run the following command to decompress the ack-onepilot installation package.
tar xvf ack-onepilot-5.1.1.tgzEdit the values.yaml file in the installation package. Modify the following parameters as needed and save the file.
registry: registry-__ACK_REGION_ID__.ack.aliyuncs.com/acs/ cluster_id: __ACK_CLUSTER_ID__ accessKey: __ACCESSKEY__ accessKeySecret: __ACCESSKEY_SECRET__ uid: "__ACK_UID__" region_id: __ACK_REGION_ID__registry: The address of the ack-onepilot image.cluster_id: A custom ID for the Kubernetes cluster. This ID must be unique. The recommended format is<uid>-<clusterid>.accessKeyandaccessKeySecret: The AccessKey ID and AccessKey secret of your Alibaba Cloud account. For more information about how to obtain an AccessKey pair, see Create an AccessKey pair.ImportantEnsure that the AliyunARMSFullAccess and AliyunSTSAssumeRoleAccess permissions are granted to the Alibaba Cloud account.
uid: The ID of your Alibaba Cloud account. To obtain the ID, hover over your profile picture in the upper-right corner of the Alibaba Cloud Management Console.region_id: The ID of the Alibaba Cloud region. For more information about the regions that support Application Monitoring, see Supported regions.
Run the following command to install ack-onepilot.
Run this command from outside the ack-onepilot installation package directory.
helm3 upgrade --install ack-onepilot ack-onepilot --namespace ack-onepilot --create-namespace
Step 4: Modify the application's YAML file
Run the following command to view the YAML file of the target stateless application (deployment).
kubectl get deployment {deployment-name} -o yamlNoteIf you do not know the
{deployment-name}, run the following command to view all stateless applications (deployments). Find the target deployment in the results, and then view the YAML file of the target deployment.kubectl get deployments --all-namespaceEdit the YAML file of the target stateless application (deployment).
kubectl edit deployment {Deployment-name} -o yamlIn the YAML file, add the following content under the
spec.template.metadatalevel.labels: aliyun.com/app-language: "golang" # Required for Go applications. This label indicates that the application is a Go application. armsPilotAutoEnable: "on" armsPilotCreateAppName: "<your-deployment-name>" # Replace <your-deployment-name> with your application name.If you want to create a new stateless application (deployment) in a Kubernetes environment and connect it to ARMS, you can use the following complete YAML file as a reference:
Result
The integration is successful if, after about one minute, the Golang application appears in the ARMS console on the page and reports data.
