Warning: In asynchronous code that uses async/await syntax,Span::enter may produce incorrect traces if the returned dropguard is held across an await point. Seethe method documentation for details.
An Event represents a moment in time. It signifies something thathappened while a trace was being recorded. Events are comparable to the logrecords emitted by unstructured logging code, but unlike a typical log line,an Event may occur within the context of a span.
As Spans and Events occur, they are recorded or aggregated byimplementations of the Subscriber trait. Subscribers are notifiedwhen an Event takes place and when a Span is entered or exited. Thesenotifications are represented by the following Subscriber trait methods:
In addition, subscribers may implement the enabled function to filterthe notifications they receive based on metadata describing each Spanor Event. If a call to Subscriber::enabled returns false for a givenset of metadata, that Subscriber will not be notified about thecorresponding Span or Event. For performance reasons, if no currentlyactive subscribers express interest in a given set of metadata by returningtrue, then the corresponding Span or Event will never be constructed.
The span! macro expands to a Span struct which is used torecord a span. The Span::enter method on that struct records that thespan has been entered, and returns a RAII guard object, which will exitthe span when dropped.
Both macros require a Level specifying the verbosity of the span orevent. Optionally, the, target and parent span may be overridden. If thetarget and parent span are not overridden, they will default to themodule path where the macro was invoked and the current span (as determinedby the subscriber), respectively.
The span macros also take a string literal after the level, to set the nameof the span (as above). In the case of the event macros, the name of the event canbe overridden (the default is event file:line) using the name: specifier.
Fields with names that are not Rust identifiers, or with names that are Rust reserved words,may be created using quoted string literals. However, this may not be used with the localvariable shorthand.
Users of the log crate should note that tracing exposes a set ofmacros for creating Events (trace!, debug!, info!, warn!, anderror!) which may be invoked with the same syntax as the similarly-namedmacros from the log crate. Often, the process of converting a project touse tracing can begin with a simple drop-in replacement.
In order to record trace events, executables have to use a Subscriberimplementation compatible with tracing. A Subscriber implements away of collecting trace data, such as by logging it to standard output.
In addition, the default subscriber can be set through using thewith_default function. This follows the tokio pattern of usingclosures to represent executing code in a context that is exited at the endof the closure. For example:
This approach allows trace data to be collected by multiple subscriberswithin different contexts in the program. Note that the override only applies to thecurrently executing thread; other threads will not see the change from with_default.
In addition to tracing and tracing-core, the tokio-rs/tracing repositorycontains several additional crates designed to be used with the tracing ecosystem.This includes a collection of Subscriber implementations, as well as utilityand adapter crates to assist in writing Subscribers and instrumentingapplications.
log: causes trace instrumentation points to emit log records as wellas trace events, if a default tracing subscriber has not been set. Thisis intended for use in libraries whose users may be using either tracingor log.
log-always: Emit log records from all tracing spans and events, evenif a tracing subscriber has been set. This should be set only byapplications which intend to collect traces and logs separately; if anadapter is used to convert log records into tracing events, this willcause duplicate events to occur.
attributes: Includes support for the #[instrument] attribute.This is on by default, but does bring in the syn crate as a dependency,which may add to the compile time of crates that do not already use it.
Tracing is built against the latest stable release. The minimum supportedversion is 1.56. The current Tracing version is not guaranteed to build onRust versions earlier than the minimum supported version.
Tracing follows the same compiler support policies as the rest of the Tokioproject. The current stable Rust compiler and the three most recent minorversions before it will always be supported. For example, if the currentstable compiler version is 1.69, the minimum supported version will not beincreased past 1.66, three minor versions prior. Increasing the minimumsupported compiler version is not considered a semver breaking change aslong as doing so complies with this policy.
Tracing in software engineering refers to the process of capturing and recording information about the execution of a software program. This information is typically used by programmers for debugging purposes, and additionally, depending on the type and detail of information contained in a trace log, by experienced system administrators or technical-support personnel and by software monitoring tools to diagnose common problems with software.[1] Tracing is a cross-cutting concern.
There is not always a clear distinction between tracing and other forms of logging, except that the term tracing is almost never applied to logging that is a functional requirement of a program (therefore excluding logging of data from an external source, such as data acquisition in a high-energy physics experiment, and write-ahead logging). Logs that record program usage (such as a server log) or operating-system events primarily of interest to a system administrator (see for example Event Viewer) fall into a terminological gray area.
Software tracing is a tool for developers to gather information for debugging. This information is used both during development cycles and post-release. Unlike event logging, software tracing usually does not have the concept of a "class" of event or an "event code". Other reasons why event-logging solutions based on event codes are inappropriate for software tracing include:
Linux offers system-level and user-level tracing capabilities with kernel markers and LTTng. ftrace also supports Linux kernel tracing. syslog is another tool in various operating systems for logging and tracing system messages.
Trace generation of method calls can be done with source code instrumentation, runtime information collection, or under debugger control.[7] Tracing macros, Aspect-oriented programming and related instrumentation techniques can be employed.
Event logging provides system administrators with information useful for diagnostics and auditing. The different classes of events that will be logged, as well as what details will appear in the event messages, are often considered early in the development cycle. Many event logging technologies allow or even require each class of event to be assigned a unique "code", which is used by the event logging software or a separate viewer (e.g., Event Viewer) to format and output a human-readable message. This facilitates localization and allows system administrators to more easily obtain information on problems that occur.
Difficulties in making a clear distinction between event logging and software tracing arise from the fact that some of the same technologies are used for both, and further because many of the criteria that distinguish between the two are continuous rather than discrete. The following table lists some important, but by no means precise or universal, distinctions that are used by developers to select technologies for each purpose, and that guide the separate development of new technologies in each area:
If tracing is enabled or disabled at compile-time, collecting trace data from a client's system hinges on their willingness and capability to install a version of the software specifically enabled for tracing, and subsequently replicate the issue.
Tracing in software typically demands high standards of robustness, not only in the accuracy and reliability of the trace output but also in ensuring that the process being traced remains uninterrupted.
Given its low-level nature, tracing can generate a large volume of messages. To mitigate performance issues, it's often necessary to have the option to deactivate software tracing, either at the time of compilation or during run-time.
From April 2020 to December 2021, the Community Tracing Collaborative (CTC) supported local health departments in their contact tracing work on behalf of the Commonwealth of Massachusetts. The goal of the CTC was to assist local health departments and reach out to people who tested positive for COVID-19 and their close contacts, making sure they received the support they needed to isolate, quarantine, or get tested.
The MA Community Tracing Collaborative (CTC) was created by the Baker-Polito COVID-19 Command Center in April 2020 to respond rapidly to the surge in COVID-19 positive cases and to assist the Department of Public Health and local health departments with the COVID-19 public health emergency. Four main organizations worked closely to manage this initiative:
In short, I felt that we were stumbling a little bit around a shared vocabulary.I thought we could probably map out the domain of instrumentation, or observability, as a sort of Venn diagram.Metrics, tracing, and logging are definitely all parts of a broader picture, and can definitely overlap in some circumstances, but I wanted to try and identify the properties of each that were truly distinct.I had a think over a coffee break and came up with this.
I think that the defining characteristic of metrics is that they are aggregatable: they are the atoms that compose into a single logical gauge, counter, or histogram over a span of time.As examples: the current depth of a queue could be modeled as a gauge, whose updates aggregate with last-writer-win semantics; the number of incoming HTTP requests could be modeled as a counter, whose updates aggregate by simple addition; and the observed duration of a request could be modeled into a histogram, whose updates aggregate into time-buckets and yield statistical summaries.
d3342ee215