Managed Service for OpenTelemetry:Use SkyWalking to report the trace data of Go applications

Sample code

For more information about the sample code repository, see skywalking-demo at GitHub.

Use the skywalking-go agent to report trace data

1. Download the skywalking-go agent.

2. Build the skywalking-go agent.

   cd skywalking-go && make build

3. Generate an executable file in the skywalking-go/bin directory.

   The executable file varies based on your operating system. For example, use skywalking-go-agent--darwin-amd64 for the macOS operating system.

   

4. Open the Go project and import the SkyWalking module into the main package.

   Method 1

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

   Method 2

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

5. Configure the config.yaml file.

   You can configure the config.yaml file by referring to the skywalking-go/tools/go-agent/config/config.default.yaml file in the sample code.

   Expand to view the sample content of the config.default.yaml file

   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}
   

   Two methods are provided for you to configure parameters. For example, to configure the service_name parameter, use one of the following methods:

   Method 1 (recommended): Add the service_name parameter to the config.yaml file

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

   Method 2: Configure a system environment variable

   export SW_AGENT_NAME=<your_service_name>

   To connect the skywalking-go agent to the Managed Service for OpenTelemetry console, you must configure the following parameters:

   • service_name: ${SW_AGENT_NAME:Your_ApplicationName}: the name of the Go application.

   • backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}: the endpoint of the server.

   • authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}: the authentication token for accessing the server.

   By default, the skywalking-go agent automatically instruments all plug-ins. To disable automatic instrumentation for specific plug-ins, you can specify the excluded parameter. Examples:

   # Disable automatic instrumentation for the SQL plug-in.
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
   
   # Disable automatic instrumentation for multiple plug-ins. Separate the plug-ins with commas (,).
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

6. Rebuild the project.

   # Specify the -tolexec parameter.
   sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

   • path/to/skywalking-go-agent: the absolute path to the executable file that is generated in Step 3 in the "Use the skywalking-go agent to report trace data" section.

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

7. Start the project. Then, SkyWalking reports data to the Managed Service for OpenTelemetry console.

Appendix

The following table describes some environment variables of the skywalking-go agent. A value of NULL indicates that no default value is specified.

Use the Go2Sky agent to report trace data

1. The Go2Sky agent allows you to hard-code parameters into your project or use environment variables to configure parameters.

   Hard-code parameters into the project

   ### Use the reporter.WithParameter() method to import parameters.
   report, err := reporter.NewGRPCReporter(
       <your-backend-server-address>,
       reporter.WithAuthentication(<your-auth-token>))

   Use environment variables to configure parameters

   ### The Go2Sky agent can obtain the values of the following parameters from 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
   
   ### Configure environment variables. In this example, macOS is used.
   # Method 1: Write an environment variable configuration file. The environment variables configured by using this method are permanently valid.
   vim ~/.bash_profile
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
   source ~/.bash_profile
   # Method 2: Open a terminal and configure environment variables in the command line. The environment variables configured by using this method are temporarily valid and become invalid when you open another terminal.
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>

2. Configure the ServiceName parameter to specify an application.

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

3. Add hooks for Go2Sky plug-ins.

   The Go2Sky agent provides plug-ins for many libraries. You need to add hooks for these plug-ins to the source code of your project. For more information about how to add hooks, see the go2sky-plugins repository at GitHub. A README.md file is provided in the plugin folder of each plug-in to describe how to use the plug-in.

   In this example, the gin framework is used.

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

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

      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
      }

4. Restart the application.

Appendix

The following table describes the environment variables of the Go2Sky agent. A value of NULL indicates that no default value is specified.

FAQ

• What do I do if the error message shown in the following figure appears when I use the skywalking-go agent?

  

  If the inject method fails, you can use the import method to import the SkyWalking module into the main package.

• Why does the Managed Service for OpenTelemetry console fail to display the correct trace data for a cross-process service call when I use the Go2Sky agent to report trace data?

  Managed Service for OpenTelemetry connects traces based on trace IDs. Trace IDs are carried and transmitted by HTTP requests. If invalid trace data is displayed, the trace IDs are not correctly transmitted. In this case, you must configure appropriate spans for instrumentation.

  You can call the following two important operations to connect traces for a cross-process service call:

  • CreateEntrySpan: creates an entry span. You can call this operation to extract the trace analysis context, including the trace ID, from an HTTP request.

  • CreateExitSpan: creates an exit span. You can call this operation to inject the trace analysis context, including the trace ID, into an HTTP request.

  // Call the CreateLocalSpan operation to create a span in a process. 
  span, ctx, err := tracer.CreateLocalSpan(context.Background())
  subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
  
  // For a cross-process service call, call the CreateEntrySpan operation to extract the trace analysis context from the HTTP request, and call the CreateExitSpan operation to inject the trace analysis 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
  })

  For a cross-process service call, trace IDs must be transmitted across processes to connect the traces. Therefore, you must call the preceding operations to inject the trace analysis context into the HTTP requests that are transmitted across processes.

References

• Official website of Apache SkyWalking

• skywalking-go repository at GitHub

• Official documentation of skywalking-go

• Go2Sky repository at GitHub

• go2sky-plugins repository at GitHub