tracing

use tracing::{span, Level};

let span = span!(Level::TRACE, "my span");
let _enter = span.enter();
// Any trace events that occur before the guard is dropped will occur
// within the span.  Dropping the guard will exit the span.

tracing::error_span!("myerrorspan", ?s);
tracing::error!(target: "myerrorspan", ?s, s.field_a, "just a debug message2");

use tracing::{Level, event, instrument};

#[instrument]
pub fn my_function(my_arg: usize) {
    // 这个 event 位于 my_function span 下，具有 my_arg field
    event!(Level::INFO, "inside my_function!");
    // ...
}

#[instrument(level="debug", target="this_crate::some_span", name="my_instrumented_span")]
async fn do_something_async() {
    // do some work
}

#[instrument(fields(http.uri = req.uri(), http.method = req.method()))]
pub fn handle_request<B>(req: http::Request<B>) -> http::Response<B> {
    // ... handle the request ...
}

// instrument 支持丰富的配置参数
impl Handler {
    #[instrument(
        name = "Handler::run",
        skip(self),
        fields(
            // `%` serializes the peer IP addr with `Display`
            peer_addr = %self.connection.peer_addr().unwrap()
        ),
    )]
    async fn run(&mut self) -> mini_redis::Result<()> {
        //...
    }
}

//! src/routes/subscriptions.rs
// [...]
#[tracing::instrument(
    name = "Adding a new subscriber",
    skip(form, pool),
    fields(
        request_id = %Uuid::new_v4(),
        subscriber_email = %form.email,
        subscriber_name= %form.name
    )
)]
pub async fn subscribe(form: web::Form<FormData>, pool: web::Data<PgPool>,) -> HttpResponse {
    match insert_subscriber(&pool, &form).await
    {
        Ok(_) => HttpResponse::Ok().finish(),
        Err(_) => HttpResponse::InternalServerError().finish()
    }
}

use tracing::info_span;
let json = info_span!("json.parse").in_scope(|| serde_json::from_slice(&buf))?;

use tracing::{event, Level};

// level 和 message, 字符串字面量默认为 message，故 message key 可以忽略。
event!(Level::INFO, "something has happened!");
// 等效为
event!(Level::INFO, message = "something has happened!")

event!(Level::INFO, key = "value") // 没有 message（为空）

// span 必选: Level 和 span name/id
let span = span!(Level::TRACE, "my span");

// event：Level 必选, message 可选
event!(Level::INFO, "something has happened!");
event!(Level::INFO);  // 没有 message

// event 可选：parent span
event!(parent: &span, Level::INFO, "something has happened!");

// event 可选：target
event!(target: "app_events", Level::INFO, "something has happened!");

// event 可选：name，默认为 file:line
event!(name: "some_info", Level::INFO, "something has happened!");

// 对于 span, 必须在 span name/id 后添加 field=value
tracing::error_span!("myerrorspan", ?s);
// tracing::error_span!(?s, "myerrorspan"); // 错误

// 对于 event, 分两种情况:
// 1. 如果有 message, 自定义 field 都必须位于 message 之前;
// 2. 如果没有 message, 则可以使用 field=value 形式来定义任意 field.
tracing::error!(target: "myerrorspan", ?s, s.field_a, "just a debug message2");
tracing::error!(target: "myerrorspan", ?s, s.field_a, a = "b");  // 没有 message

// 在 enter _span drop 前, 后续的 event 都自动关联该 span
let _span = tracing::error_span!("my_enter_span", ?s).entered();
tracing::error!(?s, s.field_a, a = "c");

let user = "ferris";
span!(Level::TRACE, "login", user);
// 等效于
span!(Level::TRACE, "login", user = user);

let user = "ferris";
let email = "[email protected]";
// field name 中间可以有 .
span!(Level::TRACE, "login", user, user.email = email);

let user = User { name: "ferris", email: "[email protected]", };
// span 具有两个 fields `user.name = "ferris"` 和 `user.email = "[email protected]"`.
span!(Level::TRACE, "login", user.name, user.email);

