Application Real-Time Monitoring Service:Report Go trace data through SkyWalking

Step 1: Get the SkyWalking endpoint

1. Log on to the Managed Service for OpenTelemetry console.

2. In the left-side navigation pane, click Cluster Configurations. On the page that appears, click the Access point information tab.

3. In the top navigation bar, select a region. In the Cluster Information section, turn on Show Token.

4. Set the Client parameter to SkyWalking.

5. Copy the endpoint from the Related Information column.

Step 2: Build the agent binary

Clone and build the skywalking-go agent:

git clone https://github.com/apache/skywalking-go.git
cd skywalking-go && make build

The build produces an executable in the skywalking-go/bin/ directory. The file name varies by OS -- for example, skywalking-go-agent--darwin-amd64 on macOS.

Step 3: Add the SkyWalking module to your project

Choose one of the following methods:

package main

import (
	_ "github.com/apache/skywalking-go"
)

skywalking-go/bin/skywalking-go-agent--darwin-amd64 -inject path/to/your-project

Step 4: Configure the agent

Create a config.yaml file with at least the following three parameters:

agent:
  service_name: ${SW_AGENT_NAME:<your-service-name>}

reporter:
  grpc:
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:<your-skywalking-endpoint>}
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:<your-auth-token>}

Replace the placeholders with your values:

Set these values in config.yaml directly (recommended) or through environment variables:

export SW_AGENT_NAME=my-go-service
export SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=xxx.api.aliyuncs.com:11800
export SW_AGENT_REPORTER_GRPC_AUTHENTICATION=abcdef123456

plugin:
  # Disable a single plug-in
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}

  # Disable multiple plug-ins (comma-separated)
  # excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

agent:
  # Service name is showed in UI.
  service_name: ${SW_AGENT_NAME:Your_ApplicationName}
  # To obtain the environment variable key for the instance name, if it cannot be obtained, an instance name will be automatically generated.
  instance_env_name: SW_AGENT_INSTANCE_NAME
  # Sampling rate of tracing data, which is a floating-point value that must be between 0 and 1.
  sampler: ${SW_AGENT_SAMPLE:1}
  meter:
    # The interval of collecting metrics, in seconds.
    collect_interval: ${SW_AGENT_METER_COLLECT_INTERVAL:20}

reporter:
  grpc:
    # The gRPC server address of the backend service.
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}
    # The maximum count of segment for reporting tracing data.
    max_send_queue: ${SW_AGENT_REPORTER_GRPC_MAX_SEND_QUEUE:5000}
    # The interval(s) of checking service and backend service
    check_interval: ${SW_AGENT_REPORTER_GRPC_CHECK_INTERVAL:20}
    # The authentication string for communicate with backend.
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}
    # The interval(s) of fetching dynamic configuration from backend.
    cds_fetch_interval: ${SW_AGENT_REPORTER_GRPC_CDS_FETCH_INTERVAL:20}
    tls:
      # Whether to enable TLS with backend.
      enable: ${SW_AGENT_REPORTER_GRPC_TLS_ENABLE:false}
      # The file path of ca.crt. The config only works when opening the TLS switch.
      ca_path: ${SW_AGENT_REPORTER_GRPC_TLS_CA_PATH:}
      # The file path of client.pem. The config only works when mTLS.
      client_key_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_KEY_PATH:}
      # The file path of client.crt. The config only works when mTLS.
      client_cert_chain_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_CERT_CHAIN_PATH:}
      # Controls whether a client verifies the server's certificate chain and host name.
      insecure_skip_verify: ${SW_AGENT_REPORTER_GRPC_TLS_INSECURE_SKIP_VERIFY:false}

log:
  # The type determines which logging type is currently used by the system.
  # The Go agent wourld use this log type to generate custom logs. It supports: "auto", "logrus", or "zap".
  # auto: Automatically identifies the source of the log.
  #       If logrus is present in the project, it wourld automatically use logrus.
  #       If zap has been initialized in the project, it would use the zap framework.
  #       By default, it would use std errors to output log content.
  # logrus: Specifies that the Agent should use the logrus framework.
  # zap: Specifies that the Agent should use the zap framework.
  # The system must have already been initialized through methods such as "zap.New", "zap.NewProduction", etc.
  type: ${SW_AGENT_LOG_TYPE:auto}
  tracing:
    # Whether to automatically integrate Tracing information into the logs.
    enable: ${SW_AGENT_LOG_TRACING_ENABLE:true}
    # If tracing information is enabled, the tracing information would be stored in the current Key in each log.
    key: ${SW_AGENT_LOG_TRACING_KEY:SW_CTX}
  reporter:
    # Whether to upload logs to the backend.
    enable: ${SW_AGENT_LOG_REPORTER_ENABLE:true}
    # The fields name list that needs to added to the label of the log.(multiple split by ",")
    label_keys: ${SW_AGENT_LOG_REPORTER_LABEL_KEYS:}

