attributes: implement `#[instrument(tracing)]` by Tamschi · Pull Request #1819 · tokio-rs/tracing

Tamschi · 2022-01-05T23:27:13Z

This adds an optional tracing = Path parameter to the #[instrument] attribute, which can be used to override where the generated code looks for the tracing crate. This defaults to just quote!(tracing), as before.

Closes #1818.

Motivation

Please see the linked issue for details.

In short, this change makes #[instrument] more useful in proc macros (①¹) where tracing is available as optional dependency of the proc macro's library's main crate (②). With the override, ② can re-export tracing for use in ①'s output, which means library crates using ① via ② don't have to include tracing as optional dependency/feature.

¹ Sorry if this is odd. English isn't my first language and it's sometimes hard to use it unambiguously.

Solution

I tried to stay close to the style of the existing code.

So far, I've

added the new parameter,
defaulted it like target,
updated the quotes to replace tracing with #tracing
(and added the required let tracing = args.tracing(); lookup ~~where possible~~).

To do:

It's getting late here and I have a question regarding an implementation detail (I'll comment about that in a moment), so I'm making a draft PR for now.

Tamschi · 2022-01-06T00:45:18Z


+    /// The location of the `tracing` crate.
+    ///
+    /// For backwards-compatibility, this must default to the plain `tracing` identifier with call site resolution.


I'm not entirely sure if this should go into the doc comment, on second thought. A comment above the quote!(tracing) may be more apt.

I'd actually like to suggest adding one of those breaking change comments there: A default of quote!(::tracing) would avoid collisions with consumer-defined names just about entirely by default, but unfortunately it would also break the "hidden override" that's theoretically available right now.

…ent the former This doesn't technically make the parameter more narrow, as the generated code would fail to compile with any other sort of path due to macro calls on it, but it maybe makes some error messages better.

…asure

Tamschi · 2022-01-08T20:35:22Z

+#[instrument(tracing = ::tracing, level = 5)]
+pub fn level_5() {}
+#[instrument(tracing = ::tracing, level = 4)]
+pub fn level_4() {}
+#[instrument(tracing = ::tracing, level = 3)]
+pub fn level_3() {}
+#[instrument(tracing = ::tracing, level = 2)]
+pub fn level_2() {}
+#[instrument(tracing = ::tracing, level = 1)]
+pub fn level_1() {}
+
+const A_LEVEL: ::tracing::Level = ::tracing::Level::INFO;
+#[instrument(tracing = ::tracing, level = A_LEVEL)]
+pub fn level_ident() {}


The ability to specify the level through an integer constant or Level-identifier seems to be undocumented, as far as the immediate ///-documentation on #[instrument] goes. Should I document it or is this deprecated/out of scope for this PR?