#[derive(Debug)]
struct MyStruct { field: &'static str, }
let my_struct = MyStruct { field: "Hello world!"};

// ？使用 Debug
event!(Level::TRACE, greeting = ?my_struct);
// 等效于
event!(Level::TRACE, greeting = tracing::field::debug(&my_struct));

// % 使用 Display
event!(Level::TRACE, greeting = %my_struct.field);
// 等效于
event!(Level::TRACE, greeting = tracing::field::display(&my_struct.field)

// ？和 % 也可以用在 key 名称前
event!(Level::TRACE, %my_struct.field);

use tracing::{trace_span, field};

// 创建一个 span, 具有两个 field，其中 greeting 具有值，而 parting
// 需要后续设置值
let span = trace_span!("my_span", greeting = "hello world", parting = field::Empty);

// 后续使用 span.record() 方法为 Empty field 指定具体的值
span.record("parting", &"goodbye world!");

let question = "the ultimate question of life, the universe, and everything";
let answer = 42;
event!(
    Level::DEBUG,
    question.answer = answer,
    question.tricky = true,
    "the answer to {} is {}.", question, answer  // message
);

[.. INFO zero2prod] Adding a new subscriber.; request_id=f349b0fe..
[email protected] subscriber_name=le guin
[.. TRACE zero2prod] -> Adding a new subscriber.
[.. INFO zero2prod] request_id f349b0fe.. - Saving new subscriber details
in the database
[.. INFO zero2prod] request_id f349b0fe.. - New subscriber details have
been saved
[.. TRACE zero2prod] <- Adding a new subscriber.
[.. TRACE zero2prod] -- Adding a new subscriber.
[.. INFO actix_web] .. "POST /subscriptions HTTP/1.1" 200 .

impl<'a> Metadata<'a>

pub const fn new(
    name: &'static str, // 缺省：file:line
    target: &'a str, // 缺省：module path
    level: Level,
    fields: FieldSet,
    kind: Kind， // 可选值为 EVENT，SPAN，HINT
    // 下面可选的 metadata 指定源码位置：
    file: Option<&'a str>,
    line: Option<u32>,
    module_path: Option<&'a str>,
) -> Metadata<'a>

use std::{error::Error, io};
use tracing::{debug, error, info, span, warn, Level};

#[tracing::instrument]
pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
    debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
    if yak == 3 {
        warn!("could not locate yak!");
        return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into());
    } else {
        debug!("yak shaved successfully");
    }
    Ok(())
}

pub fn shave_all(yaks: usize) -> usize {
    let _span = span!(Level::TRACE, "shaving_yaks", yaks).entered();

    info!("shaving yaks");

    let mut yaks_shaved = 0;
    for yak in 1..=yaks {
        let res = shave(yak);
        debug!(yak, shaved = res.is_ok());

        if let Err(ref error) = res {
            error!(yak, error = error.as_ref(), "failed to shave yak!");
        } else {
            yaks_shaved += 1;
        }
        debug!(yaks_shaved);
    }
    yaks_shaved
}

//! src/main.rs
//! [...]
use tracing::subscriber::set_global_default;
use tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer};

// path 是标识符，不支持短横杠，需要将 cargo package name 的短横杠转为下划线。
use tracing_subscriber::{layer::SubscriberExt, EnvFilter, Registry};
use tracing_log::LogTracer;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Redirect all `log`'s events to our subscriber
    LogTracer::init().expect("Failed to set logger");

    let env_filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new("info"));

    let formatting_layer = BunyanFormattingLayer::new(
        "zero2prod".into(),
        std::io::stdout
    );

    let subscriber = Registry::default()
        .with(env_filter)
        .with(JsonStorageLayer)
        .with(formatting_layer);

    set_global_default(subscriber).expect("Failed to set subscriber");
    // [...]
}

