« OpenTelemetry API 贡献 »
Elastic 文档 ›

OpenTracing API

编辑

OpenTracing API编辑

Elastic APM Go 代理提供了一个 OpenTracing API 的实现，它构建在核心 Elastic APM API 之上。

通过 OpenTracing API 创建的 Span 将被转换为 Elastic APM 事务或 Span。根 Span 和使用远程 Span 上下文创建的 Span 将被转换为 Elastic APM 事务。所有其他 Span 将被创建为 Elastic APM Span。

初始化 Tracer编辑

OpenTracing API 实现是作为核心 Elastic APM API 之上的桥梁实现的。要初始化 OpenTracing Tracer 实现，您必须首先导入 apmot 包

import (
	"go.elastic.co/apm/module/apmot/v2"
)

apmot 包导出一个函数 "New"，它返回 opentracing.Tracer 接口的实现。如果您不带任何参数调用 apmot.New()，则返回的 Tracer 将包装 apm.DefaultTracer()。如果您希望使用不同的 apm.Tracer，则可以使用 apmot.New(apmot.WithTracer(t)) 传递它。

otTracer := apmot.New()

获得 opentracing.Tracer 后，使用标准 OpenTracing API 将 Span 报告给 Elastic APM。有关 OpenTracing Go API 的文档，请参阅 opentracing-go。

import (
	"context"

	"go.elastic.co/apm/module/apmot/v2"

	"github.com/opentracing/opentracing-go"
)

func main() {
	opentracing.SetGlobalTracer(apmot.New())

	parent, ctx := opentracing.StartSpanFromContext(context.Background(), "parent")
	child, _ := opentracing.StartSpanFromContext(ctx, "child")
	child.Finish()
	parent.Finish()
}

混合使用原生 API 和 OpenTracing API编辑

当您导入 apmot 时，使用 原生 API 创建的事务和 Span 将作为 OpenTracing Span 提供，使您能够混合使用原生 API 和 OpenTracing API。例如：

// Transaction created through native API.
transaction := apm.DefaultTracer().StartTransaction("GET /", "request")
ctx := apm.ContextWithTransaction(context.Background(), transaction)

// Span created through OpenTracing API will be a child of the transaction.
otSpan, ctx := opentracing.StartSpanFromContext(ctx, "ot-span")

// Span created through the native API will be a child of the span created
// above via the OpenTracing API.
apmSpan, ctx := apm.StartSpan(ctx, "apm-span", "apm-span")

opentracing.SpanFromContext 函数将返回一个 opentracing.Span，它包装了 apm.Span 或 apm.Transaction。这些 Span 对象仅用于在通过 OpenTracing API 创建新 Span 时传递上下文，而不是完全功能的 Span。特别是，Finish 和 Log* 方法是无操作的，Tracer 方法返回一个无操作的 Tracer。

Elastic APM 特定标签编辑

Elastic APM 定义了一些未包含在 OpenTracing API 中但在 Elastic APM 上下文中相关的标签。某些标签仅与 Elastic APM 事务相关。

  • type - 设置事务或 Span 的类型，例如 "request" 或 "ext.http"。如果未指定 type，则可以从其他标签推断出类型。例如，如果指定了 "http.url"，则对于事务，类型将为 "request"，对于 Span，类型将为 "ext.http"。如果无法推断出类型，则将其设置为 "unknown"。

以下标签仅与根 Span 或服务入口 Span 相关，它们将转换为 Elastic APM 事务

  • user.id - 设置用户 ID，该 ID 显示在 Elastic APM 应用程序中事务详细信息的“用户”选项卡中
  • user.email - 设置用户电子邮件，该电子邮件显示在 Elastic APM 应用程序中事务详细信息的“用户”选项卡中
  • user.username - 设置用户名，该用户名显示在 Elastic APM 应用程序中事务详细信息的“用户”选项卡中
  • result - 设置事务的结果。如果未指定 result，但 error 标签设置为 true，则事务结果将设置为 "error"

Span 日志编辑

Span.LogKV 和 Span.LogFields 方法将向 Elastic APM 发送错误事件，其中 "event" 字段设置为 "error" 的日志。

已弃用的日志方法 Span.Log、Span.LogEvent 和 Span.LogEventWithPayload 是无操作的。

注意事项编辑

上下文传播编辑

我们支持 TextMap 和 HTTPHeaders 传播格式；当前不支持 Binary。

Span 引用编辑

我们仅支持 ChildOf 引用。当前不支持其他引用，例如 FollowsFrom。

行李编辑

Span.SetBaggageItem 是无操作的；行李项将被静默丢弃。

« OpenTelemetry API 贡献 »