上下文

概述

上下文是一种传播机制，它跨越 API 边界，在逻辑执行单元间传递执行范围的值。贯穿各领域的问题通过共享 上下文 对象在进程中访问其数据。

上下文 必须是不可改变的，其写操作必须导致创建一个新的 上下文，其中包含原始值和更新的值。

希望各语言能实现单一的、被广泛使用的 上下文。在没有非常明确，预先存在的选项的情况下，OpenTelemetry 必须提供自己的 Context 实现。根据不同语言的实现，其用法可以是显式，也可以是隐式。

不鼓励用户使用已隐式调用上下文的 instrumentation 时，直接使用上下文 API。在这些情况下，用户将通过横切关注点的 API 作为替代，以执行诸如设置 trace 或设置 baggage 条目等操作。

上下文 将有以下操作，并有各自的语言差异：

键用于横切关注点控制对其本地状态的访问。它们是唯一的，因此其他可能使用相同上下文的库不能意外地使用相同的键。建议有关方面通过 API 控制数据访问，而不是提供对其键的直接公开访问。

API必须接受以下参数：

键的名称。钥匙名称存在的目的是便于调试，并不是键的唯一标识。对 CreateKey 的使用相同名称多次调用不应该返回相同的值，除非语言限制另有规定。不同的语言可能会对预期的类型施加不同的限制，所以这个参数请具体参考实现细节。

API必须返回一个不透明的对象，代表新创建的密钥。

关注点可以在由上下文表示的当前执行状态下访问其本地状态。

API必须接受以下参数：

API 必须返回上下文中指定键的值。

关注点可以用 “上下文 “表示当前的执行状态中记录其本地状态。

API必须接受以下参数：

API 必须返回一个包含新值的新上下文。

这些操作预计只能由隐式使用上下文的语言实现，因此是可选的。这些操作应该只用于实现自动范围切换，并由 SDK 组件和 OpenTelemetry instrumentation 定义的更高级别的 API。

AP I必须返回与调用者当前执行单元相关的上下文。

将上下文与调用者的当前执行单元连接起来。

API必须接受以下参数：

API 必须返回一个值，该值可以作为标记 来恢复上一个的 `上下文’。

注意：每次调用这个操作都应该产生对断开上下文的相应调用。

将与调用者当前执行单元相连接的上下文重置为连接上下文操作之前的值。

本操作旨在帮助确保正确关联上下文与调用者的当前执行单元。用户可以依靠它来识别错误的调用顺序，例如：试图分离一个不是当前实例的上下文。在这种情况下，该操作可以发出信号，警告用户调用顺序错误，如记录一个错误或返回一个错误值。

API必须接受以下参数：

API可以返回一个值，用于检查操作成功与否。