plugin:
  # List the names of excluded plugins, multiple plugin names should be splitted by ","
  # NOTE: This parameter only takes effect during the compilation phase.
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:}
  config:
    http:
      # Collect the parameters of the HTTP request on the server side
      server_collect_parameters: ${SW_AGENT_PLUGIN_CONFIG_HTTP_SERVER_COLLECT_PARAMETERS:false}
    mongo:
      # Collect the statement of the MongoDB request
      collect_statement: ${SW_AGENT_PLUGIN_CONFIG_MONGO_COLLECT_STATEMENT:false}
    sql:
      # Collect the parameter of the SQL request
      collect_parameter: ${SW_AGENT_PLUGIN_CONFIG_SQL_COLLECT_PARAMETER:false}

Step 5: Rebuild your project

Compile with the -toolexec flag pointing to the agent binary and your config file:

sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

• path/to/skywalking-go-agent -- absolute path to the executable built in Step 2

• path/to/config.yaml -- absolute path to the config file created in Step 4

Step 6: Start your application and verify

Run the compiled binary. The agent instruments all supported plug-ins automatically and begins reporting traces over gRPC.

After you start the project, SkyWalking reports data to the Managed Service for OpenTelemetry console.

Environment variables reference

Supported plug-ins

The skywalking-go agent automatically instruments the following libraries at compile time. No per-library installation is required.

Step 1: Set up the reporter

Configure the gRPC reporter by hard-coding parameters or setting environment variables.

report, err := reporter.NewGRPCReporter(
    "<your-backend-server-address>",
    reporter.WithAuthentication("<your-auth-token>"))

# Permanent -- add to your shell profile
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
export SW_AGENT_AUTHENTICATION=<your-auth-token>

# Then start your application (the agent reads these variables automatically)

Step 2: Create a tracer

ServiceName := "<your-service-name>"
tracer, err := go2sky.NewTracer(ServiceName, go2sky.WithReporter(report))

Step 3: Add plug-in hooks

Go2Sky requires a hook for each instrumented library. See the go2sky-plugins repository on GitHub -- each plug-in folder contains a README with integration instructions.

Example -- gin framework:

package main

import (
	"log"

	"github.com/SkyAPM/go2sky"
	v3 "github.com/SkyAPM/go2sky-plugins/gin/v3"
	"github.com/SkyAPM/go2sky/reporter"
	"github.com/gin-gonic/gin"
)

func main() {
	// Use gRPC reporter for production
	re, err := reporter.NewLogReporter()
	if err != nil {
		log.Fatalf("new reporter error %v \n", err)
	}
	defer re.Close()

	tracer, err := go2sky.NewTracer("gin-server", go2sky.WithReporter(re))
	if err != nil {
		log.Fatalf("create tracer error %v \n", err)
	}

	gin.SetMode(gin.ReleaseMode)
	r := gin.New()

	// Use go2sky middleware with tracing
	r.Use(v3.Middleware(r, tracer))

	// Add your routes here
}

Step 4: Restart the application

After adding hooks, restart your application. Traces begin flowing to the Managed Service for OpenTelemetry console.

Supported plug-in libraries

Each plug-in requires a separate go get installation:

Environment variables reference

What do I do if the skywalking-go inject command fails?

If the -inject method fails, add the SkyWalking import directly in your main package instead:

import _ "github.com/apache/skywalking-go"

Then rebuild with -toolexec as described in Step 5.

Why does the console show broken traces for cross-process calls with Go2Sky?

Managed Service for OpenTelemetry correlates spans by trace IDs carried in HTTP headers. If traces appear disconnected across services, trace context is not propagating correctly.

To fix this, create entry and exit spans that propagate trace context across HTTP boundaries:

// CreateEntrySpan -- extract trace context from an incoming HTTP request
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
    return r.Header.Get(key), nil
})

// CreateExitSpan -- inject trace context into an outgoing HTTP request
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
    req.Header.Set(key, value)
    return nil
})

For in-process spans (no network boundary), use CreateLocalSpan:

span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

Every HTTP call that crosses a process boundary must carry trace context. Without CreateEntrySpan and CreateExitSpan at each boundary, the downstream service starts a new, disconnected trace.