OpenTelemetry-go的SDK使用方法详解

目录

• 例子
• 原理
• 方法使用
• newExporter
• newResource
• trace.NewTracerProvider
• otel
• 注意
• 获取当前跨度
• 设置span状态
• 设置span属性
• 记录错误
• 设置活动
• tp.Shutdown

2019年5月,OpenCensus 和 OpenTracing形成了 OpenTelemetry(简称 OTel)

也就是说,我们在使用链路追踪SDK的时候就需要使用OpenTelemetry的新规范.OpenTelemetry帮我们实现了相应语言的SDK,所以我们只需要进行调用即可.
接下来,我们开始对go所对应的SDK进行使用.

本文主要根据官方文档实例进行讲解.

例子

本文简化了官方的例子,每个地方都已注释完毕! 例子使用jaeger作为链路追踪服务器.

首先我们先引入它的包.

# 安装核心模块
go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/trace
# 安装导出器,这里导出器使用的是stdout
go get go.opentelemetry.io/otel/sdk \
         go.opentelemetry.io/otel/exporters/stdout/stdouttrace
# 因为我们需要使用jaeger所以要导入jaeger导出器
go get -u go.opentelemetry.io/otel/exporters/jaeger

当我们导入上面的包之后,就可以运行例子了.

package main
import (
	"context"
	"fmt"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/jaeger"
	"go.opentelemetry.io/otel/sdk/resource"
	"go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.12.0"
)
// 计算斐波那契队列
func Fibonacci(n uint) (uint64, error) {
	if n <= 1 {
		return uint64(n), nil
	}

	var n2, n1 uint64 = 0, 1
	for i := uint(2); i < n; i++ {
		n2, n1 = n1, n1+n2
	}

	return n2 + n1, nil
}
// 这里模拟服务之间的掉用的效果.
func Run(ctx context.Context) {
	_, span := otel.Tracer("nihao").Start(ctx, "two")
	defer span.End()
	fibonacci, err := Fibonacci(20)
	if err != nil {
		return
	}
	fmt.Println(fibonacci)
}
// newExporter returns a console exporter.
// 创建导出器,对于链路追踪服务器的选择就是在这里配置
// 下面是基于jaeger的导出器.
// 这里需要注意,在使用jaeger导出器的时候传输格式是jaeger.thrift over HTTP
// 所以在配置url时请使用14268端口 与/api/traces
func newExporter(url string) (*jaeger.Exporter, error) {
	return jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(url)))
}

// 资源是一种特殊类型的属性，适用于进程生成的所有跨度。这些应该用于表示有关非临时进程的底层元数据
// 例如，进程的主机名或其实例 ID
func newResource() *resource.Resource {
	r, _ := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("fib"),
			semconv.ServiceVersionKey.String("v0.1.0"),
			attribute.String("environment", "demo"),
		),
	)
	return r
}

// 主函数
func main() {
	url := "http://collector.tl.com:31498/api/traces"
	// 创建导出器
	exp, _ := newExporter(url)
	// 创建链路生成器,这里将导出器与资源信息配置进去.
	tp := trace.NewTracerProvider(
		trace.WithBatcher(exp),
		trace.WithResource(newResource()),
	)
	// 结束时关闭链路生成器
	defer func() {
		if err := tp.Shutdown(context.Background()); err != nil {
			fmt.Println(err)
		}
	}()

	// 将创建的生成器设置为全局变量.
	// 这样直接使用otel.Tracer就可以创建链路.
	// 否则 就要使用 tp.Tracer的形式创建链路.
	otel.SetTracerProvider(tp)
	newCtx, span := otel.Tracer("nihao").Start(context.Background(), "one")
	Run(newCtx)
	span.End()
}

原理

运行成功了,那么它的底层原理是怎么实现的,每个组件是怎么组织的?
这里我将根据上面的例子画一张流程图来进行说明.

通过上面的图我们可以知道,跨度之间的传输使用的是Context 来实现的.
使用span.end()就是将当前跨度信息发送给链路追踪服务器.

方法使用

接下来让我们根据上面的例子讲解一下他们每个方法的使用方式与配置吧!

newExporter

它的作用是创建一个导出器
在里面有两种配置

// 配置jaeger服务器
jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(url))
// 参数是一个options ...CollectorEndpointOption所以让我们看一下都有哪些配置
jaeger.WithEndpoint(endpoint string) // 配置服务器地址
jaeger.WithUsername(username string) // 配置用户名
jaeger.WithPassword(password string) // 配置密码
jaeger.WithHTTPClient(client *http.Client) //设置用于发送给jeager服务器所用到的client,有默认.这里可以设置

