日志服务支持通过 OpenTelemetry SDK 直接写入 Trace 数据到日志服务。本文档以 Go SDK 为例，演示 Golang 应用接入 Trace 存储的操作步骤，适用于业务系统首次使用全链路追踪服务的场景。 ## 前提条件 * 已配置 Golang 开发环境，请参考 [Go 官网](https://golang.org/doc/install/source)下载和安装 Go 编译运行环境。 * Go 版本为 1.19 及后续版本，您可以执行 `go version` 检查当前 Go 的版本信息。 ## 背景信息在微服务、分布式等涉及多个服务交互的架构或系统中，可以使用全链路追踪服务进行服务调用链路分析或架构性能监控。日志服务通过 Trace 存储提供基于 [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) 标准协议的分布式链路追踪能力，您可以参考本文档，在业务系统中部署 Trace 存储，在数据源上启用 Trace 事件，采集并发送日志数据到火山引擎日志服务中。 ## 操作步骤 ## 1 创建 Trace 实例在日志服务控制台中创建一个 Trace 实例，用于配合业务系统采集并发送、管理 Trace 数据。日志服务会同步创建一个日志主题用于存储 Trace 数据。详细操作步骤请参考[创建 Trace 实例](https://www.volcengine.com/docs/6470/812320)。 ## 2 添加相关依赖在本地 Go 项目中执行以下命令添加对应依赖。 ```Shell # 添加otel协议依赖 go get go.opentelemetry.io/otel go get go.opentelemetry.io/otel/trace go get go.opentelemetry.io/otel/bridge/opentracing # 添加otel exporter的依赖（用户需要通过exporter向日志服务发送trace数据） go get go.opentelemetry.io/otel/exporters/otlp/otlptrace # 添加http exporter依赖（如果配置的是日志服务的http端口，需要添加这个依赖） go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp # 添加grpc exporter依赖（如果配置的是日志服务的grpc端口，需要添加这个依赖） go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc ``` ## 3 初始化 Provider 添加依赖后，您需要通过执行代码完成 OpenTelemetry Provider 的初始化。您需要指定要使用的数据传输协议，以便 OpenTelemetry 将数据从您的应用程序传输到 Trace 实例。在 Tracer 类的构造函数中，可以使用协议参数来指定该协议。初始化时应配置日志服务接入点和鉴权相关参数，详细信息请参考[参数说明](https://www.volcengine.com/docs/6470/812322#.5Y-C5pWw6K-05piO)。日志服务支持通过以下方式配置鉴权信息： * 在 gRPC协议、HTTPS 协议的请求头（Header）中配置。 * 在 OpenTelemetry 协议的 Resource 字段中配置鉴权信息。 ### HTTP 协议初始化示例通过 HTTP 协议方式接入 Trace 存储时，可参考以下示例代码完成 OpenTelemetry Provider 的初始化。日志服务提供两种鉴权参数的配置方式，您可以按需选择对应的示例代码进行接入。详细参数信息请参考[参数说明](https://www.volcengine.com/docs/6470/812322#.5Y-C5pWw6K-05piO)。 * 通过 OpenTelemetry 协议的 Resource 参数配置鉴权参数： ```Go import ( "context" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/exporters/otlp/otlptrace" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" "go.opentelemetry.io/otel/sdk/resource" "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.10.0" ) // 初始化endpoint为日志服务http open telemetry协议端口并且在trace数据的body中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithHttpResource(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { traceTopicKey := attribute.Key("tls.otel.tracetopic") akKey := attribute.Key("tls.otel.ak") skKey := attribute.Key("tls.otel.sk") regionKey := attribute.Key("tls.otel.region") opts := []otlptracehttp.Option{otlptracehttp.WithEndpoint(endPoint + ":4318")} // endpoint为http 【参数配置】 exporter, _ := otlptrace.New( context.Background(), otlptracehttp.NewClient(opts...), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), // 在otel请求body中添加TLS需要的鉴权字段 traceTopicKey.String(topicId), akKey.String(ak), skKey.String(sk), regionKey.String(region), )), ) return tp } ``` * 在 HTTPS 协议的请求头（Header）中配置鉴权参数： ```Go import ( "context" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/exporters/otlp/otlptrace" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" "go.opentelemetry.io/otel/sdk/resource" "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.10.0" ) // 初始化endpoint为日志服务http open telemetry协议端口并且在http请求的hader中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithHttpHeader(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { // 在http header中添加TLS需要的鉴权字段 opts := []otlptracehttp.Option{otlptracehttp.WithEndpoint(endPoint + ":4318"), // endpoint参考【参数配置】 otlptracehttp.WithHeaders(map[string]string{"x-tls-otel-tracetopic": topicId, "x-tls-otel-ak": ak, "x-tls-otel-sk": sk, "x-tls-otel-region": region})} exporter, _ := otlptrace.New( context.Background(), otlptracehttp.NewClient(opts...), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), )), ) return tp } ``` ### gRPC 协议初始化示例通过 gRPC 协议方式接入 Trace 存储时，可参考以下示例代码完成 OpenTelemetry Provider 的初始化。日志服务提供两种鉴权参数的配置方式，您可以按需选择对应的示例代码进行接入。详细参数信息请参考[参数说明](https://www.volcengine.com/docs/6470/812322#.5Y-C5pWw6K-05piO)。 * 通过 OpenTelemetry 协议的 Resource 参数配置鉴权参数： ```Go import ( "context" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/exporters/otlp/otlptrace" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" "go.opentelemetry.io/otel/sdk/resource" "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.10.0" "google.golang.org/grpc/credentials/insecure" ) // 初始化endpoint为日志服务grpc open telemetry协议端口并且在trace数据的body中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithGrpcResource(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { exporter, _ := otlptrace.New( context.Background(), otlptracegrpc.NewClient(otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()), otlptracegrpc.WithEndpoint(endPoint+":4317")), // endpoint为grpc 【参数配置】 ) traceTopicKey := attribute.Key("tls.otel.tracetopic") akKey := attribute.Key("tls.otel.ak") skKey := attribute.Key("tls.otel.sk") regionKey := attribute.Key("tls.otel.region") tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), // 在otel请求body中添加TLS需要的鉴权字段 traceTopicKey.String(topicId), akKey.String(ak), skKey.String(sk), regionKey.String(region), )), ) return tp } ``` * 在 gRPC 协议的请求头（Header）中配置鉴权参数： ```Go import ( "context" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/exporters/otlp/otlptrace" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" "go.opentelemetry.io/otel/sdk/resource" "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.10.0" "google.golang.org/grpc/credentials/insecure" ) // 初始化endpoint为日志服务grpc open telemetry协议端口并且在grpc请求的hader中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithGrpcHeader(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { // 在grpc header中添加TLS需要的鉴权字段 exporter, _ := otlptrace.New( context.Background(), // otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()) 配置tls方式访问 otlptracegrpc.NewClient(otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()), otlptracegrpc.WithEndpoint(endPoint+":4317"), // endpoint为grpc 【参数配置】 otlptracegrpc.WithHeaders(map[string]string{"x-tls-otel-tracetopic": topicId, "x-tls-otel-ak": ak, "x-tls-otel-sk": sk, "x-tls-otel-region": region})), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), )), ) return tp } ``` ### 参数说明初始化 Provider 时，需要在初始化代码中配置接入点和鉴权相关的参数，参数说明如下。 * 接入点相关参数 endpoint 为日志服务的接入点信息，由服务地址和端口号组成，不同协议类型的端口号不同。接入点格式为 `${tls_endpoint}:端口号`，其中 `${tls_endpoint}` 为日志服务的服务地址，获取方式请参考[服务地址](https://www.volcengine.com/docs/6470/73641)。 * HTTPS 协议的接入点为 `${tls_endpoint}:4318`。例如 `https://tls-cn-beijing.ivolces.com:4318`。 * gRPC 协议的接入点为 `${tls_endpoint}:4317`，例如 `https://tls-cn-beijing.ivolces.com:4317`。为保证信息传输的安全性，使用 gRPC 协议时必须开启 TLS。 * 鉴权相关参数：您可以在初始化时通过两种方式配置鉴权信息，即在 gRPC 协议、HTTPS 协议的 Header 中或 OpenTelemetry 协议的 Resource 字段中配置。不同配置方式的参数说明如下。 |Header key |Resource key |示例 |说明 | |---|---|---|---| |x\-tls\-otel\-tracetopic |tls.otel.tracetopic |39f0bce1\-e37e\-4dc5\-ab06\-801d310b\*\*\*\* |用于存储 Trace 数据的日志主题 ID。

