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

Step 1: Download and build the agent

Download the skywalking-go agent, and then run the following command to build it:

cd skywalking-go && make build

An executable file is generated in the skywalking-go/bin directory. The executable file differs by operating system:

• macOS: skywalking-go-agent--darwin-amd64

• Linux: skywalking-go-agent--linux-amd64

• Windows: skywalking-go-agent--windows-amd64

Step 2: Enable instrumentation in your Go project

Open your Go project and enable instrumentation in one of the following ways. If the inject command returns an error, import the skywalking module in the main package instead.

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

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

Step 3: Configure the connection parameters

Copy skywalking-go/tools/go-agent/config/config.default.yaml from the skywalking-go repository that you downloaded in Step 1, save it as your own config.yaml file, and then set the following parameters to connect the agent to Managed Service for OpenTelemetry:

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>}

• service_name: the service name. Replace <your-service-name> with the name of your application.

• backend_service: the endpoint. Replace <your-endpoint> with the endpoint that you copied in Obtain an endpoint.

• authentication: the authentication token of the endpoint. Replace <your-auth-token> with your own token.

For the remaining agent parameters, the ways to set them, and the default configuration file, see Advanced configuration for the skywalking-go agent.

Step 4: Rebuild and start your project

Rebuild your project and pass the agent to the Go compiler with the -toolexec flag:

# You must use -toolexec
sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

• path/to/skywalking-go-agent: the absolute path of the executable file that you built in Step 1.

• path/to/config.yaml: the absolute path of the parameter settings file of the skywalking-go agent.

Start your project. SkyWalking data is then reported to the Managed Service for OpenTelemetry console.

Step 1: Configure the connection parameters

Go2Sky supports two configuration methods: hard-code the parameters in your project, or configure them automatically by using environment variables.

// Import parameters by using reporter.WithParameter()
report, err := reporter.NewGRPCReporter(
    <your-backend-server-address>,
    reporter.WithAuthentication(<your-auth-token>))

# Method 1: write to the environment variable configuration file (persistent)
vim ~/.bash_profile
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
source ~/.bash_profile
# Method 2: open a terminal and configure on the command line (temporary; no longer in effect in a new terminal)
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>

Step 2: Configure the service name

Configure ServiceName to identify the application:

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

Step 3: Add a Go2Sky plug-in hook

Go2Sky provides plug-ins for many libraries, but you must add the instrumentation in the source code of your project. For information about how to add instrumentation, see the Go2Sky-Plugins repository on GitHub. The README.md file in each plug-in folder provides a basic usage example.

To add the hook for the gin framework, perform the following operations:

1. Go to the /gin folder and open the /gin/v3/README.md file.

2. Add the middleware hook: v3.Middleware(r, tracer).

The following example shows how the hook is mounted. Replace the log reporter with the gRPC reporter and the service name that you configured in Step 1 and Step 2 before you report data to Managed Service for OpenTelemetry.

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))
    // do something
}

Step 4: Restart the application

Restart the application.

Ways to set a parameter

You can set a skywalking-go agent parameter in two ways. The following example configures service_name:

agent:
  service_name: ${SW_AGENT_NAME:<your_service_name>}

export SW_AGENT_NAME=<your_service_name>

Exclude plug-ins

By default, the skywalking-go agent instruments all plug-ins automatically. To exclude a specific plug-in, set the excluded parameter:

# To exclude the sql plugin
plugin:
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
# To exclude multiple plugins at the same time, separate them with commas
plugin:
  excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

Default configuration file

The following example shows the complete config.default.yaml file of the skywalking-go agent:

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}

skywalking-go environment variables

The following table lists the environment variables that the skywalking-go agent supports. NULL indicates that no default value is set.

Go2Sky environment variables

The following table lists the environment variables that the Go2Sky agent supports. NULL indicates that no default value is set.

The inject command of skywalking-go returns a version error

The following error occurs when you use skywalking-go:

U-VF4VY9W5-1944:skywalking-go-test whlongxi$ skywalking-go/bin/skywalking-go-agent--darwin-amd64 -inject ../skywalking-go-test -all
2023/08/09 16:55:59 version is empty, please use the release version of skywalking-go

If an error occurs when you use the inject method, import the skywalking module in the main package.

Cross-process traces are not displayed correctly when you report data through Go2Sky

End-to-end tracing connects a trace by using the trace ID, which is carried in HTTP requests. An incorrect trace means that the trace ID is not propagated correctly, so you must set the spans appropriately. Use the following two interfaces to connect cross-process calls into a single trace:

• CreateEntrySpan: the entry span. Use this interface to extract the tracing context, which includes the trace ID, from an HTTP request.

• CreateExitSpan: the exit span. Use this interface to inject the tracing context, which includes the trace ID, into an HTTP request.

// Within a process, use CreateLocalSpan to create a span.
span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
// Across processes, use the entry span CreateEntrySpan to extract the context from the HTTP request, and use the exit span CreateExitSpan to inject the context into the HTTP request.
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
    return r.Header.Get(key), nil
})
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
        req.Header.Set(key, value)
        return nil
})

In a cross-process project, the trace ID must be propagated between processes to connect the trace. Use the preceding interfaces to inject the context into HTTP requests so that it is passed between processes with the requests.