mirror of https://github.com/tokio-rs/tracing.git synced 2025-10-01 15:00:33 +00:00

History

core: change Span and Event metadata to be 'static (#110 )

## Motivation

Currently, the `span::Attributes` type in `tokio-trace-core` contains a
reference to `Metadata` with a generic lifetime `'a`. This means that if
a `Subscriber` wishes to store span metadata, it cannot simply store a
`&'static Metadata<'static>`. Instead, it must extract the individual
components from the metadata and store them in its own structure. In
addition, while the `name` and `FieldSet` in a `Metadata` are always
`'static`, the target and file path are not.  If the `Subscriber` needs
to store those values, they must be cloned into a `String` on the heap.

This is somewhat unergonomic for subscriber implementors, in comparison
to being able to use a `&'static Metadata<'static>` reference. In
addition, it implies additional overhead when using certain parts of a
span's metadata.

## Solution

This branch changes the `Metadata` fields in `Event` and `Attributes` to
be `'static`, and `Subscriber::register_callsite` to take an
`&'static Metadata<'static>`. Unlike PR #108, this branch leaves
`Metadata` generic over a lifetime, and `Subscriber::enabled` takes an
`&'a Metadata<'a>`.

Since subscribers are provided all span metadata as a static reference
in both `register_callsite` and `new_span`, they can clone _those_
static references, but `Subscriber::enabled` can still be called with
`Metadata` constructed from a `log::Record`. This means that log records
can still be filtered as normal. A different callsite, which does not
have metadata from the log record, is used when actually recording
events constructed from `log::Records`; in a follow-up, we can propagate
the log metadata as fields there.

Closes #78
Closes #108

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

2019-06-27 15:18:32 -07:00

src

core: change Span and Event metadata to be 'static (#110 )

2019-06-27 15:18:32 -07:00

tests

meta: rename everything to tracing (#99 )

2019-06-26 11:31:07 -07:00

Cargo.toml

meta: rename everything to tracing (#99 )

2019-06-26 11:31:07 -07:00

CHANGELOG.md

meta: rename everything to tracing (#99 )

2019-06-26 11:31:07 -07:00

LICENSE

meta: rename everything to tracing (#99 )

2019-06-26 11:31:07 -07:00

README.md

meta: rename everything to tracing (#99 )

2019-06-26 11:31:07 -07:00

README.md

tracing-core

Core primitives for tracing.

Documentation

Overview

tracing is a framework for instrumenting Rust programs to collect structured, event-based diagnostic information. This crate defines the core primitives of tracing.

The crate provides:

Span identifies a span within the execution of a program.
Event represents a single event within a trace.
Subscriber, the trait implemented to collect trace data.
Metadata and Callsite provide information describing Spans.
Field, FieldSet, Value, and ValueSet represent the structured data attached to a Span.
Dispatch allows span events to be dispatched to Subscribers.

In addition, it defines the global callsite registry and per-thread current dispatcher which other components of the tracing system rely on.

Application authors will typically not use this crate directly. Instead, they will use the tracing crate, which provides a much more fully-featured API. However, this crate's API will change very infrequently, so it may be used when dependencies must be very stable.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.