Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: backport roughly a year's worth of changes #2728

Merged
merged 34 commits into from
Oct 1, 2023

Commits on Sep 26, 2023

  1. mock: differentiate between mocks and expectations (#2373)

    The `tracing-mock` crate provides a mock collector (and a subscriber for
    use by the tests in the `tracing-subscriber` crate) which is able to
    make assertions about what diagnostics are emitted.
    
    These assertions are defined by structs that match on events, span, and
    their fields and metadata. The structs that matched these objects have
    been called, up until now, mocks, however this terminology may be
    misleading, as the created objects don't mock anything.
    
    There were two different names for similar functionality with `only()`
    and `done()` on fields and collectors/subscribers respectively. Using a
    single name for these may make it easier to onboard onto `tracing-mock`.
    
    To reduce confusion, these structs have been split into two categories:
    mocks and expectations.
    
    Additionally, the `done()` function on the `Collector` and `Subscriber`
    mocks has been replaced with `only()`. This matches the similar function
    for `ExpectedField`, and may be more intuitive.
    
    The mocks replace some component in the tracing ecosystem when a library
    is under test. The expectations define the assertions we wish to make
    about traces received by the mocks.
    
    Mocks (per module):
    * collector - `MockCollector`, no change
    * subscriber - `MockSubscriber`, renamed from `ExpectSubscriber`
    
    Expectations (per module):
    * event - `ExpectedEvent`, renamed from `MockEvent`
    * span - `ExpectedSpan`, renamed from `MockSpan`
    * field - `ExpectedField` and `ExpectedFields`, renamed from `MockField`
      and `Expected`. Also `ExpectedValue` renamed from `MockValue`.
    * metadata - `ExpectedMetadata`, renamed from `Expected`
    
    Refs: #539
    hds authored and davidbarsky committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    5048b86 View commit details
    Browse the repository at this point in the history
  2. mock: change helper functions to expect::<thing> (#2377)

    * mock: change helper functions to `expect::<thing>`
    
    The current format of test expectations in `tracing-mock` isn't ideal.
    The format `span::expect` requires importing `tracing_mock::<thing>` which
    may conflict with imports from other tracing crates, especially
    `tracing-core`.
    
    So we change the order and move the functions into a module called
    `expect` so that:
    * `event::expect` becomes `expect::event`
    * `span::expect` becomes `expect::span`
    * `field::expect` becomes `expect::field`
    
    This format has two advantages.
    1. It reads as natural English, e.g "expect span"
    2. It is no longer common to import the modules directly.
    
    Regarding point (2), the following format was previously common:
    
    ```rust
    use tracing_mock::field;
    
    field::expect();
    ```
    
    This import of the `field` module may then conflict with importing the
    same from `tracing_core`, making it necessary to rename one of the
    imports.
    
    The same code would now be written:
    
    ```rust
    use tracing_mock::expect;
    
    expect::field();
    ```
    
    Which is less likely to conflict.
    
    This change also fixes an unused warning on `MockHandle::new` when the
    `tracing-subscriber` feature is not enabled.
    
    Refs: #539
    hds authored and davidbarsky committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    dc636df View commit details
    Browse the repository at this point in the history
  3. mock: add README to tracing-mock (#2362)

    There has been interest around publishing `tracing-mock` to crates.io
    for some time. In order to make this possible, documentation and some
    code clean up is needed.
    
    Specifically **I** want to have access to `tracing-mock` within parts of
    `tokio` to write tests that ensure that the correct calling location is
    picked up for all `spawn*` functions when the `tracing` feature is
    enabled.
    
    This change starts that process by adding a README for `tracing-mock`.
    The README follows the standard format for all `tracing` crates and
    includes 2 examples. The README is included in the `lib.rs` docs using
    `#[doc = include_str!(...)]`, so that the same documentation is included
    in the crate, and the examples are tested when running doctests.
    
    The README describes steps when using the `tracing` 1.0 from crates.io
    and `tracing-mock` from the `v0.1.x` branch. The tests target the
    current branch.
    
    Co-authored-by: David Barsky <[email protected]>
    Co-authored-by: Eliza Weisman <[email protected]>
    3 people committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    9c6ffce View commit details
    Browse the repository at this point in the history
  4. attributes: update async_instrument error text for Rust 1.66 (#2427)

    The error message suggesting that you remove a semicolon to return a
    value (instead of unit) was updated slightly in rust-lang/rust#102650,
    which was included in Rust 1.66.0.
    
    This causes one of the tests in tracing-attributes to fail. We fix it by
    using the updated error message.
    hds authored and davidbarsky committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    5db72b6 View commit details
    Browse the repository at this point in the history
  5. mock: document public APIs in event module (#2426)

    There has been interest around publishing tracing-mock to crates.io
    for some time. In order to make this possible, documentation and some
    code clean up is needed.
    
    The `event` module needs documentation and examples.
    
    This change adds documentation to the event module and all the public
    APIs within it. This includes doctests on all the methods which serve as
    examples.
    
    The following pattern was applied to the description of most methods:
    - Short description of expectation
    - Additional clarification (where needed)
    - Description of cases that cause the expectation to fail
    - Examples
      - Successful validation
      - Unsuccesful validation
    
    Two changes were also made in the text provided to the user when an
    assertion fails for `with_explicit_parent` or `with_contextual_parent`.
    
    One small API changes is also included:
    
    The method `in_scope` has been placed behind the `tracing-subscriber`
    feature flag as it currently only works with the `MockSubscriber`, not
    with the `MockCollector`. If the feature flag is active and it is used
    to set a non-empty scope, the `MockCollector` will panic with
    `unimplemented` during validation.
    
    Refs: #539
    hds authored and davidbarsky committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    e8b3795 View commit details
    Browse the repository at this point in the history
  6. mock: document public APIs in subscriber module (#2446)

    There has been interest around publishing `tracing-mock` to crates.io
    for some time. In order to make this possible, documentation and some
    code clean up is needed.
    
    The `subscriber` module needs documentation and examples.
    
    This change adds documentation to the `subscriber` module and all the public
    APIs within it. This includes doctests on all the methods which serve as
    examples.
    
    The `MockSubscriberBuilder::record` method was removed as its
    functionality is not implemented.
    
    Previously, the `MockSubscriber` would verify the scope of an
    `ExpectedEvent`, even if `in_scope` hadn't been called. In this case,
    that would check that an event was not in a span if `in_scope` had not
    been called. `tracing-subscriber` all adhere to this pattern. However it
    is different to the behavior of all other expectation methods, where an
    explicit call is needed to expect something, otherwise nothing is
    checked. As such, the behavior has been modified to align with the rest
    of the crate. The previous behavior can be achieved by calling
    `in_scope(None)` to verify that an event has no scope. The documentation
    for `in_scope` has been updated with an example for this case.
    
    The tests in `tracing-subscriber` which previously verified *implicitly*
    that an event had no scope (by not calling `in_scope` at all) have *not*
    been modified. It is my opinion that this implicit behavior was never
    required.
    
    Refs: #539
    hds authored and davidbarsky committed Sep 26, 2023
    Configuration menu
    Copy the full SHA
    cbcfbf9 View commit details
    Browse the repository at this point in the history

Commits on Sep 27, 2023

  1. docs: fix typo in panic_hook example (#2453)

    arifd authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    516392c View commit details
    Browse the repository at this point in the history
  2. chore: bump MSRV to 1.56 (#2546)

    As part of upgrading syn to 2.0 (e.g.,
    #2516), we need to bump the MSRV
    to 1.56. As part of this PR, I've:
    - Updated the text descriptions of what would be an in-policy MSRV bump
      to use more recent versions of rustc. The _niceness_ of said version
      numbers are purely coincidental.
    - I've removed some of the exceptions made in CI.yml in order to support
      some crates with a higher MSRV.
    davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    d55ce3d View commit details
    Browse the repository at this point in the history
  3. core: add ValueSet::len and Record::len (#2152)

    This PR adds two new accessor functions that are useful for creating a
    structured serde implementation for tracing.
    
    This is a sort of "distilled" version of
    #2113, based on the `v0.1.x`
    branch.
    
    As it is unlikely that "structured serde" will be 1:1 compatible with
    the existing JSON-based `tracing-serde` (or at least - I'm not sure how
    to do it in a reasonable amount of effort), these functions will allow
    me to make a separate crate to hold me over until breaking formatting
    changes are possible in `tracing-serde`.
    
    CC @hawkw, as we've discussed this pretty extensively
    jamesmunns authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    bcaeaa9 View commit details
    Browse the repository at this point in the history
  4. mock: document public API in collector module (#2389)

    There has been interest around publishing `tracing-mock` to crates.io
    for some time. In order to make this possible, documentation and some
    code clean up is needed.
    
    This change adds documentation to the collector module itself and to all the
    public APIs in the module. This includes doctests on all the methods
    that serve as examples.
    
    Additionally the implementation for the `Expect` struct has been moved
    into the module with the definition, this was missed in #2369.
    
    Refs: #539
    hds authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    bb81c7e View commit details
    Browse the repository at this point in the history
  5. tracing: use fully qualified names in macros for items exported from …

    …std prelude (#2621)
    
    Currently, in many places, macros do not use fully qualified names for
    items exported from the prelude. This means that naming collisions
    (`struct Some`) or the removal of the std library prelude will cause
    compilation errors.
    
    - Identify and use fully qualified names in macros were we previously
      assumed the Rust std prelude. We use `::core` rather than `::std`.
    - Add
      [`no_implicit_prelude`](https://doc.rust-lang.org/reference/names/preludes.html#the-no_implicit_prelude-attribute)
      to `tracing/tests/macros.rs`. I'm unsure if this is giving us good
      coverage - can we improve on this approach? I'm not confident I've
      caught everything.
    hlbarber authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    0b31599 View commit details
    Browse the repository at this point in the history
  6. Configuration menu
    Copy the full SHA
    ddb1b8a View commit details
    Browse the repository at this point in the history
  7. Configuration menu
    Copy the full SHA
    8e77a43 View commit details
    Browse the repository at this point in the history
  8. Configuration menu
    Copy the full SHA
    5952e36 View commit details
    Browse the repository at this point in the history
  9. core: ensure callsites in test have unique addresses (#2681)

    The test relies on TEST_CALLSITE_1 and TEST_CALLSITE_2 to have
    different addresses. However, as they are zero-sized types, this
    is not guaranteed.
    
    This fixes the test failure with LLVM 17 and certain optimization
    options reported at rust-lang/rust#114699.
    nikic authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    8cb22ff View commit details
    Browse the repository at this point in the history
  10. Configuration menu
    Copy the full SHA
    2ee84b3 View commit details
    Browse the repository at this point in the history
  11. docs: Add clippy-tracing to related crates (#2628)

    ## Motivation
    
    Sharing tooling.
    
    ## Solution
    
    Adds `clippy-tracing` to related crates.
    
    Closes #2627
    JonathanWoollett-Light authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    1fa24df View commit details
    Browse the repository at this point in the history
  12. tracing: fix wasm_bindgen_test macros (#2675)

    ## Motivation
    
    Tests involving `wasm_bindgen_test` currently fail:
    
    https://github.com/tokio-rs/tracing/actions/runs/5756318807/job/15605512576
    
    ## Solution
    
    - [x] Use `extern crate wasm_bindgen_test` to side-step `no_implicit_prelude`.
    - [x] rustwasm/wasm-bindgen#3549
    - [ ] Consume the release `wasm_bindgen_test` containing said change.
    hlbarber authored and davidbarsky committed Sep 27, 2023
    Configuration menu
    Copy the full SHA
    5da7799 View commit details
    Browse the repository at this point in the history

Commits on Sep 29, 2023

  1. subscriber: support NO_COLOR in fmt::Layer (#2647)

    It's necessary at times to be able to disable ANSI color output for
    rust utilities using `tracing`.  The informal standard for this is the
    `NO_COLOR` environment variable described here: https://no-color.org/
    
    Further details/discussion in #2388
    
    This commit updates `fmt::Layer` to check the `NO_COLOR`
    environment variable when determining whether ANSI color output is
    enabled by default. As described in the spec, any non-empty value set
    for `NO_COLOR` will cause ANSI color support to be disabled by default.
    
    If the user manually overrides ANSI color support, such as by calling
    `with_ansi(true)`, this will still enable ANSI colors, even if
    `NO_COLOR` is set. The `NO_COLOR` env var only effects the default
    behavior.
    
    Fixes #2388
    dmlary authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    bbc87fe View commit details
    Browse the repository at this point in the history
  2. chore: fix new warnings in Rust 1.72.0 (#2700)

    This branch fixes a handful of new warnings which have shown up after
    updating to Rust 1.72.0.
    
    This includes:
    
    * `clippy::redundant_closure_call` in macros --- allowed because the
      macro sometimes calls a function that isn't a closure, and the closure
      is just used in the case where it's not a function.
    * Unnecessary uses of `#` in raw string literals that don't contain `"`
      characters.
    * Dead code warnings with specific feature flag combinations in
      `tracing-subscriber`.
    
    In addition, I've fixed a broken RustDoc link that was making the
    Netlify build sad.
    hawkw authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    95b1d5c View commit details
    Browse the repository at this point in the history
  3. attributes: fix instrument with "log" feature (#2599)

    ## Motivation
    
    The instrument macro currently doesn't work with the "log" crate
    feature: #2585
    
    ## Solution
    
    Change the generated code to create a span if either
    `tracing::if_log_enabled!` or `tracing::level_enabled!`. I'm not sure
    how to add a test for this or if this is the best solution.
    
    Fixes #2585
    miwig authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    316c5a1 View commit details
    Browse the repository at this point in the history
  4. appender: clarify file appender docs (#2689)

    ## Motivation
    
    There are a few errors in the file appender docs - this fixes them.
    
    It also wasn't clear/apparent to me that you can create a non-rolling
    file appender with the `rolling` module - this calls that out more
    clearly.
    
    ## Solution
    
    Updates to docs.
    CLEckhardt authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    7d63c84 View commit details
    Browse the repository at this point in the history
  5. flame: fix folded formatting (#2710)

    ## Motivation
    
    The `.folded` format expects a `;`-separated list of the stack function,
    optionally followed up by a sample count.
    
    The implementation before this commit added a blank space after each `;`
    which made parsers, such as `inferno-flamegraph` mis-interpret the data.
    
    Furthermore, normally one wouldn't expect the filename and line-number
    in such stack trace.
    
    ## Solution
    
    Remove white-space between `;` for the generated file and remove
    filename and line-number by default.
    conectado authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    e4bb093 View commit details
    Browse the repository at this point in the history
  6. attributes: generate less dead code for async block return type hint (#…

    …2709)
    
    ## Motivation
    
    `#[tracing::instrument]` uses `unreachable!()` macro which needlessly
    expands to panicking and formatting code. It only needs any `!` type.
    
    ## Solution
    
    `loop {}` works just as well for a `!` type, and it crates less work for
    the compiler. The code is truly unreachable, so the message would never
    be useful. Rust used to be concerned about semantics of empty loops in
    LLVM, but this [has been solved](https://reviews.llvm.org/D85393).
    kornelski authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    b658b1f View commit details
    Browse the repository at this point in the history
  7. core: allow ValueSets of any length (#2508)

    ## Motivation
    
    Fixes: #1566
    
    ## Solution
    
    This change removes the maximum of 32 fields limitation using const
    generics.
    
    Having this arbitrary restriction in place to prevent stack overflows
    feels a little misplaced to me since stack size varies between
    environments.
    eopb authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    b0e3c71 View commit details
    Browse the repository at this point in the history
  8. tracing: allow setting event names in macros (#2699)

    ## Motivation
    
    The motivation is #1426.  Currently, event names are set to a default
    value of `event file:line`, which (1) doesn't allow for customization,
    and (2) prevents events from working for some opentelemetry endpoints
    (they often use the event name `exception` to designate something like a
    panic).
    
    ## Solution
    
    Went through the event macros, and added new parameterization that
    allows for setting the `name`.  In addition, added some comments, and
    reordering, to make life a bit better for the next person that comes
    along to edit those macros.  Finally, added tests for the macro
    expansion alongside the existing tests with a reasonable amount of
    coverage (though, admittedly, more could be added for all of the macro
    invocation types
    
    Fixes #1426
    twitchax authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    3b1851d View commit details
    Browse the repository at this point in the history
  9. journald: allow custom journal fields (#2708)

    It's currently not possible to customize how messages will get send to journald.
    
    This became apparent in #2425, where first a specific API got designed, but then
    it was decided that users should not get restricted in only a subset of fields,
    but should be able to simply choose by themselves what fields get set with what
    values.
    
    So in a sense, this is the successor/rework of #2425.
    
    Allow custom fields to be set in tracing-journald.
    
    - [x] How should we deal with fields that also get supplied by other options?
      For example, setting `SYSLOG_IDENTIFIER` here and also setting
      `.with_syslog_identifier()` will send said field twice, potentially with
      differing values. Is that a problem?
        - Answer: No, this is not a problem.
    
    Closes #2425
    Finomnis authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    a0a176e View commit details
    Browse the repository at this point in the history
  10. tracing: allow constant field names in macros (#2617)

    I've found myself in the case where I wanted to have customized event field name
    for different trait implementations. In fact, these implementations are
    completely unrelated (in separate applications), so, in this use case, I find
    more readable to have `foo="some_id"` and `bar=16` instead of `resource="foo"
    value="some_id"` and `resource=bar value=16`
    
    Because events only accept identifier or literal as field name, this is quite
    cumbersome/impossible to do. A simple solution could be to make events accept
    constant expression too; in my use case, I could then add a associated constant
    to my trait.
    
    This PR proposes a new syntax for using constant field names:
    ```rust
    tracing::debug!({ CONSTANT_EXPR } = "foo");
    ```
    This is the same syntax than constant expression, so it should be quite intuitive.
    
    To avoid constant expression names conflict, internal variables of macro
    expansion have been prefixed with `__`, e.g. `__CALLSITE`.
    
    Co-authored-by: Joseph Perez <[email protected]>
    Co-authored-by: Eliza Weisman <[email protected]>
    3 people authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    0687403 View commit details
    Browse the repository at this point in the history
  11. docs: add axum-insights to relevant crates. (#2713)

    ## Motivation
    
    Adding a relevant library to the list of `tracing`-enabled crates.
    
    ## Solution
    
    Added to READMEs and documentation.
    twitchax authored and davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    75f0dbf View commit details
    Browse the repository at this point in the history
  12. [tracing-subscriber]: add chrono crate implementations of FormatTime (#…

    …2690)
    
    Issue #2080 explains that it's not
    possible to soundly use
    [`tracing_subscriber::fmt::time::LocalTime`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/time/struct.LocalTime.html)
    in a multithreaded context. It proposes adding alternative time formatters that
    use the [chrono crate](https://docs.rs/chrono/latest/chrono/) to workaround
    which is what this PR offers.
    
    A new source file 'chrono_crate.rs' is added to the 'tracing-subscriber'
    package implementing `mod chrono_crate` providing two new tag types `LocalTime`
    and `Utc` with associated `time::FormatTime` trait implementations that call
    `chrono::Local::now().to_rfc3339()` and `chrono::Utc::now().to_rfc3339()`
    respectively. Simple unit-tests of the new functionality accompany the
    additions.
    ---------
    
    Co-authored-by: David Barsky <[email protected]>
    Co-authored-by: Shayne Fletcher <[email protected]>
    3 people committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    66d96cd View commit details
    Browse the repository at this point in the history
  13. Configuration menu
    Copy the full SHA
    ffb1b11 View commit details
    Browse the repository at this point in the history
  14. attributes: bump minimum version of proc-macro2 to 1.0.60 (#2732)

    As part of landing #2728, I noticed that the `-Zminimal-versions` check fails
    due to proc-macro2 1.0.40 referencing a since-removed, nightly-only
    feature (`proc_macro_span_shrink`). Since this change doesn't change the MSRV
    of `proc-macro2` (or `tracing`, for that matter), this feels like a safe change
    to make.
    davidbarsky committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    b661e84 View commit details
    Browse the repository at this point in the history
  15. subscriber: Implement layer::Filter for Option<Filter> (#2407)

    It's currently awkward to have an optional per-layer filter.
    
    Implement `Filter<L>` for `Option<F> where F: Filter<L>`, following the example
    of `Layer`. A `None` filter passes everything through.
    
    Also, it looks like Filter for Arc/Box doesn't pass through all the methods, so
    extend the `filter_impl_body` macro to include them.
    
    This also adds a couple of tests and updates the docs.
    
    ---------
    
    Co-authored-by: David Barsky <[email protected]>
    Co-authored-by: Ryan Johnson <[email protected]>
    Co-authored-by: Eliza Weisman <[email protected]>
    4 people committed Sep 29, 2023
    Configuration menu
    Copy the full SHA
    f875c16 View commit details
    Browse the repository at this point in the history
  16. Configuration menu
    Copy the full SHA
    aa51104 View commit details
    Browse the repository at this point in the history