telemetry-subscribers

基于Tokio的应用程序遥测的通用工具，包括跟踪、日志和跨度

这是一个通用遥测功能库，特别是针对 Tokio 跟踪 库的订阅者。我们在这里简单地将许多常见的订阅者，如将跟踪数据写入Jaeger、分布式跟踪、常见的日志和指标目标等，打包成一个易于配置的通用包。还有一些独特的层，例如自动为跨度创建Prometheus延迟直方图的层。

我们还故意将日志级别与跨度创建分开。这对于生产应用程序来说通常是必需的，因为在正常情况下，不希望在高级别进行日志记录，但仍然希望收集到TRACE级别跨度数据的采样。

入门很容易。在您的应用程序中

  use telemetry_subscribers::TelemetryConfig;
  let (_guard, _handle) = TelemetryConfig::new("my_app").init();

保留守卫直到程序结束是很重要的。在main fn中分配它并保留它，因为一旦它掉落，则日志输出将停止。

有一个构建器API可用：只需执行 TelemetryConfig::new()... 另一种方便的初始化方法是 TelemetryConfig::new().with_env() 从环境变量中填充配置。

您还可以运行示例并查看ANSI颜色输出

cargo run --example easy-init

功能

• jaeger - 此功能默认启用，因为它启用了Jaeger跟踪
• json - Bunyan格式化器 - JSON日志输出，可选
• tokio-console - Tokio-console 订阅者，可选
• chrome - 启用使用 chrome://tracing 可视化输出，可选

标准输出与文件输出

默认情况下，日志（但不包括跨度）格式化为可读性高，输出到标准输出，并在每行末尾使用键值标签。可以通过配置 RUST_LOG 来自定义日志输出，包括过滤。

通过在配置中设置 log_file，可以将日志输出写入每日轮转文件。

跟踪和跨度输出

详细跨度开始和结束日志可以通过两种方式生成

• 通过定义配置变量 span_log_output 或环境变量 ENABLE_SPAN_LOGS。
• 通过定义配置变量 json_log_output 或环境变量 ENABLE_JSON_LOGS。请注意，这会导致输出为 JSON 格式，这不是那么易于阅读，因此默认情况下未启用。

JSON 输出可以轻松地馈送到诸如 ElasticSearch 等后端进行索引、警报、聚合和分析。它需要启用 json crate 功能。

Jaeger（查看分布式跟踪）

要使用 Jaeger 可视化嵌套跨度，请执行以下操作

1. 运行以下命令以获取本地 Jaeger 容器：docker run -d -p6831:6831/udp -p6832:6832/udp -p16686:16686 jaegertracing/allin-one:latest
2. 将 enable_jaeger 配置设置设为 true 或设置环境变量 TOKIO_JAEGER
3. 运行您的应用程序
4. 浏览到 https://127.0.0.1:16686/ 并选择您使用 service_name 配置的服务

注意：目前尚未将独立的跨度（不是嵌套的）连接为单个跟踪。

Jaeger 订阅者默认启用，但受 jaeger 功能标志的保护。如果您想省略 Jaeger 依赖项，可以在依赖项中关闭默认功能。

telemetry = { url = "...", default-features = false }

自动 Prometheus 跨度延迟

该库包含一个名为 PrometheusSpanLatencyLayer 的跟踪订阅者层。它将为您的应用程序中的每个跨度创建 Prometheus 直方图来跟踪延迟，这对于跟踪生产应用程序中跨度的性能非常有用。

只能通过编程方式启用此层，通过将 Prometheus 注册表传递给 TelemetryConfig。

跨度级别与日志级别

Jaeger 输出、自动跨度延迟等包括哪些跨度？这些由配置属性 span_level 或环境变量 TOKIO_SPAN_LEVEL 控制。请注意，这与 RUST_LOG 是分开的，因此您可以从记录和跟踪的跨度级别独立控制日志的详细程度。

请注意，常规日志输出的跨度级别不受跨度级别配置的影响。

实时异步检查/ Tokio Console

Tokio-console 是一款出色的 CLI 工具，用于分析并帮助调试使用 Tokio 的 Rust 应用程序，实时！它依赖于一个特殊的订阅者。

1. 使用特殊标志构建您的应用程序：RUSTFLAGS="--cfg tokio_unstable" cargo build
2. 为此crate启用tokio-console功能。
3. 在运行应用程序时设置tokio_console配置设置（或使用配置with_env()方法时设置TOKIO_CONSOLE环境变量）
4. 克隆控制台仓库并cargo run以启动控制台

注意：设置tokio TRACE日志不是必需的。文档中说要这样做，但实际上不需要更改Tokio的日志级别。控制台订阅者有一个特殊的过滤器已经处理了这个问题。

默认情况下，Tokio控制台监听端口6669。要更改此设置以及其他设置，如保留策略，请参阅配置指南。

自定义panic钩子

此库安装了一个自定义panic钩子，使用tracing crate记录一个ERROR级别的日志（事件）。这使得panic的span信息也可以正确记录。

要使panic时退出进程，设置环境变量CRASH_ON_PANIC。