tracex

应用性能遥测Uptrace组件

在使用前，确保已经配置以下环境变量

对于配置遥测地址的部分，可以参考原DSN地址格式对应填写：

<TRACE_SCHEME>://<TRACE_KEY>@<TRACE_ADDRESS>:<TRACE_PORT>/<TRACE_PROJECT_ID>

键	值类型	默认值	说明	必填
TRACE_ENABLED	bool	false	启用性能遥测组件	√
TRACE_SCHEME	string	http	遥测安全类型，https为启用TLS
TRACE_ADDRESS	string	-	遥测地址	√
TRACE_PORT	int	14317	遥测端口，建议选用gRPC端口
TRACE_KEY	string	-	遥测应用Key	√
TRACE_PROJECT_ID	int	-	遥测应用ID	√
TRACE_SERVICE_NAME	string	-	服务名	√
TRACE_SERVICE_VERSION	string	-	服务版本	√
TRACE_ENVIRONMENT	string	-	服务环境	√
TRACE_PKG_NAME	string	-	软件包名	√
TRACE_HOST_NAME	string	(自动获取)	主机名，默认自动获取本主机名

确保环境变量无误后，在init()或在main()的开头部分，初始化trace组件，组件会自动检查必须变量并在异常时退出

不需要额外判断TRACE_ENABLED的机制，在不需要运行该组件时不会产生其他副作用

ctx := context.Background()
helper := &ServiceTraceHelper{}
helper.SetupTrace()
defer helper.Shutdown(ctx)

通过NewTracer()获得全局tracer对象，通过Start()启动并记录一个上下文

tracer := helper.NewTracer()
ctxMain, main := tracer.Start(ctx, "main")
defer main.End()

在每个调用层级启动一个上下文，组件会自动跟踪并记录调用栈。请注意，必须使用从父级获得的ctx，直接使用全局ctx会导致调用栈记录不正确，子父继承的ctx记录了调用关系

tracer := helper.NewTracer()
ctxMain, main := tracer.Start(ctx, "main")  // Use this ctx
defer main.End()

_, child1 := tracer.Start(ctxMain, "child1-of-main")
child1.SetAttributes(attribute.String("key1", "value1"))
// ...do something
child1.RecordError(errors.New("error1"))  // record errors
child1.End()

_, child2 := tracer.Start(ctxMain, "child2-of-main")
child2.SetAttributes(attribute.Int("key2", 42), attribute.Float64("key3", 123.456))
// ...do something
child2.End()

同样地，组件也可以在协程中正常使用，但是需要有相应的等待同步机制，确保在主协程结束前调用End()，否则会丢失一整个上下文的记录

tracer := helper.NewTracer()
ctxMain, main := tracer.Start(ctx, "main")  // Use this ctx
defer main.End()
wg := sync.WaitGroup{}
wg.Add(1)

go func() {
    defer wg.Done()
    _, go1 := tracer.Start(ctx, "go1-of-main")
    defer go1.End()
    // ...do something
}()

wg.Wait()

最后，你可以通过TraceURL()来打印当前会话的URL，但是组成URL的host由你配置的DSN地址决定

fmt.Printf("trace: %s\n", uptrace.TraceURL(main))