-`opentelemetry_0_13`: attach [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-rust)'s context to the root span using `opentelemetry` 0.13;
-`opentelemetry_0_14`: same as above but using `opentelemetry` 0.14;
-`opentelemetry_0_15`: same as above but using `opentelemetry` 0.15;
Check out [the examples on GitHub](https://github.com/LukeMathWalker/tracing-actix-web/tree/main/examples) to get a taste of how [`TracingLogger`] can be used to observe and monitor your
`tracing-actix-web`'s documentation provides a crash course in how to use [`tracing`] to instrument an `actix-web` application.
If you want to learn more check out ["Are we observable yet?"](https://www.lpalmieri.com/posts/2020-09-27-zero-to-production-4-are-we-observable-yet/) -
it provides an in-depth introduction to the crate and the problems it solves within the bigger picture of [observability](https://docs.honeycomb.io/learning-about-observability/).
# The root span
[`tracing::Span`] is the key abstraction in [`tracing`]: it represents a unit of work in your system.
A [`tracing::Span`] has a beginning and an end. It can include one or more **child spans** to represent sub-unit
of works within a larger task.
When your application receives a request, [`TracingLogger`] creates a new span - we call it the **[root span]**.
All the spans created _while_ processing the request will be children of the root span.
[`tracing`] empowers us to attach structured properties to a span as a collection of key-value pairs.
Those properties can then be queried in a variety of tools (e.g. ElasticSearch, Honeycomb, DataDog) to
understand what is happening in your system.
# Customisation via [`RootSpanBuilder`]
Troubleshooting becomes much easier when the root span has a _rich context_ - e.g. you can understand most of what
happened when processing the request just by looking at the properties attached to the corresponding root span.
You might have heard of this technique as the [canonical log line pattern](https://stripe.com/blog/canonical-log-lines),
popularised by Stripe. It is more recently discussed in terms of [high-cardinality events](https://www.honeycomb.io/blog/observability-a-manifesto/)
by Honeycomb and other vendors in the observability space.
[`TracingLogger`] gives you a chance to use the very same pattern: you can customise the properties attached
to the root span in order to capture the context relevant to your specific domain.
performs trace propagation according to the OpenTelemetry standard.
It tries to extract the OpenTelemetry context out of the headers of incoming requests and, when it finds one, it sets
it as the remote context for the current root span.
If you add [`tracing-opentelemetry::OpenTelemetryLayer`](https://docs.rs/tracing-opentelemetry/0.12.0/tracing_opentelemetry/struct.OpenTelemetryLayer.html)
in your `tracing::Subscriber` you will be able to export the root span (and all its children) as OpenTelemetry spans.
Check out the [relevant example in the GitHub repository](https://github.com/LukeMathWalker/tracing-actix-web/tree/main/examples/opentelemetry) for reference.
You can find an alternative integration of `actix-web` with OpenTelemetry in [`actix-web-opentelemetry`](https://github.com/OutThereLabs/actix-web-opentelemetry)
- parts of this project were heavily inspired by their implementation. They provide support for metrics
and instrumentation for the `awc` HTTP client, both out of scope for `tracing-actix-web`.
# License
Licensed under either of <ahref="LICENSE-APACHE">Apache License, Version 2.0</a> or <ahref="LICENSE-MIT">MIT license</a> at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in `tracing-actix-web` by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
