OTel-词汇表

本文档定义了OTel规范中使用的一些术语，其他一些基本术语在概述文档中也有提及。

User Roles

Application Owner

应用程序或服务的维护者，负责配置和管理OTel SDK的生命周期。

Library Author

共享库的维护者，共享库被许多应用程序依赖，也是OTel Instrumentation（仪表监测）的目标。

Instrumentation Author

OTel instrumentation的维护者，针对OTel API开发instrumentation，可以在应用程序代码、共享库或检测库中编写instrumentation。

Plugin Author

OTel SDK插件的维护者，针对OTel SDK插件接口开发。

Common

Signals

OTel由Signal或telemetry类别构成，Metric、Log、Trace和Baggage都是Signal的实例。每个Signal代表了一组连贯的、独立的功能，遵循一个独立的生命周期，生命周期定义着Signal当前的稳定状态。

Packages

在本规范中，术语package描述了一组表示独立依赖的代码，这些代码可以独立于其他package导入到程序中。在某些语言中，此概念可映射到不同的术语，例如“module”。需要注意，在某些语言中，术语“package”指的是不同的概念。

ABI Compatibility

ABI（应用程序二进制接口）是定义在机器代码级别的，软件组件之间的交互接口。例如，在应用程序可执行文件和共享对象库的编译二进制文件之间的交互。ABI兼容性意味着软件库的新编译版本可以正确链接到目标可执行文件，而无需重新编译该可执行文件。

ABI兼容性对于某些语言非常重要，尤其是那些提供机器代码形式的语言。对于其他语言，ABI兼容性可能不是必要的。

In-band and Out-of-band Data

在电信技术中，带内信令是在同一频带或信道内发送控制信息，这些频带或信道用于诸如语音或视频之类的数据。这与通过不同的信道，甚至通过单独的网络（维基百科）发送的带外信号形成对比。

在OTel中，我们将带内数据看作业务消息的一部分，它是在分布式系统组件之间传递的数据。例如，当Trace或package以HTTP头的形式包含在HTTP请求中时，这些数据通常不包含遥测数据，而是用于关联和连接由各种组件生成的遥测数据。遥测本身是带外数据，它通过专用消息从应用程序传输，通常由后台程序异步传输，而不是从业务逻辑的关键路径传输。输出到遥测后端的metric、log和trace都是带外数据的实例。

Manual Instrumentation

针对OTel API（如Trace API、Metrics API）或其他从终端用户代码或共享框架（如MongoDB、Redis等）采集遥测数据的代码。

Automatic Instrumentation

就遥测采集方式而言，不要求最终用户通过编写/访问应用程序代码的方式使用OTel API。采集方式因编程语言而异，例如字节码注入或打修补等。

同义词：Auto-Instrumentation

Telemetry SDK

实现OTel API的库，请参见Library Guidelines和Library resource semantic conventions。

Constructors

Constructor是Application owner用来初始化和配置OTel SDK和contrib包的公共代码。Constructor的实例包括配置对象、环境变量和构造器。

SDK Plugins

插件是扩展OTel SDK的库，插件接口的例子有SpanProcessor、Exporter和Sampler接口。

Exporter Library

Exporters是SDK插件，它实现了Exporter接口，并向用户发送遥测信息。

Instrumented Library

收集遥测信号（Trace、Metric、Log）的库。

对OTel API的调用可以由Instrumented库本身发起，也可以由另一个Instrumentation库完成。

例子：org.mongodb.client客户端.

Instrumentation Library

给定Instrumented库提供instrumentation库。如果具有内置的OTel
instrumentation，则Instrumented和Instrumentation可以是同一个库。

有关更详细的定义和命名准则，请参见概述。

例子：io.opentelemetry.contrib.mongodb

同义词：Instrumenting Library.

Tracer Name / Meter Name

创建新Tracer或Meter时指定的名称和版本参数（可选），请参阅获取跟踪器/获取仪表。

名称/版本一起标识了一个Instrumentation库。

Logs

Log Record

事件的记录。通常，记录包括一个时间戳，指示事件发生的时间以及描述发生了什么、在哪里发生的等其他数据。

同义词：Log Entry

Log

有时指日志记录的集合。这里有点不太明确，因为有时大家也使用Log来代指单个日志记录，因此应谨慎使用该术语。在可能存在歧义的上下文中，应使用额外的限定符（例如，Log Record）。

Embedded Log

内嵌在Span对象的Event list里。

Standalone Log

区别于Embedded Log，未内嵌在Span对象里，记录在其他地方。

Log Attributes

Log Record中的键/值对。

Structured Logs

格式化日志，有良好的格式结构定义，可以区分日志记录的不同元素（例如时间戳、属性等）。例如，Syslog协议（RFC5425）定义了结构化数据格式。

Flat File Logs

记录在文本文件中的日志，通常每条日志记录是一行（也可能使用多行记录，即多行文本是一条完整日志记录）。对于以更加结构化的格式（例如JSON文件）写入文本文件的日志，是否被视为Flat File Logs，业界尚未达成一致的意见。如果这种区别很重要，建议具体阐述。