OpenTelemetry 桥接

Elastic .NET APM Agent 中的 OpenTelemetry 桥接将 OpenTelemetry span 桥接到 Elastic APM 事务和 span 中。Elastic APM OpenTelemetry 桥接允许您使用与供应商无关的 OpenTelemetry 追踪 API 手动检测您的代码，并让 Elastic .NET APM Agent 处理这些 API 调用。这意味着您可以使用 Elastic APM Agent 进行追踪，而无需因为使用 APM Agent 自身的 公共 API 添加手动追踪而产生任何供应商锁定。

OpenTelemetry 桥接是核心 Agent 包的一部分 (Elastic.Apm)，因此您无需添加其他依赖项。

从 1.23.0 版本开始，OpenTelemetry 桥接默认启用。

这允许您通过 ActivitySource 和 StartActivity() 检测代码，无需任何额外配置。

如果您想禁用桥接，目前可以通过 OpenTelemetryBridgeEnabled 配置设置来禁用它。

如果您通过环境变量配置 Agent，请将 ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED 环境变量设置为 false。

如果您通过 appsettings.json 文件配置 Agent，则将 ElasticApm:OpenTelemetryBridgeEnabled 设置为 false。

{
  "ElasticApm":
    {
      "ServerUrl":  "http://myapmserver:8200",
      "SecretToken":  "apm-server-secret-token",
      "OpenTelemetryBridgeEnabled": false
    }
}

您可以创建 OpenTelemetry span，或者用 .NET 的术语来说，您可以通过活动源开始创建新的活动，Agent 将自动桥接这些 span。

public static void Sample()
{
	var src = new ActivitySource("Test");
	using var activity1 = src.StartActivity(nameof(Sample), ActivityKind.Server);
	Thread.Sleep(100);
	using var activity2 = src.StartActivity("foo");
	Thread.Sleep(150);
}

上面的代码片段创建了一个名为 Sample 的 span 和一个名为 foo 的 Sample 子 span。桥接将从 Sample 创建一个事务和一个名为 foo 的子 span。

您还可以混合使用 Activity API 和 公共 API，OpenTelemetry 桥接将负责将 span 放置到正确的位置。这样做的好处是，如果您已经有一些通过 公共 API 检测的库，但将来想使用与供应商无关的 OpenTelemetry API，则无需一次性替换所有公共 API 调用。

/// ElasticTransaction
/// -
/// ---> OTelSpan
///           -
///           ---> ElasticSpan

var src = new ActivitySource("Test");
tracer.CaptureTransaction( nameof(Sample4), "test", t =>
{
	Thread.Sleep(100);
	using (var activity = src.StartActivity("foo"))
	{
		tracer.CurrentSpan.CaptureSpan("ElasticApmSpan", "test", () => Thread.Sleep(50));
		Thread.Sleep(150);
	}
});

上面的代码片段使用 Elastic .NET APM Agent 的 公共 API 创建了一个事务。然后它创建一个名为 foo 的活动；此活动将是先前创建的事务的子活动。最后，再次使用 Elastic .NET APM Agent 的 公共 API 创建一个 span；此 span 将是 OpenTelemetry span 的子 span。

当然，这些调用不必在同一方法中。此处描述的概念适用于不同的方法、类型或库。

Elastic APM Agent 还与 Activity.Baggage 集成。

这是一个使用上述 API 设置行李值的示例

_activitySource.StartActivity("MyActivity")?.AddBaggage("foo", "bar");

Elastic APM Agent 将根据 W3C 行李规范 自动传播这些值，并且 Activity.Baggage 会根据传入的 baggage 头自动填充。

此外，Agent 还提供 BaggageToAttach 配置，以自动将 Activity.Baggage 中的值附加到捕获的事件。

.NET 中的 OpenTelemetry 通过 Activity API 实现，并且有一个 OpenTelemetry shim 更紧密地遵循 OpenTelemetry 规范。此 shim 建立在 Activity API 之上。

Elastic .NET APM Agent 中的 OpenTelemetry 桥接针对 Activity API。由于 OpenTelemetry .NET shim 建立在 Activity API 之上，因此 shim 也被隐式支持，尽管我们没有直接测试它，因为 Activity API 是 .NET 的推荐 OpenTelemetry API。

并非所有 OpenTelemetry API 功能都受支持。

此桥接仅支持追踪 API。指标 API 当前不受支持。

Span 事件 (Span#addEvent()) 当前不受支持。事件将被静默丢弃。

在进程内或进程外传播行李不受支持。行李项将被静默丢弃。