How to Install and Use Go Agent for Cloud‑Native Application Monitoring on ACK

Introduction

With the popularity of Kubernetes and containerization, Go is widely used in cloud‑native components and many business scenarios. However, compared with Java, Go lacks bytecode‑enhancement based, non‑intrusive monitoring, requiring manual SDK instrumentation which brings heavy workload and high intrusion.

Problems of Manual Instrumentation

Trace requires instrumentation at every call point and proper context propagation.

Metrics need collection at each call, risking metric explosion.

Large workload and high intrusion: each new interface needs additional instrumentation.

Go Agent Solution

Go Agent addresses these issues by injecting monitoring code at compile time.

Implementation Principle

During compilation, Go Agent uses the -toolexec flag to hijack the compiler. It parses each .go file’s abstract syntax tree (AST) with the dst library, finds suitable insertion points, and inserts monitoring code. The modified files are compiled into .a files, and the final binary contains the injected logic.

Supported SDKs

Go Agent supports Go 1.18+ and integrates with common microservice frameworks and protocols such as Gin, Kratos, Kitex, OpenTelemetry, etc. Currently it supports 20 third‑party SDKs.

Product Capabilities

Application overview: request count, error count, average latency, instance count.

Application topology: upstream and downstream relationships.

Service details: call statistics for each interface.

Dependency services: downstream call information.

Call‑chain analysis: full system call chain.

Instance monitoring.

Scenario analysis: database and anomaly analysis.

Application configuration: sampling rate and probe toggles.

Intelligent alerts: configurable rules for services, HTTP status, DB metrics, dependencies, host monitoring.

Compatibility

Go Agent is compatible with existing OTel Go SDK versions v1.6.0‑v1.26.0 and supports trace propagation protocols W3C, Jaeger, EagleEye, Zipkin.

Step‑by‑Step Guide

Prerequisites

Create an ACK cluster (managed, dedicated, or Serverless).

Create a namespace (e.g., default).

Verify OS, architecture, Go version, and framework compatibility.

Ensure the project uses Go modules.

Step 1: Install ARMS Component

Log in to the Container Service console.

Select the target cluster.

Navigate to Operations → Component Management and search for ack-onepilot (version ≥ 3.2.0).

Click Install and configure parameters (default values are recommended).

Step 2: Compile Go Binary with Probe

Download the compilation tool appropriate for your OS/architecture.

Verify the SHA256 checksum and make the tool executable.

Obtain a LicenseKey via OpenAPI (DescribeTraceLicenseKey).

Run the tool with -toolexec to compile your project, adding --dev for dev mode if needed.

If you have additional build flags, append them after --.

labels:
  aliyun.com/app-language: golang
  armsPilotAutoEnable: 'on'
  armsPilotCreateAppName: "<your‑deployment‑name>"

Step 3: Grant ARMS Access Permissions

Authorize the AliyunARMSFullAccess role to the cluster’s RAM role.

If the ARMS Addon Token is missing, create it in the kube-system namespace.

Provide AK/SK in the ack‑onepilot component configuration.

Step 4: Enable Monitoring for Go Application

Add the labels shown above to your Deployment YAML and deploy the application. After about a minute, the Go service should appear in the ARMS console with data reporting.

References

For detailed documentation, see the official Alibaba Cloud ARMS and ACK guides.