mick-jaeger

用于向 Jaeger 服务器发送跟踪信息的 Rust 客户端。

所有文档都在 crate 根目录。请参阅 docs.rs。

lib.rs:

Jaeger 客户端。

概述

为了使用此 crate，您必须熟悉 span 的概念。

span 覆盖一定的时间段，通常是操作开始到结束。换句话说，您通常在函数或块的开始处启动 span，并在函数/块的结束处结束它。

此 crate 的目的是让您轻松记录 span 并将其发送到 Jaeger 服务器，Jaeger 服务器将汇总它们并允许您可视化它们。

每个 span 都属于一个 trace。trace 通过一个 128 位的标识符来识别。Jaeger 允许您轻松地可视化属于同一 trace 的所有 span，即使它们来自不同的客户端。

例如，想象一个 HTTP 前端服务器接收一个 HTTP 请求。它可以为此请求生成一个新的 trace id，然后将此标识符传递给处理此请求部分的其他外部进程。这些外部进程，所有都与同一个 Jaeger 服务器连接，可以报告与该请求对应的 span。

最简单的方法是通过 Docker 启动 Jaeger 服务器进行快速实验

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
  -p 5775:5775/udp \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 14250:14250 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.20

另请参阅 官方文档。

用法：初始化

首先，调用 init 以分配所有必要的对象。

这返回一个 TracesIn 和 TracesOut 的组合。将它们视为发送者和接收者。将完成的 span 发送到 TracesOut 使用 TracesIn。

将跟踪信息发送到服务器不属于本库的功能。必须使用 TracesOut 进行轮询，使用 TracesOut::next，并通过 UDP 发送到 Jaeger 服务器。

let (traces_in, mut traces_out) = mick_jaeger::init(mick_jaeger::Config {
    service_name: "demo".to_string(),
});

let udp_socket = async_std::net::UdpSocket::bind("0.0.0.0:0").await.unwrap();
udp_socket.connect("127.0.0.1:6831").await.unwrap();

async_std::task::spawn(async move {
    loop {
        let buf = traces_out.next().await;
        udp_socket.send(&buf).await.unwrap();
    }
});

如果 TracesOut::next 调用不够频繁，换句话说，如果后台任务太慢，那么通过 TracesIn 发送的跨度将被自动且无声地丢弃。在正常情况下，不应该发生这种情况。

用法：跨度

使用 TracesIn::span 方法创建跨度。

使用本库的基本方法是使用 TracesIn::span。这将创建一个 Span 对象，当它被销毁时，将发送一个目标为 TracesOut 的报告。

注意：只要 Span 存活，它就不会在 Jaeger 服务器上可见。建议创建短生命周期的跨度以及长生命周期的跟踪 ID。

let _span = traces_in.span(NonZeroU128::new(43).unwrap(), "something");

// do something

// The span is reported when it is destroyed at the end of the scope.

注意：不要将您的跨度命名为 _，否则它们将立即被销毁！

添加标签到跨度是可能的，也是推荐的。

let mut _span = traces_in.span(NonZeroU128::new(43).unwrap(), "something");
_span.add_string_tag("key", "value");

跨度可以有子跨度

fn my_function(traces_in: &std::sync::Arc<mick_jaeger::TracesIn>) {
    let mut _span = traces_in.span(NonZeroU128::new(43).unwrap(), "foo");

    // do something

    {
        let mut _span = _span.child("bar");
        // something expensive
    }
}

如果事件发生在特定的时间点而不是一段时间内，也可以添加日志。

let mut _span = traces_in.span(NonZeroU128::new(43).unwrap(), "something");
_span.log().with_string("key", "value");

与其他 crate 的区别

尽管存在其他 crate 允许您与 Jaeger 进行接口，但根据 mick_jaeger 的作者，它们都过于复杂。一些是损耗性抽象：试图使其易于使用，它们隐藏了重要细节（如跟踪 ID），这比它帮助的要多。

mick_jaeger 尝试保持简单。它不处理发送到服务器的事实消除了很多关于网络库和线程的偏执性决定。

mick_jaeger 理论上可以是 no_std-兼容的（经过一些调整后），但无法实现，因为在编写本文档时没有无 std 兼容的 thrift 协议库。