pub trait Subscriber: 'static {
    // Required methods
    fn enabled(&self, metadata: &Metadata<'_>) -> bool;
    fn new_span(&self, span: &Attributes<'_>) -> Id;
    fn record(&self, span: &Id, values: &Record<'_>);
    fn record_follows_from(&self, span: &Id, follows: &Id);
    fn event(&self, event: &Event<'_>);
    fn enter(&self, span: &Id);
    fn exit(&self, span: &Id);

    // Provided methods
    fn on_register_dispatch(&self, subscriber: &Dispatch) { ... }
    fn register_callsite(&self, metadata: &'static Metadata<'static> ) -> Interest { ... }
    fn max_level_hint(&self) -> Option<LevelFilter> { ... }
    fn event_enabled(&self, event: &Event<'_>) -> bool { ... }
    fn clone_span(&self, id: &Id) -> Id { ... }
    fn drop_span(&self, _id: Id) { ... }
    fn try_close(&self, id: Id) -> bool { ... }
    fn current_span(&self) -> Current { ... }
    unsafe fn downcast_raw(&self, id: TypeId) -> Option<*const ()> { ... }
}

// FooSubscriber 实现了 Subscriber
let my_subscriber = FooSubscriber::new();

// 全局 subscriber
tracing::subscriber::set_global_default(my_subscriber)
    .expect("setting tracing default failed");

// 局部闭包 Subscribe，可以按需创建多个 subscriber，分别来使用。
tracing::subscriber::with_default(my_subscriber, || {
    // 闭包内的 trace/event 将被 my_subscriber 记录
})

pub fn set_global_default<S>(subscriber: S) -> Result<(), SetGlobalDefaultError>
    where S: Subscriber + Send + Sync + 'static,
{
    crate::dispatcher::set_global_default(crate::Dispatch::new(subscriber))
}

pub struct Dispatch { /* private fields */ }
// 从 Subscriber 实现来创建 Dispatch
pub fn new<S>(subscriber: S) -> Dispatch where S: Subscriber + Send + Sync + 'static,

// 创建一个 dispatch
use dispatcher::Dispatch;
let my_subscriber = FooSubscriber::new();
let my_dispatch = Dispatch::new(my_subscriber);

// 使用方式 1: 为闭包函数设置缺省 Subscribe
dispatcher::with_default(&my_dispatch, || {
    // my_subscriber is the default
});

// 使用方式 2: 为全局所有线程设置缺省 Subscribe
dispatcher::set_global_default(my_dispatch)
    .expect("global default was already set!");
// `my_subscriber` is now the default

// 使用方式 3: 为当前线程设置缺省 Subscribe
dispatcher::set_default(my_dispatch)
    .expect("default was already set!");

// tracing-subscriber::fmt::Subscriber 类型实现了 tracing::Subscriber trait
pub struct Subscriber<N = DefaultFields, E = Format<Full>, F = LevelFilter,
    W = fn() -> Stdout> { /* private fields */ }

impl Subscriber {
    // ...
    pub fn new() -> Self {
        Default::default()
    }
}
impl Default for Subscriber {
    fn default() -> Self {
        SubscriberBuilder::default().finish()
    }
}

pub const DEFAULT_MAX_LEVEL: LevelFilter = LevelFilter::INFO;
pub struct SubscriberBuilder<
    N = format::DefaultFields,
    E = format::Format<format::Full>,
    F = LevelFilter,
    W = fn() -> io::Stdout,
    > {
        filter: F,
        inner: Layer<Registry, N, E, W>,
    }

impl Default for SubscriberBuilder {
    fn default() -> Self {
        SubscriberBuilder {
            filter: Subscriber::DEFAULT_MAX_LEVEL, // INFO
            inner: Default::default(),
        }
            .log_internal_errors(true)
    }
}

// 示例
use tracing_subscriber;

#[tokio::main]
pub async fn main() -> mini_redis::Result<()> {
    // 创建缺省的 fmt::Subscriber
    let subscriber = tracing_subscriber::FmtSubscriber::new();
    // 设置为全局 subscriber
    tracing::subscriber::set_global_default(subscriber)?;

    // 也可以调用 fmt::init() 一步完成。
    // tracing_subscriber::fmt::init();

    //...
}

//  对 tracing_subscriber::fmt::SubscriberBuilder 进行更精细化的配置
let subscriber = tracing_subscriber::fmt()
    // Use a more compact, abbreviated log format
    .compact()
    // Display source code file paths
    .with_file(true)
    // Display source code line numbers
    .with_line_number(true)
    // Display the thread ID an event was recorded on
    .with_thread_ids(true)
    // Don't display the event's target (module path)
    .with_target(false)
    .with_ansi(true)
    // 通过环境变量字符串设置过滤规则
    .with_env_filter("tracing=trace,tokio=trace,runtime=trace")
    // 自定义最低日志输出级别
    .with_max_level(Level::DEBUG)
    //.pretty()
    .finish(); // 返回 tracing_subscriber::fmt::Subscriber 对象;

// 设置为全局 sbuscriber
tracing::subscriber::set_global_default(subscriber).unwrap();

let subscriber = tracing_subscriber::fmt()
    // ... add configuration
    .init() // 内部调用 builder.finish() 然后设置为 global Subscriber

pub fn format() -> Format

// Struct tracing_subscriber::fmt::format::Format 定义:
pub struct Format<F = Full, T = SystemTime> { /* private fields */ }

// 创建一个自定义输出格式
let format = tracing_subscriber::fmt::format()
    .without_time()         // Don't include timestamps
    .with_target(false)     // Don't include event targets.
    .with_level(false)      // Don't include event levels.
    .compact();             // Use a more compact, abbreviated format.

// 使用自定义输出格式
tracing_subscriber::fmt::fmt()
    .event_format(format)
    .init();

  // 自定义 Fmt Layer 和 EnvFilter Layer，然后用它们创建一个 Registery
  use tracing_subscriber::{fmt, EnvFilter};
  use tracing_subscriber::prelude::*;

  let fmt_layer = fmt::layer() // 自定义 Layer 对象配置
      .with_target(false) // don't include event targets when logging
      .with_level(false) // don't include event levels when logging
      .with_writer(io::stderr); // 将事件写到 stdout
      .event_format(fmt);

  let filter_layer = EnvFilter::try_from_default_env()
      .or_else(|_| EnvFilter::try_new("info"))
      .unwrap();

  let subscriber = tracing_subscriber::registry() // 等效于 Registry::default()
      .with(filter_layer)
      .with(fmt_layer)
      .init();

  //  Registry::default() 的 Registry 是空的，需要使用 with() 来关联至少一个 Layer
  let subscriber = Registry::default()
      .with(fmt::Layer::default());

use tracing_subscriber::{fmt, Registry};
use tracing_subscriber::fmt::{self, format, time};
use tracing_subscriber::prelude::*;

// fmt::Layer::default() 等效于 fmt::layer()
Registry::default().with(fmt::Layer::default()).init()

// 使用 EnvFilter layer
use tracing_subscriber::{EnvFilter, fmt, prelude::*};
tracing_subscriber::registry()
    .with(fmt::layer())
    // 从缺省的 RUST_LOG env 中读取 LOG 配置
    .with(EnvFilter::from_default_env())
    .init();

tracing_subscriber::registry()
    .with(fmt::layer())
    // 从指定的 MYAPP_LOG env 中读取 LOG 配置
    .with(EnvFilter::from_env("MYAPP_LOG"))
    .init();

// 写文件：file_appender 实现了 std::io::Write
let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
tracing_subscriber::fmt()
    .with_writer(file_appender)
    .init();

// Non-Blocking Writer
// 1. 写 stdout
let (non_blocking, _guard) = tracing_appender::non_blocking(std::io::stdout());
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

// 2. 自定义 writer
use std::io::Error;
struct TestWriter;
impl std::io::Write for TestWriter {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        let buf_len = buf.len();
        println!("{:?}", buf);
        Ok(buf_len)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}
let (non_blocking, _guard) = tracing_appender::non_blocking(TestWriter);
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

// Non-Blocking Rolling File Appender
let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log");
let (non_blocking, _guard) = tracing_appender::non_blocking(file_appender);
tracing_subscriber::fmt()
    .with_writer(non_blocking)
    .init();

use tracing_opentelemetry::OpenTelemetryLayer;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::Registry;
use opentelemetry_sdk::trace::TracerProvider;
use opentelemetry::trace::{Tracer, TracerProvider as _};
use tracing::{error, span};

// 1. 使用 jaeger exporter pipeline 创建一个名为 "trace_demo" 的 service
// Create a jaeger exporter pipeline for a `trace_demo` service.
let tracer = opentelemetry_jaeger::new_agent_pipeline()
    .with_service_name("trace_demo")
    .install_simple()
    .expect("Error initializing Jaeger exporter");
// 2. 或者使用 TracerProvider 创建一个 readme_example 的 service
// Create a new OpenTelemetry trace pipeline that prints to stdout
let provider = TracerProvider::builder()
    .with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
    .build();
let tracer = provider.tracer("readme_example");

// Create a layer with the configured tracer
let otel_layer = OpenTelemetryLayer::new(tracer);
// 或者:
// let otel_layer = tracing_opentelemetry::layer().with_tracer(tracer);

// Use the tracing subscriber `Registry`, or any other subscriber
// that impls `LookupSpan`
let subscriber = Registry::default().with(otel_layer);

// Trace executed code
tracing::subscriber::with_default(subscriber, || {
    // Spans will be sent to the configured OpenTelemetry exporter
    let root = span!(tracing::Level::TRACE, "app_start", work_units = 2);
    let _enter = root.enter();

    error!("This event will be logged in the root span.");
});

pub struct Context { /* private fields */ }

impl Context
pub fn new() -> Self
pub fn current() -> Self
    use opentelemetry::Context;
    #[derive(Debug, PartialEq)]
    struct ValueA(&'static str);
    fn do_work() {
        assert_eq!(Context::current().get(), Some(&ValueA("a")));
    }
    let _guard = Context::new().with_value(ValueA("a")).attach();
    do_work()

pub fn map_current<T>(f: impl FnOnce(&Context) -> T) -> T

pub fn current_with_value<T: 'static + Send + Sync>(value: T) -> Self
    use opentelemetry::Context;

    // Given some value types defined in your application
    #[derive(Debug, PartialEq)]
    struct ValueA(&'static str);
    #[derive(Debug, PartialEq)]
    struct ValueB(u64);

    // You can create and attach context with the first value set to "a"
    let _guard = Context::new().with_value(ValueA("a")).attach();

    // And create another context based on the fist with a new value
    let all_current_and_b = Context::current_with_value(ValueB(42));

    // The second context now contains all the current values and the addition
    assert_eq!(all_current_and_b.get::<ValueA>(), Some(&ValueA("a")));
    assert_eq!(all_current_and_b.get::<ValueB>(), Some(&ValueB(42)));

pub fn get<T: 'static>(&self) -> Option<&T>
    use opentelemetry::Context;
    // Given some value types defined in your application
    #[derive(Debug, PartialEq)]
    struct ValueA(&'static str);
    #[derive(Debug, PartialEq)]
    struct MyUser();

    let cx = Context::new().with_value(ValueA("a"));

    // Values can be queried by type
    assert_eq!(cx.get::<ValueA>(), Some(&ValueA("a")));

    // And return none if not yet set
    assert_eq!(cx.get::<MyUser>(), None);

pub fn with_value<T: 'static + Send + Sync>(&self, value: T) -> Self
    use opentelemetry::Context;

    // Given some value types defined in your application
    #[derive(Debug, PartialEq)]
    struct ValueA(&'static str);
    #[derive(Debug, PartialEq)]
    struct ValueB(u64);

    // You can create a context with the first value set to "a"
    let cx_with_a = Context::new().with_value(ValueA("a"));

    // And create another context based on the fist with a new value
    let cx_with_a_and_b = cx_with_a.with_value(ValueB(42));

    // The first context is still available and unmodified
    assert_eq!(cx_with_a.get::<ValueA>(), Some(&ValueA("a")));
    assert_eq!(cx_with_a.get::<ValueB>(), None);

    // The second context now contains both values
    assert_eq!(cx_with_a_and_b.get::<ValueA>(), Some(&ValueA("a")));
    assert_eq!(cx_with_a_and_b.get::<ValueB>(), Some(&ValueB(42)));

pub fn attach(self) -> ContextGuard
    use opentelemetry::Context;

    #[derive(Debug, PartialEq)]
    struct ValueA(&'static str);

    let my_cx = Context::new().with_value(ValueA("a"));

    // Set the current thread context
    let cx_guard = my_cx.attach();
    assert_eq!(Context::current().get::<ValueA>(), Some(&ValueA("a")));

    // Drop the guard to restore the previous context
    drop(cx_guard);
    assert_eq!(Context::current().get::<ValueA>(), None);

use opentelemetry::Context;

// Application-specific `a` and `b` values
#[derive(Debug, PartialEq)]
struct ValueA(&'static str);

#[derive(Debug, PartialEq)]
struct ValueB(u64);

// 创建一个 context，并设置为 current context
let _outer_guard = Context::new().with_value(ValueA("a")).attach();

// Only value a has been set
let current = Context::current();
assert_eq!(current.get::<ValueA>(), Some(&ValueA("a")));
assert_eq!(current.get::<ValueB>(), None);

{
    // 创建一个子 Context，并设置为 current context
    let _inner_guard = Context::current_with_value(ValueB(42)).attach();

    // Both values are set in inner context
    let current = Context::current();
    assert_eq!(current.get::<ValueA>(), Some(&ValueA("a")));
    assert_eq!(current.get::<ValueB>(), Some(&ValueB(42)));
} // block 结束后，_inner_guard 被 drop，current context 恢复为 _outer_guard 对应的 Context

// Resets to only the `a` value when inner guard is dropped
let current = Context::current();
assert_eq!(current.get::<ValueA>(), Some(&ValueA("a")));
assert_eq!(current.get::<ValueB>(), None);

pub trait TraceContextExt {
    // Required methods
    fn current_with_span<T: Span + Send + Sync + 'static>(span: T) -> Self;

        use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context};

        let tracer = global::tracer("example");
        // build a span
        let span = tracer.start("parent_span");

        // create a new context from the currently active context that includes this span
        let cx = Context::current_with_span(span);

        // create a child span by explicitly specifying the parent context
        let child = tracer.start_with_context("child_span", &cx);

    fn with_span<T: Span + Send + Sync + 'static>(&self, span: T) -> Self;

        use opentelemetry::{global, trace::{TraceContextExt, Tracer}, Context};

        fn fn_with_passed_in_context(cx: &Context) {
            let tracer = global::tracer("example");

            // build a span
            let span = tracer.start("parent_span");

            // create a new context from the given context that includes the span
            let cx_with_parent = cx.with_span(span);

            // create a child span by explicitly specifying the parent context
            let child = tracer.start_with_context("child_span", &cx_with_parent);
        }

    fn span(&self) -> SpanRef<'_>;

        use opentelemetry::{trace::TraceContextExt, Context};

        // Add an event to the currently active span
        Context::map_current(|cx| cx.span().add_event("An event!", vec![]));

    fn has_active_span(&self) -> bool;

        use opentelemetry::{trace::TraceContextExt, Context};
        assert!(!Context::map_current(|cx| cx.has_active_span()));

    fn with_remote_span_context(&self, span_context: SpanContext) -> Self;
}
impl TraceContextExt for Context

pub trait Span {
    // Required methods
    fn add_event_with_timestamp<T>(&mut self, name: T, timestamp: SystemTime, attributes: Vec<KeyValue>, ) where T: Into<Cow<'static, str>>;
    fn span_context(&self) -> &SpanContext;
    fn is_recording(&self) -> bool;
    fn set_attribute(&mut self, attribute: KeyValue);
    fn set_status(&mut self, status: Status);
    fn update_name<T>(&mut self, new_name: T) where T: Into<Cow<'static, str>>;
    fn add_link(&mut self, span_context: SpanContext, attributes: Vec<KeyValue>);
    fn end_with_timestamp(&mut self, timestamp: SystemTime);

    // Provided methods
    fn add_event<T>(&mut self, name: T, attributes: Vec<KeyValue>) where T: Into<Cow<'static, str>> { ... }
    fn record_error(&mut self, err: &dyn Error) { ... }
    fn set_attributes(&mut self, attributes: impl IntoIterator<Item = KeyValue>) { ... }
    fn end(&mut self) { ... }
}

// Get a tracer
let tracer = global::tracer("my_tracer");

// Create a span，父 span 为 active span 或空。
let span = tracer.start("parent_span");

span.set_status(Status::error("value too small"));
span.add_event("An event!", vec![KeyValue::new("happened", true)]);

use opentelemetry::{global, trace::{self, Span, Status, Tracer, TracerProvider}};

fn may_error(rand: f32) {
    if rand < 0.5 {
        // Get the currently active span to record additional attributes, status, etc.
        trace::get_active_span(|span| {
            span.set_status(Status::error("value too small"));
            span.add_event("An event!", vec![KeyValue::new("happened", true)]);
        });
    }
}

// Get a tracer
let tracer = global::tracer("my_tracer");

// Create a span, 当前 active span 为空。
let span = tracer.start("parent_span");

// Mark the span as active
let active = trace::mark_span_as_active(span);

// Any span created here will be a child of `parent_span`...

// Drop the guard and the span will no longer be active
drop(active)

use opentelemetry::{global, trace::{Span, Tracer}, KeyValue};
use opentelemetry::trace::get_active_span;

fn my_function() {
    // start an active span in one function
    global::tracer("my-component").in_span("span-name", |_cx| {

        // in_span() 方法自动将创建的 子 span 作为闭包函数的 active span

        // anything happening in functions we call can still access the active span...
        my_other_function();
    })
}

fn my_other_function() {
    // call methods on the current span from
    get_active_span(|span| {
        span.add_event("An event!", vec![KeyValue::new("happened", true)]);
    })
}

#[non_exhaustive]
pub struct Event {
    pub name: Cow<'static, str>,
    pub timestamp: SystemTime,
    pub attributes: Vec<KeyValue>,
    pub dropped_attributes_count: u32,
}