itsscb/tracing
1
0
Fork 0
mirror of https://github.com/tokio-rs/tracing.git synced 2025-10-01 15:00:33 +00:00
Code Issues Packages Projects Releases Wiki Activity
tracing/examples/README.md
Benjamin Saunders 8c0ef97bd4
journald: add tracing-journald crate implementing a simple journald layer (#691) 
## Motivation

Support for writing tracing-based logs directly to their standard
destination while preserving both standard and custom metadata on Linux
systems. Improves usability of Linux services and for Linux applications
executing outside of a terminal.

## Solution

It turns out [journald's native protocol][1] is very simple and spoken
over a Unix datagram socket at a fixed location (see [discussion of
stability of these interfaces][2], allowing high quality native support
with ~100LoC.

[journald conventions][3] for structured field names differ from typical
tracing idioms, and journald discards fields which violate its
conventions. Hence, this layer automatically sanitizes field names by
translating `.`s into `_`s, stripping leading `_`s and
non-ascii-alphanumeric characters other than `_`, and upcasing.

Levels are mapped losslessly to journald `PRIORITY` values as follows:

- `ERROR` => Error (3)
- `WARN` => Warning (4)
- `INFO` => Notice (5)
- `DEBUG` => Informational (6)
- `TRACE` => Debug (7)

Note that the naming scheme differs slightly for the latter half.

The standard journald `CODE_LINE` and `CODE_FILE` fields are
automatically emitted. A `TARGET` field is emitted containing the
event's target. Enclosing spans are numbered counting up from the root,
and their fields and metadata are included in fields prefixed by `Sn_`
where `n` is that number.

User-defined fields other than the event `message` field have a prefix
applied by default to prevent collision with standard fields.

[1]: https://www.freedesktop.org/wiki/Software/systemd/export/
[2]: https://systemd-devel.freedesktop.narkive.com/i5tlUyjz/client-logging-to-journald-without-libsystemd-journal-so#post6
[3]: https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html
2020-06-29 12:07:24 -07:00

3.5 KiB
Raw Blame History

Tracing Examples

This directory contains a collection of examples that demonstrate the use of the tracing ecosystem:

  • tracing:
    • counters: Implements a very simple metrics system to demonstrate how subscribers can consume field values as typed data.
    • sloggish: A demo Subscriber implementation that mimics the output of slog-term's Compact formatter.
  • tracing-attributes:
    • attrs-basic: A simple example of the #[instrument] attribute.
    • attrs-args: An example implementing a simple recursive calculation of Fibonacci numbers, to demonstrate how the #[instrument] attribute can record function arguments.
  • tracing-subscriber:
    • fmt: Demonstrates the use of the fmt module in tracing-subscriber, which provides a subscriber implementation that logs traces to the console.
    • fmt-stderr: Demonstrates overriding the output stream used by the fmt subscriber.
    • fmt-custom-field: Demonstrates overriding how the fmt subscriber formats fields on spans and events.
    • fmt-custom-event: Demonstrates overriding how the fmt subscriber formats events.
    • subscriber-filter: Demonstrates the tracing-subscriber::filter module, which provides a layer which adds configurable filtering to a subscriber implementation.
    • tower-load: Demonstrates how dynamically reloadable filters can be used to debug a server under load in production.
    • journald: Demonstrates how to use fmt and journald layers to output to both the terminal and the system journal.
  • tracing-futures:
    • spawny-thing: Demonstrates the use of the #[instrument] attribute macro asynchronous functions.
    • tokio-spawny-thing.rs: Similar to spawny-thingy, but with the additional demonstration instrumenting concurrent tasks created with tokio::spawn.
    • futures-proxy-server: Demonstrates the use of tracing-futures by implementing a simple proxy server, based on this example from tokio.
    • async_fn: Demonstrates how asynchronous functions can be instrumented.
    • echo: Demonstrates a tracing-instrumented variant of Tokio's echo example.
  • tracing-flame:
    • infero-flame: Demonstrates the use of tracing-flame to generate a flamegraph from spans.
  • tracing-tower:
    • tower-client: Demonstrates the use of tracing-tower to instrument a simple tower HTTP/1.1 client.
    • tower-server: Demonstrates the use of tracing-tower to instrument a simple tower HTTP/1.1 server.
  • tracing-serde:
    • serde-yak-shave: Demonstrates the use of tracing-serde by implementing a subscriber that emits trace output as JSON.
  • tracing-log:
    • hyper-echo: Demonstrates how tracing-log can be used to record unstructured logs from dependencies as tracing events, by instrumenting this example from hyper, and using tracing-log to record logs emitted by hyper.
  • tracing-opentelemetry:
    • opentelemetry: Demonstrates how tracing-opentelemetry can be used to export and visualize tracing span data.
    • opentelemetry-remote-context: Demonstrates how tracing-opentelemetry can be used to extract and inject remote context when traces span multiple systems.