文档

通过SkyWalking上报Go应用数据

更新时间:

通过SkyWalking为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后,可观测链路 OpenTelemetry 版即可开始监控应用,您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用SkyWalking Go Agent进行自动埋点并上报应用数据。

说明

ARMS应用监控针对Golang语言提供了商业化版本的自研探针,提供了无侵入的埋点能力,拥有更加丰富的功能和更高的稳定性。详细信息,请参见开始监控Golang应用

前提条件

获取接入点信息

新版控制台

  1. 登录可观测链路 OpenTelemetry 版控制台,在左侧导航栏单击接入中心

  2. 开源框架区域单击SkyWalking卡片。

  3. 在弹出的SkyWalking面板中选择数据需要上报的地域。

    说明

    初次接入的地域将会自动进行资源初始化。

  4. 选择连接方式,然后复制接入点信息。

    若您的服务部署在阿里云上,且所属地域与选择的接入地域一致,推荐使用阿里云内网方式,否则选择公网方式。

    image.png

旧版控制台

  1. 登录可观测链路 OpenTelemetry 版控制台

  2. 在左侧导航栏单击集群配置,然后在右侧页面单击接入点信息页签。

  3. 在页面顶部选择需要接入的地域,然后在集群信息区域打开显示Token开关。

  4. 客户端采集工具区域单击SkyWalking

    相关信息列中,获取接入点信息。

    SkyWalking接入点信息

    说明

    如果应用部署于阿里云生产环境,则选择阿里云VPC网络接入点,否则选择公网接入点。

Agent选择

Go2Sky是SkyWalking官方旧版的SkyWalking Go探针,使用人数较多,但侵入较严重,因此官方推出了新版的skywalking-go探针,新版探针具有无侵入的特性。本文同时提供skywalking-go和Go2Sky两种探针接入流程,方便您将数据上报至可观测链路 OpenTelemetry 版控制台。

Go2Sky

  • 旧版SkyWalking Agent,在skywalking-go Agent正式发布后停止支持。

    根据官网页面显示,Go2Sky已被移到Retired,即不再维护。

  • 代码侵入较严重,每一个插件都要在项目中添加Hook。

  • 使用人数较多。

  • 支持的埋点库:

    展开查看支持的埋点库

    库名称

    监控安装方式

    sql

    go get -u github.com/SkyAPM/go2sky-plugins/sql

    dubbo-go

    go get -u github.com/SkyAPM/go2sky-plugins/dubbo-go

    gear

    go get -u github.com/SkyAPM/go2sky-plugins/gear

    gin

    go get -u github.com/SkyAPM/go2sky-plugins/gin/v2
    go get -u github.com/SkyAPM/go2sky-plugins/gin/v3

    go-restful

    go get -u github.com/SkyAPM/go2sky-plugins/go-restful

    gorm

    go get -u github.com/SkyAPM/go2sky-plugins/gorm

    http

    go get -u github.com/SkyAPM/go2sky

    go-kratos v2

    go get -u github.com/SkyAPM/go2sky-plugins/kratos

    logrus

    go get -u github.com/SkyAPM/go2sky-plugins/logrus

    go-micro(v3.5.0)

    go get -u github.com/SkyAPM/go2sky-plugins/micro

    mongo

    go get -u github.com/SkyAPM/go2sky-plugins/mongo

    go-resty(v2.2.0)

    go get -u github.com/SkyAPM/go2sky-plugins/resty

    zap(v1.16.0)

    go get -u github.com/SkyAPM/go2sky-plugins/zap

skywalking-go

  • 新版SkyWalking Agent,官方提供稳定支持。

  • 代码几乎无侵入。

  • 用法简单,只需要编译GoLang项目时通过-toolexec参数指定skywalking-go Agent。

  • 使用人数相对Go2Sky较少。

  • 支持的埋点库:

    展开查看支持的埋点库

    库名称

    监控安装方式

    sql

    无需安装。

    dubbo-go

    gear

    gin

    go-restful

    gorm

    http

    go-kratos v2

    logrus

    go-micro(v3.5.0)

    mongo

    go-resty(v2.2.0)

    zap(v1.16.0)

推荐Agent

建议您使用新版skywalking-go探针,优势如下:

  • 使用简便:skywalking-go使用更简单,您只需要通过简短的步骤即可完成接入和自动埋点。Skywalking-go是无侵入式探针,而Go2Sky在使用插件时需要手动添加Hook钩子。

  • 社区支持:官方将取消对Go2Sky的继续支持,也不再接受关于Go2Sky的PR。

  • 插件生态:官方将会持续将Go2Sky的插件移植到skywalking-go。目前,skywalking-go相比Go2Sky多了对gRPC框架的埋点。

示例Demo

示例Demo仓库地址:SkyWalking Demo