(I'd still like to keep these tests here regardless of the answer to that question, since they all have distinct code paths.)

It should probably be documented, but in a follow-up PR. We should probably document it on the Level type as well, since I believe its FromStr implementation will also accept numbers.

davidbarsky · 2022-01-11T21:11:29Z

I'll try to review this PR shortly, but looking over how you're generating components in Asteracea (to use proc-macro-definitions/src/component_declaration.rs as an example), you can mimic what tracing-attributes does to generate spans by creating a span within the function body by writing something like this instead of using the #[instrument] macro:

let _guard = tracing::info_span!(#new_span_name).enter();

I still think it's probably a good idea for us to figure out the hygiene issues with the #[instrument], however.

Tamschi · 2022-01-11T22:12:37Z

Thank you for the hint, I may eventually do that to keep the proc macro requirements low (or to work around the debug/display name collision issue).

…o instead of using `#[instrument]` This skips waiting for <tokio-rs/tracing#1819> to land and should also compile a bit faster in some cases.

bryangarza · 2022-05-09T19:56:53Z

@Tamschi is this PR something you will continue working on, or should we close?

Tamschi · 2022-05-09T20:53:31Z

@Tamschi is this PR something you will continue working on, or should we close?

Well I mean, I had completed this in January from my end. I was only waiting for a review.
(No problem though, I don't exactly have expectations to OSS projects in general. (Edit: Not sarcasm. It's totally fine.))

I can look into those conflicts though, one moment.

Tamschi · 2022-05-09T20:57:05Z

There. This should be good to merge again, but if anything's amiss please let me know!

bryangarza · 2022-05-09T23:25:49Z

Thanks for fixing the conflicts, we'll go through the code in the next few days.

Tamschi · 2022-09-24T10:45:29Z

I just resolved the two merge conflicts that had appeared at some point since May, so this should be ready to merge again.

(I wish there was a notification for this, that way I could have fixed it much earlier. Maybe I just missed it.)

…type

Tamschi · 2023-04-01T10:29:17Z

New year, new attempt 😅

Yes, I'm still (very slowly) building my framework on top of this branch.
I actually hit a snag where I can't use the tracing::info_span! trick easily anymore, since I'm now conditionally emitting async component constructors. It would be great to see this land in that regard.

There is one clippy warning, but it's in a different crate untouched by this MR, so I didn't fix it on my end.

benluelo · 2024-09-10T15:24:09Z

any progress here? this is currently required for any crate that tries to reexport tracing (generated code trying to reexport everything under one crate, etc)

# Conflicts: # tracing-attributes/src/expand.rs

Tamschi · 2024-09-23T09:59:00Z

I just resolved the new merge conflict (and a copy-paste mistake in an error message that I'd missed).

But yeah, this would still be good to get merged. I've added support for coloured async to Asteracea since, and supporting tracing for that without relying on tracing-attributes would be cumbersome.

any progress here? this is currently required for any crate that tries to reexport tracing (generated code trying to reexport everything under one crate, etc)

The implementation here has been complete for two and a half years, though I've had to fix merge conflicts occasionally.
(I'm not notified when one occurs due to the master branch moving ahead. I check back here occasionally if there's any updates.)

Maybe this fifth opportunity's a charm to get a review for it 😉

Tamschi · 2025-07-23T07:47:31Z

Ah, that wasn't quite right. I'll merge it locally in a moment.

# Conflicts: # tracing-attributes/src/attr.rs # tracing-attributes/src/expand.rs

Tamschi · 2025-07-23T08:38:06Z

(Replacing only the failing commit) InstrumentArgs::tracing() now defaults to ::tracing to match #3126 (which would have been exactly that two-character change had this been merged 😉)

The warnings are unrelated to this PR.

That said, I'm not sure for how long I'll continue to keep this PR merge-ready, as the feature is available in fastrace now.

Tamschi added 2 commits January 5, 2022 23:25

add #[instrument(tracing = Expr)] parameter

78b4e37

[WIP] implement tracing override for #[instrument]

087e369

Tamschi commented Jan 5, 2022

View reviewed changes

Comment thread tracing-attributes/src/attr.rs Outdated

Tamschi commented Jan 6, 2022

View reviewed changes

implement tracing override for #[instrument]

fabca1a

Tamschi force-pushed the instrument-tracing-override branch from d331d95 to fabca1a Compare January 8, 2022 15:37

Tamschi added 5 commits January 8, 2022 17:14

add the first set of #[instrument(tracing)] tests

aadd850

link to symbols in #[instrument(tracing)] documentation

1684e54

add tests for remaining #[instrument(tracing)] code paths

b91ee93

check #[instrument(tracing, level)] with a level ident, for good me…

899714d

…asure

Tamschi commented Jan 8, 2022

View reviewed changes

Tamschi marked this pull request as ready for review January 8, 2022 20:37

Tamschi requested review from a team, davidbarsky and hawkw as code owners January 8, 2022 20:37

Merge branch 'master' into instrument-tracing-override

96f016f

Merge branch 'master' into instrument-tracing-override

40ad784

Merge branch 'master' into instrument-tracing-override

f4b31c5

bryangarza self-requested a review May 9, 2022 23:25

Merge branch 'master' into instrument-tracing-override

a185b25

Merge branch 'master' into instrument-tracing-override

a17b04d

Moved ToTokens implementation of Level to new LevelWithTracing …

3b5d4c3

…type

Tamschi added 2 commits September 23, 2024 11:39

Merge branch 'master' into instrument-tracing-override

fc39c55

# Conflicts: # tracing-attributes/src/expand.rs

attributes: fix copy-paste mistake in error message

12b854e

Tamschi added 4 commits October 3, 2024 13:53

Merge branch 'master' into instrument-tracing-override

3802e68

Merge branch 'master' into instrument-tracing-override

72bc05c

Merge branch 'master' into instrument-tracing-override

bc1789c

Merge branch 'master' into instrument-tracing-override

cba4489

Merge branch 'master' into instrument-tracing-override

4af7280

# Conflicts: # tracing-attributes/src/attr.rs # tracing-attributes/src/expand.rs

Tamschi force-pushed the instrument-tracing-override branch from 4b106c4 to 4af7280 Compare July 23, 2025 08:28

Conversation

Tamschi commented Jan 5, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

Uh oh!

Uh oh!

Tamschi Jan 6, 2022

Choose a reason for hiding this comment

Uh oh!

Tamschi Jan 8, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hawkw Jan 11, 2022

Choose a reason for hiding this comment

Uh oh!

davidbarsky commented Jan 11, 2022

Uh oh!

Tamschi commented Jan 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bryangarza commented May 9, 2022

Uh oh!

Tamschi commented May 9, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tamschi commented May 9, 2022

Uh oh!

bryangarza commented May 9, 2022

Uh oh!

Tamschi commented Sep 24, 2022

Uh oh!

Tamschi commented Apr 1, 2023

Uh oh!

benluelo commented Sep 10, 2024

Uh oh!

Tamschi commented Sep 23, 2024

Uh oh!

Tamschi commented Jul 23, 2025

Uh oh!

Tamschi commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Tamschi commented Jan 5, 2022 •

edited

Loading

Tamschi Jan 8, 2022 •

edited

Loading

Tamschi commented Jan 11, 2022 •

edited

Loading

Tamschi commented May 9, 2022 •

edited

Loading

Tamschi commented Jul 23, 2025 •

edited

Loading