Go Agent

Install Go Agent

Using UniAgent Linux Version

When there are applications in multiple languages on the server, it is recommended to use UniAgent for installation. For installation steps, see UniAgent Linux Deployment Guide.

Note: In the ps process list, the original Go application process will be replaced by agentinject, and the parent process ID of the Go application will become 1. If the Go application is managed by a start/stop script or service, please verify its effectiveness in a test environment and make appropriate modifications.

Method 1: Modify Application Startup Script

Applicable only to agent versions greater than 2.5.7.0

After installing UniAgent, add /opt/tingyun-oneagent/agent/go_current/bin/agentinject to the application startup script and restart the application.

For example, the original Go application startup script:

/opt/go-app/go-demo

After modification:

...
/opt/tingyun-oneagent/agent/go_current/bin/agentinject /opt/go-app/go-demo

To uninstall the agent: restore the application startup script to its original state and restart the application.

Instrumentation Principle:

The Go application is started using bin/agentinject, which uses ptrace technology to replace relevant functions in the Go application and collect performance data.

Method 2: Modify UniAgent Configuration

Applicable only to agent versions greater than 2.5.8.0

1. Manually enable Go application instrumentation

   Set go_enabled=true in /opt/tingyun-oneagent/conf/interceptor.conf.

2. Restart the UniAgent service

   sudo systemctl restart tingyun-oneagent

   Go Agent trace data needs to be forwarded to the Collector via an intermediate process. After restarting the UniAgent service, if go_enabled=true is configured, the intermediate process will be started to receive trace data.

   If you do not restart the UniAgent service, the Go Agent log 'golang_agent.log' will contain Connect file:///opt/tingyun-oneagent/agent/go_version/run/goagent.sock failed, indicating communication with the intermediate process failed.

3. Manually modify Go application identification mode

   Go application identification uses a whitelist. Modify go.namelist= in /opt/tingyun-oneagent/conf/interceptor.conf, separating multiple names with commas.

   For example, to monitor /app/go-demo1 and /test/go-test2, set go.namelist=go-demo1,go-test2

4. Restart the Go application

   If the Go application is started via a shell script, simply restart the Go application.

   If the Go application is started directly by command and the current shell was opened before the UniAgent service started, open a new shell or use sh -c 'Go application and parameters' to start; if the current shell was opened after the UniAgent service started, you can restart the Go application directly.

   If the Go application is started as a system service (systemctl), modify the service to start as /bin/sh -c 'Go application and parameters'.

   Instrumentation depends on the parent process being a dynamically linked C runtime process. If the Go application is started by a statically linked process, instrumentation will not work.

For Go applications running inside containers, the following requirements must be met:

• C Runtime Dependency:

  The base image must include a complete C runtime library (glibc or musl libc).

  Minimal images without a C runtime, such as scratch or busybox:musl, are not supported.

  You can check if the image includes a C runtime by running docker exec -it <container-name> cat /proc/self/maps and looking for *.so.

• Process Relationship Dependency:

  Instrumentation depends on the parent process being a dynamically linked C runtime process. If the Go application is started by a statically linked process, instrumentation will not work.

  You can check if the parent process is dynamically linked by running cat /proc/[parent-pid]/maps and looking for *.so.

  If the Go application is the entrypoint (pid=1), you can change the entrypoint to sh -c 'Go application and parameters' to start the Go application.

  Example:

  docker run --entrypoint 'sh -c "/app/go-demo"' image

• Permission Dependency:

  Instrumentation requires the parent process to have PTRACE_ME permission.

  If Go Agent loading fails inside the container and golang_bootstrap.log contains Operation not permitted, add the parameter --cap-add=SYS_PTRACE when running the container.

To uninstall the agent: remove the application name from the whitelist in /opt/tingyun-oneagent/conf/interceptor.conf and restart the application.

Instrumentation Principle:

Instrumentation uses the Preload technique (/etc/ld.so.preload) to load the preloaded module (libinterceptor.so) by the parent process. The preloaded module monitors the parent process starting child processes. If the child process name is in the whitelist, it replaces the child process with bin/agentinject and starts the Go application using bin/agentinject, which uses ptrace technology to replace relevant functions in the Go application and collect performance data.