通过skywalking-go探针上报

  1. 下载skywalking-go Agent。

  2. 构建Agent。

    cd skywalking-go && make build
  3. 在skywalking-go/bin路径下生成可执行文件

    不同的操作系统对应的可执行文件不同。例如,mac系统需选择skywalking-go-agent--darwin-amd64。

    image.png

  4. 打开Go项目,在main package中导入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}
    

    设置参数有以下两种方式,例如,如果要配置service_name,配置方法如下:

    方式一(推荐):直接在config.yaml中添加参数

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

    方式二:配置系统环境变量

    export SW_AGENT_NAME=<your_service_name>

    接入可观测链路 OpenTelemetry 版控制台需要设置以下参数:

    • service_name: ${SW_AGENT_NAME:Your_ApplicationName}:服务名称。

    • backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:127.0.0.1:11800}:接入点的Endpoint。

    • authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:}:接入点鉴权Token。

    skywalking-go Agent默认对所有的插件自动埋点,若需要移除特定插件,可以设置excluded参数,例如:

    # 如果想要关闭sql plugin
    plugin:
      excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
    
    # 如果想同时关闭多个plugin,使用,分隔
    plugin:
      excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}
  6. 重新构建项目。

    # 需要使用-toolexec
    sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a
    • path/to/skywalking-go-agent:上文步骤1可执行文件的绝对路径。

    • path/to/config.yaml:skywalking-go Agent的参数配置文件的绝对路径。

  7. 启动项目。此时SkyWalking数据将会上报至可观测链路 OpenTelemetry 版控制台。

参考信息

skywalking-go探针的部分属性列表,NULL表示默认值未设置:

环境变量

描述

默认值

SW_AGENT_NAME

服务名称。

NULL

SW_AGENT_INSTANCE_NAME

服务实例名称。

自动生成

SW_AGENT_SAMPLE

采样率,取值在0和1之间。

1

SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE

监控数据通过gRPC上报的服务端Endpoint。

127.0.0.1:11800

SW_AGENT_REPORTER_GRPC_AUTHENTICATION

监控数据通过gRPC上报的服务端的鉴权Token。

NULL

SW_AGENT_PLUGIN_EXCLUDES

指定移除的插件。

NULL

通过Go2Sky探针上报

  1. Go2Sky同时支持配置参数硬编码到项目或通过环境变量自动配置两种方法。

    配置参数硬编码

    ### 使用reporter.WithParameter()导入参数
    report, err := reporter.NewGRPCReporter(
        <your-backend-server-address>,
        reporter.WithAuthentication(<your-auth-token>))

    环境变量自动配置

    ### 目前go2sky支持从环境变量获取以下参数
    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
    
    ### 配置环境变量,以macOS为例
    # 方法1:写入环境变量配置文件(持久化)
    vim ~/.bash_profile
    export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
    source ~/.bash_profile
    # 方法2:打开终端,命令行配置(临时生效,打开新的终端失效)
    export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
  2. 配置ServiceName,用于识别具体的应用。

    ServiceName := <your-service-name>
    tracer, err := go2sky.NewTracer(ServiceName, go2sky.WithReporter(report))
  3. 添加Go2Sky-Plugin Hook。

    Go2Sky开发了众多库的插件,但是需要在项目源代码中添加埋点。如何添加埋点请参见Go2Sky-Plugins的Github仓库。在每个插件的plugin文件夹下,README.md文件给了简单的使用示例。

    以gin框架为例:

    1. 进入/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. 重新启动应用。

参考信息

Go2Sky的Agent属性配置表,NULL表示默认值未设置:

环境变量

描述

默认值

SW_AGENT_NAME

Go服务的名称。

NULL

SW_AGENT_LAYER

Instance belong layer name which define in the backend

实例所属的layer名称。

NULL

SW_AGENT_INSTANCE_NAME

Go服务的实例名称。

随机生成

SW_AGENT_SAMPLE

采样率,1表示全量采集。

1

SW_AGENT_COLLECTOR_BACKEND_SERVICES

Agent数据上报的服务端地址。

NULL

SW_AGENT_AUTHENTICATION

Agent数据上报的服务端的鉴权令牌。

NULL

SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD

Agent心跳上报周期,单位:s。

20

SW_AGENT_COLLECTOR_GET_AGENT_DYNAMIC_CONFIG_INTERVAL

动态获取Agent配置的时间间隔,单位:s。

20

SW_AGENT_COLLECTOR_MAX_SEND_QUEUE_SIZE

发送跨度Span的队列Buffer长度。

30000

SW_AGENT_PROCESS_STATUS_HOOK_ENABLE

启用进程状态Hook功能。

False

SW_AGENT_PROCESS_LABELS

进程标签,多个标签用英文半角逗号(,)分隔。

NULL

常见问题

  • 使用skywalking-go时报错如下:

    image.png

    如果使用inject方式报错,您可以通过import在main package中导入skywalking module。

  • 跨进程调用时,为什么通过Go2Sky上报可观测链路 OpenTelemetry 版控制台无法显示正确的调用链?

    全链路追踪通过TraceId将整个链路串联起来,而TraceId通过HTTP请求携带传递。如果调用链不正确,说明TraceId没有正确传递,需要设置合理的Span埋点。

    通过合理使用下面两个重要的接口,可以将跨进程的调用链正确的串联起来:

    • CreateEntrySpan:入口Span,可以通过该接口从HTTP请求中提取得到链路追踪上下文(包含TraceId)。

    • CreateExitSpan:出口Span,可以通过该接口向HTTP请求注入链路追踪上下文(包含TraceId)。

    // 进程内,使用CreateLocalSpan创建一个跨度(Span)。
    span, ctx, err := tracer.CreateLocalSpan(context.Background())
    subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
    
    // 跨进程,使用入口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
    })

    跨进程的项目,不同进程之间需要传递TraceId才能将调用链串联起来,所以需要用到上面的接口将上下文注入到HTTP请求中随着请求在进程间传递。

相关文档