创建 Trace 实例后，日志服务会自动创建日志主题，详细说明请参考[相关资源](https://www.volcengine.com/docs/6470/349091#.55u45YWz6LWE5rqQ)。 | |x\-tls\-otel\-ak |tls.otel.ak |AKKTNTA1OTlmOWQ1NTM5DNk5OIWwZGNmMTg0ZWUxNmU\*\*\*\* |火山引擎主账号或子账号的 Access Key ID。在火山引擎控制台[密钥列表页面](https://console.volcengine.com/iam/keymanage/)，根据页面提示查看并复制 Access Key ID。 | |x\-tls\-otel\-sk |tls.otel.sk |T0RPLS5EUTFZV1JrTmpAKE5EaGCVRGsxTjJVMk5UTTBNV1UzKODJME1U\*\*\*\* |火山引擎主账号或子账号的 Secret Access Key。在火山引擎控制台[密钥列表页面](https://console.volcengine.com/iam/keymanage/)，根据页面提示查看并复制 Secret Access Key。 | |x\-tls\-otel\-region |tls.otel.region |cn\-beijing |Trace 实例所在的地域 ID（Region）。您可以在[服务地址](https://www.volcengine.com/docs/6470/73641)中查看指定地域的 ID。 | ## 4 使用 tlsOtelTracer 发送 Trace 数据参考以下示例代码，通过 tlsOtelTracer 发送 Trace 数据到火山引擎日志服务。详细说明请参考 [OpenTelemetry 官方文档](https://opentelemetry.io/docs/instrumentation/go/manual/)。

说明

在使用 OpenTelemetry 收集和发送 Trace 数据时，请确保数据的准确性和完整性。为了保证数据的可靠性，建议您在应用程序中对数据进行验证和错误处理。

您也可以启用 Trace 事件，在数据源上使用 OpenTelemetry 的 Config 类设置相应的事件处理程序，自动发送 Trace 数据到日志服务。详细说明请参考 OpenTelemetry 官方文档。

```Go package main import ( "context" "fmt" "math/rand" "strconv" "time" "github.com/google/uuid" "github.com/opentracing/opentracing-go" "github.com/opentracing/opentracing-go/ext" "go.opentelemetry.io/otel/attribute" otbridge "go.opentelemetry.io/otel/bridge/opentracing" "go.opentelemetry.io/otel/exporters/otlp/otlptrace" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" "go.opentelemetry.io/otel/sdk/resource" "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.10.0" "google.golang.org/grpc/credentials/insecure" ) func main() { SendTrace(1000) time.Sleep(time.Minute) } func SendTrace(traceCnt int) { endPoint := "tls-cn-beijing.volces.com" // 别的region请更换相关域名，私网请使用私网域名 topicId := "${topicId}" ak := "${AK}" sk := "${SK}" region := "cn-shanghai" // 别的region请更换相关region // 选择不同的方式初始化trace provider httpHeaderProvider := InitTlsOtelTracerWithHttpHeader(endPoint, topicId, ak, sk, region) // httpResourceProvider := InitTlsOtelTracerWithHttpResource(endPoint, topicId, ak, sk, region) // grpcHeaderProvider := InitTlsOtelTracerWithGrpcHeader(endPoint, topicId, ak, sk, region) // grpcResourceProvider := InitTlsOtelTracerWithGrpcResource(endPoint, topicId, ak, sk, region) tracer, _ := otbridge.NewTracerPair(httpHeaderProvider.Tracer("my_trace")) ctx := context.TODO() for i := 0; i < traceCnt; i++ { sendTrace(ctx, tracer) } } func sendTrace(ctx context.Context, tracer *otbridge.BridgeTracer) { var OperationName []string OperationName = append(OperationName, "Operation_1", "Operation_2", "Operation_3", "Operation_4", "Operation_5") i := 0 var last_span opentracing.Span var span opentracing.Span for { uid, _ := uuid.NewUUID() index := strconv.Itoa(i) if i == 0 { span = spanInit(true, ctx, "test.span."+index, tracer, nil) } else { span = spanInit(false, ctx, "test.span"+index, tracer, last_span.Context()) } ext.SpanKindRPCClient.Set(span) ext.PeerService.Set(span, "tls-test-service") // // // #nosec span.LogKV( "event", "soft error", "type", "cache timeout", "waited.millis", 1500) span.SetTag("uuid", uid.String()) span.SetTag("host", "") span.SetBaggageItem("BaggageItem", "TLS test") span.SetOperationName(OperationName[rand.Intn(4)]) span.FinishWithOptions(opentracing.FinishOptions{FinishTime: time.Now()}) last_span = span fmt.Println("successful", i) i++ if i > 100 { break } } } func spanInit(isRoot bool, context context.Context, span_name string, otTracer *otbridge.BridgeTracer, childOfSpanContext opentracing.SpanContext) opentracing.Span { var span opentracing.Span if isRoot { span, _ = opentracing.StartSpanFromContext(context, span_name+".root.span") } else { span = otTracer.StartSpan("TLS test", opentracing.ChildOf(childOfSpanContext)) } return span } // 初始化endpoint为日志服务http open telemetry协议端口并且在http请求的hader中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithHttpHeader(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { // 在http header中添加TLS需要的鉴权字段 opts := []otlptracehttp.Option{otlptracehttp.WithEndpoint(endPoint + ":4318"), // endpoint参考【参数配置】 otlptracehttp.WithHeaders(map[string]string{"x-tls-otel-tracetopic": topicId, "x-tls-otel-ak": ak, "x-tls-otel-sk": sk, "x-tls-otel-region": region})} exporter, _ := otlptrace.New( context.Background(), otlptracehttp.NewClient(opts...), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), )), ) return tp } // 初始化endpoint为日志服务http open telemetry协议端口并且在trace数据的body中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithHttpResource(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { traceTopicKey := attribute.Key("tls.otel.tracetopic") akKey := attribute.Key("tls.otel.ak") skKey := attribute.Key("tls.otel.sk") regionKey := attribute.Key("tls.otel.region") opts := []otlptracehttp.Option{otlptracehttp.WithEndpoint(endPoint + ":4318")} // endpoint为http 【参数配置】 exporter, _ := otlptrace.New( context.Background(), otlptracehttp.NewClient(opts...), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), // 在otel请求body中添加TLS需要的鉴权字段 traceTopicKey.String(topicId), akKey.String(ak), skKey.String(sk), regionKey.String(region), )), ) return tp } // 初始化endpoint为日志服务grpc open telemetry协议端口并且在grpc请求的hader中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithGrpcHeader(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { // 在grpc header中添加TLS需要的鉴权字段 exporter, _ := otlptrace.New( context.Background(), // otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()) 配置tls方式访问 otlptracegrpc.NewClient(otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()), otlptracegrpc.WithEndpoint(endPoint+":4317"), // endpoint为grpc 【参数配置】 otlptracegrpc.WithHeaders(map[string]string{"x-tls-otel-tracetopic": topicId, "x-tls-otel-ak": ak, "x-tls-otel-sk": sk, "x-tls-otel-region": region})), ) tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), )), ) return tp } // 初始化endpoint为日志服务grpc open telemetry协议端口并且在trace数据的body中添加鉴权信息的TracerProvider func InitTlsOtelTracerWithGrpcResource(endPoint string, topicId string, ak string, sk string, region string) *trace.TracerProvider { exporter, _ := otlptrace.New( context.Background(), otlptracegrpc.NewClient(otlptracegrpc.WithTLSCredentials(insecure.NewCredentials()), otlptracegrpc.WithEndpoint(endPoint+":4317")), // endpoint为grpc 【参数配置】 ) traceTopicKey := attribute.Key("tls.otel.tracetopic") akKey := attribute.Key("tls.otel.ak") skKey := attribute.Key("tls.otel.sk") regionKey := attribute.Key("tls.otel.region") tp := trace.NewTracerProvider( trace.WithBatcher(exporter), trace.WithResource(resource.NewWithAttributes( semconv.SchemaURL, semconv.ServiceNameKey.String("your_service_name"), // 在otel请求body中添加TLS需要的鉴权字段 traceTopicKey.String(topicId), akKey.String(ak), skKey.String(sk), regionKey.String(region), )), ) return tp } ``` ## 验证接入结果成功接入 Trace 数据后，您可以通过日志服务的检索分析功能，在线查看采集到的 Trace 数据。如果 Trace 实例对应的日志主题中可检索到您上传的 Trace 数据，表示接入成功。检索 Trace 数据的方式，请参考[单主题检索日志](https://www.volcengine.com/docs/6470/1206094)。例如，您可以通过以下 SQL 语法检索指定 TraceID 对应的 Trace 数据详情。 ```SQL * ｜ select * where TraceID = '877247fa95024d2f3a1234216010****' ```