polish trace/api.md

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。