参考应用规范 | OpenTelemetry

参考应用规范

参考应用的目的是提供一个标准化的示例应用，该应用可以使用所有已提供 OpenTelemetry SDK 的编程语言来实现。 - 参考应用的实现由各编程语言的 SIG（负责实现 OpenTelemetry API 和 SDK 的小组）维护。这可以确保应用遵循该语言生态系统中的最佳实践，并为应用如何进行插桩提供一份蓝图。 - 应用必须同时提供未插桩版本和已插桩版本。这将用于...

参考应用的目的是提供一个标准化的示例应用，该应用可以使用所有已提供
OpenTelemetry SDK 的编程语言来实现。

通用要求 {#general-requirements}

参考应用的实现由各编程语言的 SIG（负责实现 OpenTelemetry API 和 SDK 的小组）维护。
这可以确保应用遵循该语言生态系统中的最佳实践，并为应用如何进行插桩提供一份蓝图。
应用必须同时提供未插桩版本和已插桩版本。
这将用于 opentelemetry.io 上的快速入门指南，展示如何将一个未使用
OpenTelemetry 的应用逐步演进为一个完全插桩的应用。
必须有语言相关的 CI 流水线，用于验证应用在两种版本下都可以成功构建并运行。
应用必须可以通过命令行接口运行。
必须提供一个 Dockerfile，用于在容器化环境中运行该应用。
应用必须能够独立运行。换句话说，它不能对其所在仓库中的其他内容存在硬依赖。
这样用户就可以将代码直接拷贝到自己的项目中，而无需处理复杂的依赖关系。

服务要求 {#service-requirements}

应用默认必须监听 8080 端口来接收 HTTP 请求。
端口应可通过环境变量 APPLICATION_PORT 进行配置。
在处理 HTTP 请求时，应使用一个已有插桩库的 HTTP 框架或库。
应用必须通过 GET（可选支持 POST）方式提供
/rolldice?rolls=<n> 接口，并返回如下 HTTP 状态码和 JSON 结果：
- 如果未设置 rolls，或其值为有效输入（大于 0 的正整数）：
  返回状态码 200；
  - 若 rolls 未设置或值为 1，返回一个介于 1 到 6 之间的单个数字
  - 若 rolls 为 n，返回一个包含 n 个介于 1 到 6 之间数字的数组
- 如果 rolls 为无效输入（非数字）：返回状态码 400，并返回
  {"status": "error", "message": "Parameter rolls must be a positive integer"}
- 如果 rolls 为 0 或负整数：
  返回状态码 500，且不返回 JSON 内容。
  这些错误示例将用于演示如何使用 OpenTelemetry 来定位错误。
/rolldice 接口可以支持一个可选参数 player=name。
应用必须输出以下日志：
- 对于状态码 <400 的每个 HTTP 请求，输出一条 INFO 级别日志
- 对于状态码在 400 到 499 之间的每个 HTTP 请求，
  输出一条 WARN 级别日志，并包含将返回在 JSON 中的错误信息
- 对于状态码大于 499 的每个 HTTP 请求，输出一条 ERROR 级别日志
- 如果设置了可选的 player 参数，
  输出一条 DEBUG 级别日志，包含 player 的值和掷骰子的结果
- 如果未设置 player 参数，
  输出一条 DEBUG 级别日志，包含固定值 anonymous player
  和掷骰子的结果数字。这些日志将用于在插桩时添加日志桥接，
  以展示 OpenTelemetry 如何与现有日志框架集成。
应用代码必须拆分为两个文件：
- app 文件：包含 HTTP 请求处理逻辑
- library 文件：包含掷骰子逻辑的实现。
  文件名应符合对应语言的习惯用法，例如 app.js、roll-the-dice.js。
  关键在于通过这种拆分，体现 library 仅依赖 OpenTelemetry API，
  而所有 SDK 的初始化都在 app 中完成。
针对 rolls 参数的错误处理需按如下方式拆分：
- app 负责检查 rolls 是否定义，若未定义则将其设为 1
- app 只检查 rolls 是否为数字：
  - 若是数字，则调用 library 中的掷骰子函数
  - 若不是数字，则直接返回 400 错误
- library 负责检查 rolls 是否为正数：
  - 若不是正数，则抛出异常
  - app 捕获该异常并返回 500 错误
library 应包含一个外层函数，用于按上述逻辑进行错误处理。
外层函数根据 rolls 的值执行以下操作：
- rolls == 1：调用一次内层函数并返回结果
- rolls > 1：循环调用内层函数 rolls 次，并将结果以数组形式返回
library 的内层函数用于生成并返回一个介于 1 到 6 之间的随机数。

插桩要求 {#instrumentation-requirements}

如果可能，OpenTelemetry SDK 的初始化应放在单独的文件中，
并在 app 文件中引入；否则可以直接放在 app 文件中。
初始化时应加载常见的资源探测器，例如 process、container、os 等。
"lib" 文件必须仅依赖 OpenTelemetry API。
service.* 相关属性应通过环境变量配置
（OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES）。
其他资源探测器也应在 SDK 初始化时启用。
遥测数据导出应同时支持 stdout/console 和 otlp 导出器。
应提供启用 OpenTelemetry 组件诊断日志的方式，
理想情况下通过 OTEL_LOG_LEVEL 配置。
应提供一种方式，为所使用的 HTTP 库添加对应的插桩库。
该插桩库应使用稳定版的 HTTP 语义约定，
优先选择同时支持多种信号（理想情况下同时支持链路和指标）的库。
仅在没有可用的 HTTP 插桩库时，
才由用户在 app 中对处理 /rolldice 的函数手动添加 span 和指标。
应为所使用的日志框架提供日志桥接，
使所有日志都能被自动采集并导出。
在 library 中应为外层函数创建一个 span：
- 该 span 用于跟踪函数执行时间
- 若抛出异常，则记录异常
- 为 span 添加诸如 rolls、code.* 等属性
在 library 中应为内层函数创建一个 span：
- 该 span 用于跟踪函数执行时间
- 将生成的随机数作为属性添加到 span 中
在 library 文件中需要创建以下指标：
- 一个计数器，用于统计外层函数的调用次数
- 一个直方图，用于统计掷骰子结果（1–6）的分布
- 一个仪表，用于记录最近一次 rolls 的值

参考应用规范

通用要求 {#general-requirements}

参考应用的实现由各编程语言的 SIG（负责实现 OpenTelemetry API 和 SDK 的小组）维护。
这可以确保应用遵循该语言生态系统中的最佳实践，并为应用如何进行插桩提供一份蓝图。

应用必须同时提供未插桩版本和已插桩版本。
这将用于 opentelemetry.io 上的快速入门指南，展示如何将一个未使用
OpenTelemetry 的应用逐步演进为一个完全插桩的应用。

必须有语言相关的 CI 流水线，用于验证应用在两种版本下都可以成功构建并运行。

应用必须可以通过命令行接口运行。

必须提供一个 Dockerfile，用于在容器化环境中运行该应用。

应用必须能够独立运行。换句话说，它不能对其所在仓库中的其他内容存在硬依赖。
这样用户就可以将代码直接拷贝到自己的项目中，而无需处理复杂的依赖关系。

服务要求 {#service-requirements}

应用默认必须监听 8080 端口来接收 HTTP 请求。
端口应可通过环境变量 APPLICATION_PORT 进行配置。

在处理 HTTP 请求时，应使用一个已有插桩库的 HTTP 框架或库。
应用必须通过 GET（可选支持 POST）方式提供
/rolldice?rolls=<n> 接口，并返回如下 HTTP 状态码和 JSON 结果：

如果未设置 rolls，或其值为有效输入（大于 0 的正整数）：
返回状态码 200；
- 若 rolls 未设置或值为 1，返回一个介于 1 到 6 之间的单个数字
- 若 rolls 为 n，返回一个包含 n 个介于 1 到 6 之间数字的数组
如果 rolls 为无效输入（非数字）：返回状态码 400，并返回
{"status": "error", "message": "Parameter rolls must be a positive integer"}
如果 rolls 为 0 或负整数：
返回状态码 500，且不返回 JSON 内容。
这些错误示例将用于演示如何使用 OpenTelemetry 来定位错误。

/rolldice 接口可以支持一个可选参数 player=name。

应用必须输出以下日志：

对于状态码 <400 的每个 HTTP 请求，输出一条 INFO 级别日志
对于状态码在 400 到 499 之间的每个 HTTP 请求，
输出一条 WARN 级别日志，并包含将返回在 JSON 中的错误信息
对于状态码大于 499 的每个 HTTP 请求，输出一条 ERROR 级别日志
如果设置了可选的 player 参数，
输出一条 DEBUG 级别日志，包含 player 的值和掷骰子的结果
如果未设置 player 参数，
输出一条 DEBUG 级别日志，包含固定值 anonymous player
和掷骰子的结果数字。这些日志将用于在插桩时添加日志桥接，
以展示 OpenTelemetry 如何与现有日志框架集成。

应用代码必须拆分为两个文件：

app 文件：包含 HTTP 请求处理逻辑
library 文件：包含掷骰子逻辑的实现。
文件名应符合对应语言的习惯用法，例如 app.js、roll-the-dice.js。
关键在于通过这种拆分，体现 library 仅依赖 OpenTelemetry API，
而所有 SDK 的初始化都在 app 中完成。

针对 rolls 参数的错误处理需按如下方式拆分：

app 负责检查 rolls 是否定义，若未定义则将其设为 1
app 只检查 rolls 是否为数字：
- 若是数字，则调用 library 中的掷骰子函数
- 若不是数字，则直接返回 400 错误
library 负责检查 rolls 是否为正数：
- 若不是正数，则抛出异常
- app 捕获该异常并返回 500 错误

library 应包含一个外层函数，用于按上述逻辑进行错误处理。
外层函数根据 rolls 的值执行以下操作：

rolls == 1：调用一次内层函数并返回结果
rolls > 1：循环调用内层函数 rolls 次，并将结果以数组形式返回

library 的内层函数用于生成并返回一个介于 1 到 6 之间的随机数。

插桩要求 {#instrumentation-requirements}

如果可能，OpenTelemetry SDK 的初始化应放在单独的文件中，
并在 app 文件中引入；否则可以直接放在 app 文件中。

初始化时应加载常见的资源探测器，例如 process、container、os 等。

"lib" 文件必须仅依赖 OpenTelemetry API。

service.* 相关属性应通过环境变量配置
（OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES）。

其他资源探测器也应在 SDK 初始化时启用。

遥测数据导出应同时支持 stdout/console 和 otlp 导出器。

应提供启用 OpenTelemetry 组件诊断日志的方式，
理想情况下通过 OTEL_LOG_LEVEL 配置。

应提供一种方式，为所使用的 HTTP 库添加对应的插桩库。
该插桩库应使用稳定版的 HTTP 语义约定，
优先选择同时支持多种信号（理想情况下同时支持链路和指标）的库。

仅在没有可用的 HTTP 插桩库时，
才由用户在 app 中对处理 /rolldice 的函数手动添加 span 和指标。

应为所使用的日志框架提供日志桥接，
使所有日志都能被自动采集并导出。

在 library 中应为外层函数创建一个 span：

该 span 用于跟踪函数执行时间
若抛出异常，则记录异常
为 span 添加诸如 rolls、code.* 等属性

在 library 中应为内层函数创建一个 span：

该 span 用于跟踪函数执行时间
将生成的随机数作为属性添加到 span 中

在 library 文件中需要创建以下指标：

一个计数器，用于统计外层函数的调用次数
一个直方图，用于统计掷骰子结果（1–6）的分布
一个仪表，用于记录最近一次 rolls 的值