diff --git a/specification/trace/api.md b/specification/trace/api.md index cf0eb92..25a8e2e 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -97,8 +97,8 @@ or because its easier with dependency injection frameworks. 本 API 必须接受以下参数： -- `name` (required): 该值必须标识出 [instrumentation library](../overview.md#instrumentation-libraries) - (例如 `io.opentelemetry.contrib.mongodb`)，而不是 instrumented library. +- `name` (required): 该值必须是 [instrumentation library](../overview.md#instrumentation-libraries) 的标识 + (例如 `io.opentelemetry.contrib.mongodb`)，而不是 instrumented library 的标识. 如果指定了一个无效的名称（空或者空字符串），将会返回一个可工作的默认 Trace ，而不是返回 null 或者抛出异常。 当一个实现 OpenTelemetry API 的库不支持“命名”功能时，该库可以忽略该命名，并对所有调用返回一个默认实例。(例如，一个甚至与可观察性无关的实例)。 @@ -192,8 +192,7 @@ Tracing API 必须在 `TraceState` 上至少提供以下操作： * 删除 key/value pair 这些操作必须遵循 [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#mutating-the-tracestate-field) 中的定义规则。 -所有转变操作都必须返回新的修改生效的`TraceState`。`TraceState` 必须所有时候都按照 -[W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header-field-values) +所有转变操作都必须返回新的修改生效的`TraceState`。`TraceState` 必须所有时候都按照[W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header-field-values) 规范中指定的规则进行验证。每个转变操作必须验证输出的参数。如果操作被传入了无效值，必须不能返回带有无效数据的 `TraceState`。 并且必须遵循 [一般错误处理准则](../error-handling.md) 。（例如，通常不得返回 null 或抛出异常） @@ -245,13 +244,13 @@ span 名称应当是一种具有通用性字符串，便于后续的统计学处 - 构建响应 - 发送响应 -可以通过创建 Child spans（或者在一些情况下用events）来更详细观察描述子操作。Child spans 应当衡量各个子操作的时间，并可以添加相应的属性。 +可以通过创建 Child spans（或者在一些情况下用 events）来更详细观察描述子操作。Child spans 应当衡量各个子操作的时间，并可以添加相应的属性。 Span 的开始时间应当设置为创建 Span 时的当前时间。Span 创建后应当可以更改名称，设置属性，添加事件和设置状态。在 Span 的结束时间被设置后，这些都不允许被改变。 `Span`s 没有在进程中传播的功能。为了防止被误用，实现中除了 `Span` 自己的 `SpanContext` 外不能访问到 `Span` 的属性。 -厂商可以通过实现 `Span` 接口来满足厂商自身特定的逻辑，然而这些可供替代的实现不得允许调用者直接创建 `Span`。所有的 `Span` 必须由 `Tracer` 创建。 +厂商可以通过实现 `Span` 接口来满足厂商自身特定的逻辑，然而这些可供替代的实现禁止允许调用者直接创建 `Span`。所有的 `Span` 必须由 `Tracer` 创建。 ### 创建 Span @@ -267,7 +266,7 @@ API 必须接受以下参数： API 需要提供一个选项，用于设置默认行为：将当前的 `Context` 作为父级。 API 禁止接收 `Span` 或 `SpanContext` 作为父级，只能是完整的 `Context`。 - Span 的语义父级必须根据 [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) 中描述的规则确定。 + Span 的语义父级必须遵守 [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) 中描述的规则。 - [`SpanKind`](#spankind)，默认值为: `SpanKind.Internal`。 @@ -299,7 +298,7 @@ API 必须接受以下参数： 在创建 `Span` 时，用户必须能够记录与其他 `Span`s 的链接。链接的 `Span` 可以来自相同或不同的 `Trace`。请看链接的[描述](../overview.md#links-between-spans)。Span 创建后不能添加链接。 -一个 `Link` 由一下属性组成。 +一个 `Link` 由以下属性组成。 - `SpanContext` ，要链接的 `Span` 所属的 `SpanContext`。 - 零或多个 [`属性`](../common/common.md#attributes) 用于描述链接。 @@ -318,25 +317,25 @@ Span 创建 API 必须提供： Span 接口必须提供： -- 返回 `SpanContext`。一个 API 返回指定的 `Span` 的 `SpanContext`。即使在 Span 结束后，该接口也可以使用。返回的值必须整个 Span 寿命周期内保持不变。可以被称为 `GetContext` 。 +- 返回 `SpanContext`。一个 API 返回指定的 `Span` 的 `SpanContext`。即使在 Span 结束后，返回的值也可以使用。返回的值必须整个 Span 寿命周期内保持不变。可以被称为 `GetContext` 。 #### IsRecording 返回 `true` 当该 `Span` 正在记录信息，例如使用 `AddEvent` 操作的事件，使用 `SetAttributes` 的属性，使用 `SetStatus` 的状态等。 -当 `Span` 结束后，通常会变成非记录状态，因此对结束的 Span，`IsRecording`应当返回 `false`。注意：流数据的实现时，它不知道一个 `Span` 是否结束，这是一个预期的情况。`IsRecording` 在 `Span` 结束后无法被修改 +当 `Span` 结束后，通常会变成非记录状态，因此对结束的 Span，`IsRecording`应当返回 `false`。注意：流式实现（它不知道一个 `Span` 是否结束）是一种预期的情况。在这种情况下，`IsRecording` 在 `Span` 结束后无法被修改。 `IsRecording` 不应当接受任何参数。 这个标记应当用来避免在 Span 没记录时，处理 Span 属性和事件（这两个操作是昂贵的计算）。注意任何子 span 的记录标记都是独立于父 span 的标记来决定的（通常基于 [SpanContext](#spancontext) 上的 TraceFlags 中的采样标记）。 -这个标签可能是 `true`， 当整个事件再被采样的时候。这允许不需要发送到后端即可记录和处理单个 `Span` 的信息。这个情况的一个例子可能是记录和处理所有的传入请求，用于创建 SLA/SLO 延迟图，同事只向后端发送一个子集（采样的子集）。详情参见 [sampling section of SDK design](sdk.md#sampling)。 +即使整个链路都不被采样，这个标记仍然可能为 `true`。这允许不需要发送到后端即可记录和处理单个 `Span` 的信息。这个情况的一个例子可能是记录和处理所有的传入请求，用于创建 SLA/SLO 延迟图，同时只向后端发送一个子集（采样的子集）。详情参见 [sampling section of SDK design](sdk.md#sampling)。 API 的使用者应当通过 instrumenting 代码访问 IsRecording 属性，除非在 context 传播器中使用，否则永远不要访问SampledFlag。 #### 设置属性 Set Attributes -`Span` 必须支持设置予以相关的 [`属性`](../common/common.md#attributes) 。 +`Span` 必须支持设置与其相关的 [`属性`](../common/common.md#attributes) 。 Span 接口必须提供： @@ -360,13 +359,13 @@ Span 接口必须提供： - 一个用于记录单个`事件`的 API，事件属性被作为参数进行传递。这个 API 可以被成为 `AddEvent`。这个 API 需要该事件的名称，可选的属性和一个可选的`时间戳`（用于指定事件的发生时间），这些既可以是单独的参数，也可以是封装他们的不可变对象，以实现语言最合适的方式为准。如果用户没有自定义时间戳，那么会自动设置时间戳为该 API 被调用的时间。 -时间应按记录顺序排序。这通常和时间的时间戳相匹配，但时间可能使用自定义的时间戳进行乱序记录。 +事件应按记录顺序排序。这通常和事件的时间戳相匹配，但事件可能使用自定义的时间戳进行乱序记录。 消费者 (Consumers) 应注意，用户可以在开始 `Span` 前或结束 `Span` 后 为事件提供时间，因此事件的时间可能早于 span 的开始时间，或晚于 span 的结束时间。本规范不对事件时间超出 `span` 时间范围的情况，进行任何标准化。 注意：OpenTelemetry 项目文档中定义了一些具有语义的 ["标准时间名称和键"](semantic_conventions/README.md) 。 -注意： [`RecordException`](#record-exception) 是一种特殊的变体，用于记录 `AddEvent` 发生的异常时间。 +注意： [`RecordException`](#record-exception) 是 `AddEvent` 的一种特殊变体，用于记录异常事件。 #### 设置状态 @@ -376,14 +375,14 @@ Span 接口必须提供： `Status` 有以下数据定义。 - `StatusCode`，以下所列的数值之一。 -- `Description` 可选，提供状态的描述性信息。`描述`必须当 `StatusCode` 为 `error` 时使用。 +- `Description` 可选，提供状态的描述性信息。`描述`必须当 `StatusCode` 为 `error` 时使用。 `StatusCode` 是下列数值之一： - `Unset` - - 默认状态 + - 默认状态。 - `Ok` - - 表示该操作依据被软件开发者或操作者验证为完全 + - 表示该操作依据被软件开发者或操作者验证为成功完成。 - `Error` - 表示所属操作存在异常。 @@ -393,13 +392,15 @@ Span 接口必须提供： 除以下情况外，状态码应保持不变： -​ 当 Instrumentation 库将状态设置成 Error 时，状态码应当被记录下来并可预测。状态代码应该只能根据语义惯例中定义的规则设置为 ERROR。对于语义约定未涵盖的操作，Instrumentation Libraries 应发布自己的约定，包括状态代码。 +当 Instrumentation 库将状态设置成 Error 时，状态码应当被记录成文档并可预测。状态代码应该只能根据语义惯例中定义的规则设置为 ERROR。对于语义约定未涵盖的操作，Instrumentation Libraries 应发布自己的约定，包括状态代码。 -通常而言，Instrumentation Libraries 不应将状态码设置为 OK，除非有明确合理的目的 。另外除非出现上述错误，否则 Instrumentation Libraries 应将状态码设置为 "未设置"。 +通常而言，除非显示配置，否则 Instrumentation Libraries 不应将状态码设置为 OK。另外除非出现上述错误，否则 Instrumentation Libraries 应将状态码设置为 "未设置"。 软件开发者或操作者可以设置状态码为 `Ok` 。 -分析工具应当对 `Ok` 状态做出响应，抑制它们因其他原因产生的任何错误。例如，为了抑制诸如 404s 错误。 +分析工具应当通过抑制它们因其他原因产生的错误来响应 `Ok` 状态。例如抑制嘈杂的404错误。 +（这里感觉还是翻译不到位，原文：Analysis tools SHOULD respond to an `Ok` status by suppressing any errors they +would otherwise generate. For example, to suppress noisy errors such as 404s.） 只有最后一次调用的值被记录，实现可自由处理之前的调用。 @@ -409,9 +410,7 @@ Span 接口必须提供： 注意： [Samplers](sdk.md#sampler) 只考虑在创建 `span` 期间已经存在的信息。任何创建后的修改，包括更新名称，都不能修改原有的决定。 - `span` 创建后名称更新的替代方法是：如果确定了最终 `span` 名称， 可以使用已明确的时间戳（过去的时间）创建 `Span`，或者将带有所需名称的 `Span` 报告为子 `Span`。 - -创建 `Span` 过程的后段，当 Span 已经使用明确的时间戳开始时 +更新名称的替代方法有：使用过去的时间戳和最终的 `Span` 名来延迟创建 `Span`，或者上报一个带有更新名称的子 `Span`。 需要参数： @@ -423,7 +422,7 @@ Span 接口必须提供： 实现者应当忽略任何在 `end` 调用发生后的所有操作。换言之，span 被结束后就变为不可记录状态。（存在例外，例如当 `Tracer` 是流式事件且没有可变的状态分配给 `Span`）。 -语言 SIGs 可能利用特定语言的语言特性，提供除 `End` 以外的方法用于结束 `span` 。例如 Python 提供了 `with` 形式结束 `span` 。然而，所有实现者的 API 必须在内部存在 `call` 方法并提供文档教导如何使用。 +语言 SIGs 可能利用特定语言的语言特性，提供除 `End` 以外的方法用于结束 `span` 。例如 Python 提供了 `with` 形式结束 `span` 。然而，此类方法的 API 实现必须在内部调用 `End` 方法并记录在文档中。 `End` 必须不会影响子 `Span`s。这些 `Span` 可能在父 `span` 结束后仍然在运行。 @@ -475,7 +474,7 @@ Span 的其余功能必须被定义为无操作行为。注意：这包括 End 跨度种类`描述的第一个属性反映了 Span 是远程的子代或父代。 具有远程父级的 Span 很有趣，因为它们是外部负载的来源。 有远程子代的 Span 也很有趣的，因为它们反映了一个非本地系统的依赖性。 -`跨度种类`描述的第二个属性反映了一个子 Span 调用是表同步。 当一个子 Span 是同步时，一般而言，父 Span 应等待其完成。 理解这个属性对于跟踪系统来说是很有帮助的，因为同步的 Span 可能对整个跟踪延迟有所影响。异步方案可以是远程，也可以是本地。 +`跨度种类`描述的第二个属性反映了一个子 Span 是否同步调用。 当一个子 Span 是同步时，一般而言，父 Span 应等待其完成。 理解这个属性对于跟踪系统来说是很有帮助的，因为同步的 Span 可能对整个跟踪延迟有所影响。异步方案可以是远程，也可以是本地。 为了使 跨度种类有意义，调用者应当分配一个 Span 不超过一个目的。例如，一个服务器端的 Span 不应直接用作另一个远程 span 的父类。 作为一个简单的准则，在提取和序列化远程调用的 SpanContext 之前，instrumentation 应该创建一个新的 Span。 @@ -526,4 +525,4 @@ API 层或扩展包必须包括以下 传播者。 但是，该原则有个重要的例外，这与 `SpanContext` 的传播有关。API 必须使用 Span 的父 Context 的SpanContext 创建一个非记录 [Span](#wrapping-a-spancontext-in-a-span) （不管这是通过显示还是隐式设定的），或者如果父 Context 是一个非记录 Span（如果没有 SDK，通常会是这样），这可能会创建方法中返回父 Span。 -如果父 `Context` 不包含 `Span`，则必须返回一个空的非记录 Span（拥有一个 SpanContext，其 SpanID 和 TraceIDs 全设为零，空的Tracestate 与未采样的 TraceFlags）。这意味着由配置的传播者提供的 SpanContext 将被传播到任何子 span，并最终也会被 `Inject`，但并不会创建新的 `SpanContext`。 \ No newline at end of file +如果父 `Context` 不包含 `Span`，则必须返回一个空的非记录 Span（拥有一个 SpanContext，其 SpanID 和 TraceIDs 全设为零，空的Tracestate 与未采样的 TraceFlags）。这意味着由配置的传播者提供的 SpanContext 将被传播到任何子 span，并最终也会被 `Inject`，但并不会创建新的 `SpanContext`。