A tool for tracing::instrument

[JonathanWoollett-Light]

Feature Request

Crates

tracing

Motivation

I work on a large project with >3500 functions, I do not want to go through all of these adding tracing::instrument.

Proposal

I made a tool (https://github.com/JonathanWoollett-Light/clippy-tracing) that can:

• Add tracing::instrument to all functions.
• Remove tracing::instrument from all functions.
• Check if any functions are missing tracing::instrument.

This significantly helps (and I would argue is even necessary) to integrate tracing in a large project.

This tool should be an official crate and can greatly improve the developer experience.

Alternatives

I'm not aware of any alternative.

[hawkw]

Hi @JonathanWoollett-Light, this is very cool! I think your tool will definitely be useful to a lot of tracing users!

At this time, we are trying to avoid adding any new crates to the tokio-rs/tracing repository (and are in the process of moving some crates that don't strictly need to be in this repo into their own repos). This is in order to reduce the maintenance burden in this repo --- for example, CI builds in this repository are currently quite slow as they have to build a large number of crates. It seems like your tool doesn't really need to be in the tokio-rs/tracing git repo, as it doesn't directly depend on any tracing crates and shouldn't need tight integration testing with changes to tracing and tracing-core. Therefore, I think development on both tracing and clippy-tracing will probably be able to move much faster if we keep them in separate git repositories.

However, we'd be very happy to add links to your crate to the tracing documentation. To start, there's a list of related crates in the tracing documentation, here:

tracing/tracing/src/lib.rs

Lines 745 to 813 in ebd437c

	//! ## Related Crates
	//!
	//! In addition to `tracing` and `tracing-core`, the [`tokio-rs/tracing`] repository
	//! contains several additional crates designed to be used with the `tracing` ecosystem.
	//! This includes a collection of `Collect` implementations, as well as utility
	//! and adapter crates to assist in writing collectors and instrumenting
	//! applications.
	//!
	//! In particular, the following crates are likely to be of interest:
	//!
	//! - [`tracing-futures`] provides a compatibility layer with the `futures`
	//! crate, allowing spans to be attached to `Future`s, `Stream`s, and `Executor`s.
	//! - [`tracing-subscriber`] provides `tracing_subscriber::Subscribe` implementations and
	//! utilities for working with collectors. This includes a [`FmtSubscriber`]
	//! for logging formatted trace data to stdout, with similar
	//! filtering and formatting to the [`env_logger`] crate.
	//! - [`tracing-log`] provides a compatibility layer with the [`log`] crate,
	//! allowing log messages to be recorded as `tracing` `Event`s within the
	//! trace tree. This is useful when a project using `tracing` have
	//! dependencies which use `log`. Note that if you're using
	//! `tracing-subscriber`'s `FmtSubscriber`, you don't need to depend on
	//! `tracing-log` directly.
	//! - [`tracing-appender`] provides utilities for outputting tracing data,
	//! including a file appender and non blocking writer.
	//!
	//! Additionally, there are also several third-party crates which are not
	//! maintained by the `tokio` project. These include:
	//!
	//! - [`tracing-timing`] implements inter-event timing metrics on top of `tracing`.
	//! It provides a subscriber that records the time elapsed between pairs of
	//! `tracing` events and generates histograms.
	//! - [`tracing-opentelemetry`] provides a subscriber for emitting traces to
	//! [OpenTelemetry]-compatible distributed tracing systems.
	//! - [`tracing-honeycomb`] Provides a layer that reports traces spanning multiple machines to [honeycomb.io]. Backed by [`tracing-distributed`].
	//! - [`tracing-distributed`] Provides a generic implementation of a layer that reports traces spanning multiple machines to some backend.
	//! - [`tracing-actix-web`] provides `tracing` integration for the `actix-web` web framework.
	//! - [`tracing-actix`] provides `tracing` integration for the `actix` actor
	//! framework.
	//! - [`tracing-gelf`] implements a subscriber for exporting traces in Greylog
	//! GELF format.
	//! - [`tracing-coz`] provides integration with the [coz] causal profiler
	//! (Linux-only).
	//! - [`tracing-bunyan-formatter`] provides a layer implementation that reports events and spans
	//! in [bunyan] format, enriched with timing information.
	//! - [`tracing-wasm`] provides a `Collect`/`Subscribe` implementation that reports
	//! events and spans via browser `console.log` and [User Timing API (`window.performance`)].
	//! - [`tracing-web`] provides a layer implementation of level-aware logging of events
	//! to web browsers' `console.*` and span events to the [User Timing API (`window.performance`)].
	//! - [`tide-tracing`] provides a [tide] middleware to trace all incoming requests and responses.
	//! - [`test-log`] takes care of initializing `tracing` for tests, based on
	//! environment variables with an `env_logger` compatible syntax.
	//! - [`tracing-unwrap`] provides convenience methods to report failed unwraps
	//! on `Result` or `Option` types to a [`collect`].
	//! - [`diesel-tracing`] provides integration with [`diesel`] database connections.
	//! - [`tracing-tracy`] provides a way to collect [Tracy] profiles in instrumented
	//! applications.
	//! - [`tracing-elastic-apm`] provides a layer for reporting traces to [Elastic APM].
	//! - [`tracing-etw`] provides a layer for emitting Windows [ETW] events.
	//! - [`tracing-fluent-assertions`] provides a fluent assertions-style testing
	//! framework for validating the behavior of `tracing` spans.
	//! - [`sentry-tracing`] provides a layer for reporting events and traces to [Sentry].
	//! - [`tracing-forest`] provides a subscriber that preserves contextual coherence by
	//! grouping together logs from the same spans during writing.
	//! - [`tracing-loki`] provides a layer for shipping logs to [Grafana Loki].
	//! - [`tracing-logfmt`] provides a layer that formats events and spans into the logfmt format.
	//! - [`reqwest-tracing`] provides a middleware to trace [`reqwest`] HTTP requests.
	//!
	//! If you're the maintainer of a `tracing` ecosystem crate not listed above,
	//! please let us know! We'd love to add your project to the list!

We should definitely add clippy-tracing to that list. I would also be happy to accept PRs that mention the use of your tool in the documentation for the #[tracing::instrument] macro, and in various "getting started" guides such as https://tokio.rs/tokio/topics/tracing.

If your tool starts getting widespread adoption by users, we would definitely also be open to making it an "official" tracing project by moving it into the tokio-rs github organization, in its own repository (tokio-rs/clippy-tracing?). If we do that, it would be helpful if you would assume some of the responsibility for maintaining the project after its moved into the tokio-rs organization.

[JonathanWoollett-Light]

Thankyou for the repones, I've posted a PR adding it to the documentation #2628.