// 配置jaeger-agent 代理地址
jaeger.WithAgentEndpoint()
// 参数是options ...AgentEndpointOption
jaeger.WithAgentHost(host string) // 设置代理host
jaeger.WithAgentPort(port string) // 设置代理端口
jaeger.WithLogger(logger *log.Logger) // 设置日志系统
jaeger.WithDisableAttemptReconnecting() // 设置禁止重新连接UDP
jaeger.WithAttemptReconnectingInterval(interval time.Duration) // 设置代理解析jaeger服务器之间的时间间隔
jaeger.WithMaxPacketSize(size int) // 设置UDP传输的最大包

无论是使用agent还是Collector,导出器都 使用batchUploader,也就是批量上传策略.

newResource

存在于每个span中,在jaegerUI上显示的是tag下面的Process
它有默认设置,也可以自定义,下面让我们看一下具体使用

// merge 只是合并下面的两组资源.
r, _ := resource.Merge(
        // 设置默认的资源. 进程id等
		resource.Default(),
        // 设置自定义属性
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("fib"),
			semconv.ServiceVersionKey.String("v0.1.0"),
            // 我们可以使用该方法,来进行添加自定义属性
			attribute.String("environment", "demo"),
		),
	)

这里并不强制使用resource.NewWithAttributes,只要返回值是 resource.Resource 即可

trace.NewTracerProvider

创建一个链路生成器,我们主要使用它来进行链路追踪

	// 创建生成器,这里配置了资源与 导出器.
tp := trace.NewTracerProvider(
		trace.WithBatcher(exp),
		trace.WithResource(newResource()),
	)
// 下面让我们看一下它都有哪些配置
// 这里创建的是批量处理导出器,也就是我们常用的
WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption)
// 这里可以添加别的导出器,也就是说可以同时发送给jaeger与zipkin
WithSpanProcessor(sp SpanProcessor)
// 配置资源
WithResource(r *resource.Resource)
// Tracers id与span id生成器,默认为随机数
WithIDGenerator(g IDGenerator)
// 设置采样数
WithSampler(s Sampler)
// 设置属性,资源的数量
WithSpanLimits(sl SpanLimits)
WithRawSpanLimits(limits SpanLimits)

这里重点讲解一下SpanProcessor.
SpanProcessor是一个导出器策略,存储着如何发送span到链路服务器上,有两种方式批处理和立即发送。
我们上面说的WithCollectorEndpoint 与 WithAgentEndpoint 都是创建的BatchSpanProcessor 也就是批处理导出器策略.还存在一个SpanProcessor为simpleSpanProcessor,这个就是立刻发送,没有批处理操作.
我们添加其他导出器以及策略的方式:
如果使用BatchSpanProcessor 那么在创建TracerProvider时的传参使用trace.WithBatcher即可
如果想自定义,则使用WithSpanProcessor
比如使用simpleSpanProcessor,则设置为 WithSpanProcessor(jaeger.NewSimpleSpanProcessor(exporter SpanExporter))

没错，想要添加一个导出器就需要配置导出策略。所以导出器与导出策略时绑定的。

otel

otel是一个全局配置组件，我们可以将生成器设置为全局属性，方便调用。

otel.SetTracerProvider(tp)

注意

具体的span使用请访问
下文都是拷贝官网.

获取当前跨度

通过上面我们知道,对当前跨度的操作是使用span就可以了,但是在日常过程中我们不能传输两个值一个Context和span(通常只传输Context),所以可以使用Context逆向解析出当前的span.

ctx := context.TODO()
span := trace.SpanFromContext(ctx)

:::success
下面所有设置都会在每个span的log中展示出来,只是为了更能标识信息,没有实质性的用处.(比如设置even,并不是运行这个事件,只是输出一个key为even value 为msg的信息)
:::

设置span状态

span.SetStatus(codes.Error, "operationThatCouldFail failed")

设置span属性

span.SetAttributes(attribute.Bool("isTrue", true), attribute.String("stringAttr", "hi!"))

记录错误

span.RecordError(err)

设置活动

span.AddEvent("Acquiring lock")

tp.Shutdown

注意在使用完后已经要调用Shutdown，它的功能是关闭客户端与链路服务器之间的连接，也就是我们为两个服务建立连接后为了防止资源浪费所以会调用 con.close() 即使关闭.

defer func() {
		if err := tp.Shutdown(context.Background()); err != nil {
			fmt.Println(err)
		}
	}()

到此这篇关于OpenTelemetry-go的SDK使用方法的文章就介绍到这了,更多相关OpenTelemetry-go的sdk内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们！