示例Demo

示例Demo倉庫地址：SkyWalking Demo

通過skywalking-go探針上報(bào)

1. 下載skywalking-go Agent。

2. 構(gòu)建Agent。

   cd skywalking-go && make build

3. 在skywalking-go/bin路徑下生成可執(zhí)行文件。

   不同的操作系統(tǒng)對應(yīng)的可執(zhí)行文件不同。例如，mac系統(tǒng)需選擇skywalking-go-agent--darwin-amd64。

   

4. 打開Go項(xiàng)目，在main package中導(dǎo)入skywalking module。

   方式一

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

   方式二

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

5. 配置config.yaml文件。

   您可以參考示例Demo的skywalking-go/tools/go-agent/config/config.default.yaml文件修改。

   展開查看config.default.yaml文件示例

   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}
   

   設(shè)置參數(shù)有以下兩種方式，例如，如果要配置service_name，配置方法如下：

   方式一（推薦）：直接在config.yaml中添加參數(shù)

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

   方式二：配置系統(tǒng)環(huán)境變量

   export SW_AGENT_NAME=<your_service_name>

   接入可觀測鏈路 OpenTelemetry 版控制臺需要設(shè)置以下參數(shù)：

   • service_name: ${SW_AGENT_NAME:Your_ApplicationName}：服務(wù)名稱。

   • backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}：接入點(diǎn)的Endpoint。

   • authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}：接入點(diǎn)鑒權(quán)Token。

   skywalking-go Agent默認(rèn)對所有的插件自動埋點(diǎn)，若需要移除特定插件，可以設(shè)置excluded參數(shù)，例如：

   # 如果想要關(guān)閉sql plugin
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
   
   # 如果想同時(shí)關(guān)閉多個(gè)plugin，使用,分隔
   plugin:
     excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}

6. 重新構(gòu)建項(xiàng)目。

   # 需要使用-toolexec
   sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a

   • path/to/skywalking-go-agent：上文步驟1可執(zhí)行文件的絕對路徑。

   • path/to/config.yaml：skywalking-go Agent的參數(shù)配置文件的絕對路徑。

7. 啟動項(xiàng)目。此時(shí)SkyWalking數(shù)據(jù)將會上報(bào)至可觀測鏈路 OpenTelemetry 版控制臺。

參考信息

skywalking-go探針的部分屬性列表，NULL表示默認(rèn)值未設(shè)置：

通過Go2Sky探針上報(bào)

1. Go2Sky同時(shí)支持配置參數(shù)硬編碼到項(xiàng)目或通過環(huán)境變量自動配置兩種方法。

   配置參數(shù)硬編碼

   ### 使用reporter.WithParameter()導(dǎo)入?yún)?shù)
   report, err := reporter.NewGRPCReporter(
       <your-backend-server-address>,
       reporter.WithAuthentication(<your-auth-token>))

   環(huán)境變量自動配置

   ### 目前go2sky支持從環(huán)境變量獲取以下參數(shù)
   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
   
   ### 配置環(huán)境變量，以macOS為例
   # 方法1:寫入環(huán)境變量配置文件（持久化）
   vim ~/.bash_profile
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
   source ~/.bash_profile
   # 方法2:打開終端，命令行配置（臨時(shí)生效，打開新的終端失效）
   export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>

2. 配置ServiceName，用于識別具體的應(yīng)用。

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

3. 添加Go2Sky-Plugin Hook。

   Go2Sky開發(fā)了眾多庫的插件，但是需要在項(xiàng)目源代碼中添加埋點(diǎn)。如何添加埋點(diǎn)請參見Go2Sky-Plugins的Github倉庫。在每個(gè)插件的plugin文件夾下，README.md文件給了簡單的使用示例。

   以gin框架為例：

   1. 進(jìn)入/gin文件夾，查看/gin/v3/README.md文件。

   2. 添加Middleware的Hook：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. 重新啟動應(yīng)用。

參考信息

Go2Sky的Agent屬性配置表，NULL表示默認(rèn)值未設(shè)置：

常見問題

• 使用skywalking-go時(shí)報(bào)錯(cuò)如下：

  

  如果使用inject方式報(bào)錯(cuò)，您可以通過import在main package中導(dǎo)入skywalking module。

• 跨進(jìn)程調(diào)用時(shí)，為什么通過Go2Sky上報(bào)可觀測鏈路 OpenTelemetry 版控制臺無法顯示正確的調(diào)用鏈？

  全鏈路追蹤通過TraceId將整個(gè)鏈路串聯(lián)起來，而TraceId通過HTTP請求攜帶傳遞。如果調(diào)用鏈不正確，說明TraceId沒有正確傳遞，需要設(shè)置合理的Span埋點(diǎn)。

  通過合理使用下面兩個(gè)重要的接口，可以將跨進(jìn)程的調(diào)用鏈正確的串聯(lián)起來：

  • CreateEntrySpan：入口Span，可以通過該接口從HTTP請求中提取得到鏈路追蹤上下文（包含TraceId）。

  • CreateExitSpan：出口Span，可以通過該接口向HTTP請求注入鏈路追蹤上下文（包含TraceId）。

  // 進(jìn)程內(nèi)，使用CreateLocalSpan創(chuàng)建一個(gè)跨度（Span）。
  span, ctx, err := tracer.CreateLocalSpan(context.Background())
  subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
  
  // 跨進(jìn)程，使用入口Span從CreateEntrySpan從Http請求中提取上下文，使用出口Span向CreateExitSpan向Http請求中注入上下文。
  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
  })

  跨進(jìn)程的項(xiàng)目，不同進(jìn)程之間需要傳遞TraceId才能將調(diào)用鏈串聯(lián)起來，所以需要用到上面的接口將上下文注入到HTTP請求中隨著請求在進(jìn)程間傳遞。

相關(guān)文檔

• SkyWalking官網(wǎng)

• skywalking-go的Github倉庫

• skywalking-go的官方文檔

• Go2Sky的Github倉庫

• Go2Sky-Plugins的Github倉庫