Using UniAgent Kubernetes Version

When using Kubernetes or Openshift cloud platforms, see UniAgent Kubernetes Deployment Guide.

The agent requires up to 50M of memory resources. If the Pod sets resource requests and limits, please increase the CPU and memory resource settings.

Note: The 2.5.7.0 version of the agent only supports Pods that start Go applications directly.

• If the Go application is started directly via a shell script and the image includes a complete C runtime (glibc or musl libc): add the label tingyun-go-enabled: enabled

• If the Go application is started directly via a shell script but uses a minimal image without a C runtime (e.g., busybox:musl): not supported, instrumentation will not work.

• If the Go application is started by a statically linked process: not supported, instrumentation will not work.

• If the image starts the Go application directly (e.g., scratch): add the label tingyun-go-entrypoint: enabled and ensure the command is not empty. If the command is empty, set the command to the Go application path and parameters.

Example 1:

When building the Dockerfile, specify ENTRYPOINT ['/app/go-demo', 'param'], and do not specify a command when deploying the Deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo1
  namespace: default
spec:
  selector:
    matchLabels:
      app: demo1
  template:
    spec:
      containers:
      - name: demo1
        image: test/go-demo:1.0

Set tingyun-go-entrypoint to enabled and add a command with the Dockerfile ENTRYPOINT value:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo1
  namespace: default
spec:
  selector:
    matchLabels:
      app: demo1
  template:
    metadata:
      labels:
        tingyun-go-entrypoint: enabled
    spec:
      containers:
      - name: demo1
        image: test/go-demo:1.0
        command: ['/app/go-demo', 'param']

Example 2:

When building the Dockerfile, specify ENTRYPOINT ['/app/go-demo'], do not specify a command when deploying the Deployment, but specify args.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo1
  namespace: default
spec:
  selector:
    matchLabels:
      app: demo1
  template:
    spec:
      containers:
      - name: demo1
        image: test/go-demo:1.0
        args: ['param1', 'param2']

Set tingyun-go-entrypoint to enabled, remove args, and add a command with the Dockerfile ENTRYPOINT value plus the original args:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo1
  namespace: default
spec:
  selector:
    matchLabels:
      app: demo1
  template:
    metadata:
      labels:
        tingyun-go-entrypoint: enabled
    spec:
      containers:
      - name: demo1
        image: test/go-demo:1.0
        command: ['/app/go-demo', 'param1', 'param2']

By default, containers in Kubernetes have SYS_PTRACE capability, but some customized Kubernetes platforms may restrict this capability. Please handle accordingly.

Instrumentation Principle:

Instrumentation uses the Preload technique (LD_PRELOAD) to load the preloaded module (libinterceptor.so) by the parent process. The preloaded module monitors the parent process starting child processes and replaces the child process with bin/agentinject. bin/agentinject determines whether the child process is a Go application. If not, it starts the child process directly; if it is a Go application, agentinject uses ptrace technology to replace relevant functions in the Go application and collect performance data.

If the Go application has no parent process and tingyun-go-entrypoint is enabled, the agent will modify the container command to agentinject <original-Go-application-start-command>, and agentinject will use ptrace technology to replace relevant functions in the Go application and collect performance data.

Using Standalone Agent

Download the standalone Go Agent, after installation, modify the collector address and license in /installation_path/conf/goagent.conf, and add /installation_path/bin/agentinject to the application startup script, then restart the application.

For example, the original Go application startup script:

/opt/go-app/go-demo

After modification:

...
/opt/tingyun-go-v1.0/bin/agentinject /opt/go-app/go-demo

To uninstall the agent: restore the application startup script to its original state and restart the application.

Instrumentation Principle:

The Go application is started using bin/agentinject, which uses ptrace technology to replace relevant functions in the Go application and collect performance data.

Go SDK Instrumentation

Install Go SDK

The Go SDK is installed in the same way as any third-party module.

• For GOPATH mode:

  $ go get github.com/TingYunGo/goagent

• For GOMOD mode: