Managed Service for OpenTelemetry:Report Go application trace data through SkyWalking

Step 1: Build the agent

1. Clone the repository:

      git clone https://github.com/apache/skywalking-go.git

2. Build the agent binary: The build produces an executable in the skywalking-go/bin/ directory. The filename varies by operating system -- for example, skywalking-go-agent--darwin-amd64 on macOS.

      cd skywalking-go && make build

   

Step 2: Import and configure the agent

package main

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

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

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

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

export SW_AGENT_NAME=<your-service-name>
export SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=<your-endpoint>
export SW_AGENT_REPORTER_GRPC_AUTHENTICATION=<your-auth-token>

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

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

agent:
  # Service name displayed in the console.
  service_name: ${SW_AGENT_NAME:Your_ApplicationName}
  # Environment variable key for instance name. If not set, an instance name is generated automatically.
  instance_env_name: SW_AGENT_INSTANCE_NAME
  # Sampling rate (float between 0 and 1). 1 = sample everything.
  sampler: ${SW_AGENT_SAMPLE:1}
  meter:
    # Metrics collection interval in seconds.
    collect_interval: ${SW_AGENT_METER_COLLECT_INTERVAL:20}

reporter:
  grpc:
    # gRPC endpoint of the backend service.
    backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}
    # Maximum queued segments for reporting.
    max_send_queue: ${SW_AGENT_REPORTER_GRPC_MAX_SEND_QUEUE:5000}
    # Interval in seconds for checking the backend service.
    check_interval: ${SW_AGENT_REPORTER_GRPC_CHECK_INTERVAL:20}
    # Authentication string for backend communication.
    authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}
    # Interval in seconds for fetching dynamic configuration.
    cds_fetch_interval: ${SW_AGENT_REPORTER_GRPC_CDS_FETCH_INTERVAL:20}
    tls:
      # Enable TLS for backend communication.
      enable: ${SW_AGENT_REPORTER_GRPC_TLS_ENABLE:false}
      # Path to the CA certificate file.
      ca_path: ${SW_AGENT_REPORTER_GRPC_TLS_CA_PATH:}
      # Path to the client key file (for mTLS).
      client_key_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_KEY_PATH:}
      # Path to the client certificate file (for mTLS).
      client_cert_chain_path: ${SW_AGENT_REPORTER_GRPC_TLS_CLIENT_CERT_CHAIN_PATH:}
      # Skip server certificate verification.
      insecure_skip_verify: ${SW_AGENT_REPORTER_GRPC_TLS_INSECURE_SKIP_VERIFY:false}

log:
  # Log framework: "auto", "logrus", or "zap".
  # auto: Detects logrus or zap if present; otherwise uses standard error output.
  type: ${SW_AGENT_LOG_TYPE:auto}
  tracing:
    # Inject trace context into log entries.
    enable: ${SW_AGENT_LOG_TRACING_ENABLE:true}
    # Key name for the trace context in log entries.
    key: ${SW_AGENT_LOG_TRACING_KEY:SW_CTX}
  reporter:
    # Upload logs to the backend.
    enable: ${SW_AGENT_LOG_REPORTER_ENABLE:true}
    # Field names to add as log labels (comma-separated).
    label_keys: ${SW_AGENT_LOG_REPORTER_LABEL_KEYS:}

plugin:
  # Plug-ins to exclude from automatic instrumentation (comma-separated).
  # Takes effect only at compile time.
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:}
  config:
    http:
      # Collect HTTP request parameters on the server side.
      server_collect_parameters: ${SW_AGENT_PLUGIN_CONFIG_HTTP_SERVER_COLLECT_PARAMETERS:false}
    mongo:
      # Collect MongoDB statements.
      collect_statement: ${SW_AGENT_PLUGIN_CONFIG_MONGO_COLLECT_STATEMENT:false}
    sql:
      # Collect SQL parameters.
      collect_parameter: ${SW_AGENT_PLUGIN_CONFIG_SQL_COLLECT_PARAMETER:false}

Step 3: Compile and run your project

Rebuild the project with the -toolexec flag to activate the agent:

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

Replace the paths:

Start the compiled binary. The skywalking-go agent automatically begins reporting trace data to the Managed Service for OpenTelemetry console.

Environment variables reference

Step 1: Configure the reporter

Configure Go2Sky by either hard-coding parameters or setting environment variables.

Option A: Hard-code parameters

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

Option B: Set environment variables

# Permanent: add to your shell profile
echo 'export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-endpoint>' >> ~/.bash_profile
source ~/.bash_profile

# Temporary: set in the current terminal session
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-endpoint>

The Go2Sky agent reads the following environment variables:

• SW_AGENT_AUTHENTICATION

• SW_AGENT_LAYER

• SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD

• SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL

• SW_AGENT_COLLECTOR_BACKEND_SERVICES

• SW_AGENT_COLLECTOR_MAX_SEND_QUEUE_SIZE

• SW_AGENT_PROCESS_STATUS_HOOK_ENABLE

• SW_AGENT_PROCESS_LABELS

Step 2: Create a tracer

Set the service name and create a tracer instance:

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

Step 3: Add plug-in hooks

Go2Sky requires a hook in your source code for each plug-in. Refer to the go2sky-plugins repository on GitHub, where each plug-in folder contains a README with integration instructions.

The following example adds the gin middleware hook:

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()

	// Add the go2sky middleware for tracing
	r.Use(v3.Middleware(r, tracer))

	// Add your route handlers here
}

Step 4: Restart the application

Restart your application. Go2Sky begins reporting trace data to the Managed Service for OpenTelemetry console.

Environment variables reference

The inject method fails with skywalking-go

If the -inject command fails, use the code dependency method instead: add import _ "github.com/apache/skywalking-go" to your main package.

Cross-process traces are not connected when using Go2Sky

Managed Service for OpenTelemetry connects traces across processes using trace IDs carried in HTTP headers. If traces for a cross-process call appear disconnected, the trace context is not being propagated correctly between services.

To propagate context, create the correct span types at process boundaries:

• CreateEntrySpan -- extracts the trace context (including the trace ID) from an incoming HTTP request.

• CreateExitSpan -- injects the trace context into an outgoing HTTP request.

// Create a local span within a single process
span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

// At a process boundary: extract context from the incoming request
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
    return r.Header.Get(key), nil
})

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

Both the upstream and downstream services must use CreateEntrySpan and CreateExitSpan at their boundaries for the trace to connect end-to-end.