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

subscriber: add docs on registry span ID generation #1453

Merged
merged 3 commits into from
Aug 6, 2021

Conversation

hawkw
Copy link
Member

@hawkw hawkw commented Jun 30, 2021

Motivation

Currently, tracing-subscriber's Registry type doesn't document how
span IDs are generated, or the uniqueness guarantees for span IDs. This
can cause confusion for users trying to implement Subscribers and
other code that interacts with the Registry's generated span IDs.

Solution

This branch adds a new documentation section to the Registry docs
describing how IDs are generated and when they are guaranteed to be
unique. In particular, the new section explicitly states that the
registry's IDs will not uniquely identify a span historically, because
IDs may be reused when a span has closed, and that the registry's
tracing span IDs should not be used as span IDs in a distributed
tracing system.

While I was working on these docs, I also fixed a link on adding
subscribers to a registry that went to a specific method on
FmtSubscriber, rather than to the more general docs on how
subscribers are composed with collectors.

Thanks to @Folyd for suggesting this docs improvement!

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Signed-off-by: Eliza Weisman <eliza@buoyant.io>
@hawkw hawkw requested a review from davidbarsky June 30, 2021 17:40
@hawkw hawkw requested a review from a team as a code owner June 30, 2021 17:40
Co-authored-by: David Barsky <me@davidbarsky.com>
@hawkw hawkw merged commit 9bb421f into master Aug 6, 2021
@hawkw hawkw deleted the eliza/registry-guarantee-docs branch August 6, 2021 16:38
hawkw added a commit that referenced this pull request Aug 17, 2021
## Motivation

Currently, `tracing-subscriber`'s `Registry` type doesn't document how
span IDs are generated, or the uniqueness guarantees for span IDs. This
can cause confusion for users trying to implement `Subscribe`rs and
other code that interacts with the `Registry`'s generated span IDs.

## Solution

This branch adds a new documentation section to the `Registry` docs
describing how IDs are generated and when they are guaranteed to be
unique. In particular, the new section explicitly states that the
registry's IDs will not uniquely identify a span historically, because
IDs may be reused when a span has closed, and that the registry's
`tracing` span IDs should not be used as span IDs in a distributed
tracing system.

While I was working on these docs, I also fixed a link on adding
subscribers to a registry that went to a specific method on
`FmtSubscriber`, rather than to the more general docs on how
subscribers are composed with collectors.

Thanks to @Folyd for suggesting this docs improvement!

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: David Barsky <me@davidbarsky.com>
hawkw added a commit that referenced this pull request Aug 17, 2021
## Motivation

Currently, `tracing-subscriber`'s `Registry` type doesn't document how
span IDs are generated, or the uniqueness guarantees for span IDs. This
can cause confusion for users trying to implement `Subscribe`rs and
other code that interacts with the `Registry`'s generated span IDs.

## Solution

This branch adds a new documentation section to the `Registry` docs
describing how IDs are generated and when they are guaranteed to be
unique. In particular, the new section explicitly states that the
registry's IDs will not uniquely identify a span historically, because
IDs may be reused when a span has closed, and that the registry's
`tracing` span IDs should not be used as span IDs in a distributed
tracing system.

While I was working on these docs, I also fixed a link on adding
subscribers to a registry that went to a specific method on
`FmtSubscriber`, rather than to the more general docs on how
subscribers are composed with collectors.

Thanks to @Folyd for suggesting this docs improvement!

Signed-off-by: Eliza Weisman <eliza@buoyant.io>
Co-authored-by: David Barsky <me@davidbarsky.com>
hawkw added a commit that referenced this pull request Aug 17, 2021
# 0.2.20 (August 17, 2021)
### Fixed

- **fmt**: Fixed `fmt` printing only the first `source` for errors with
  a chain of sources ([#1460])
- **fmt**: Fixed missing space between level and event in the `Pretty`
  formatter ([#1498])
- **json**: Fixed `Json` formatter not honoring `without_time` and
  `with_level` configurations ([#1463])

### Added

- **registry**: Improved panic message when cloning a span whose ID
  doesn't exist, to aid in debugging issues with multiple subscribers
  ([#1483])
- **registry**: Improved documentation on span ID generation ([#1453])

Thanks to new contributors @joshtriplett and @lerouxgd, and returning
contributor @teozkr, for contributing to this release!

[#1460]: #1460
[#1483]: #1483
[#1463]: #1463
[#1453]: #1453
hawkw added a commit that referenced this pull request Aug 17, 2021
# 0.2.20 (August 17, 2021)
### Fixed

- **fmt**: Fixed `fmt` printing only the first `source` for errors with
  a chain of sources ([#1460])
- **fmt**: Fixed missing space between level and event in the `Pretty`
  formatter ([#1498])
- **json**: Fixed `Json` formatter not honoring `without_time` and
  `with_level` configurations ([#1463])

### Added

- **registry**: Improved panic message when cloning a span whose ID
  doesn't exist, to aid in debugging issues with multiple subscribers
  ([#1483])
- **registry**: Improved documentation on span ID generation ([#1453])

Thanks to new contributors @joshtriplett and @lerouxgd, and returning
contributor @teozkr, for contributing to this release!

[#1460]: #1460
[#1483]: #1483
[#1463]: #1463
[#1453]: #1453
hawkw added a commit that referenced this pull request Aug 17, 2021
# 0.2.20 (August 17, 2021)

### Fixed

- **fmt**: Fixed `fmt` printing only the first `source` for errors with
  a chain of sources ([#1460])
- **fmt**: Fixed missing space between level and event in the `Pretty`
  formatter ([#1498])
- **json**: Fixed `Json` formatter not honoring `without_time` and
  `with_level` configurations ([#1463])

### Added

- **registry**: Improved panic message when cloning a span whose ID
  doesn't exist, to aid in debugging issues with multiple subscribers
  ([#1483])
- **registry**: Improved documentation on span ID generation ([#1453])

Thanks to new contributors @joshtriplett and @lerouxrgd, and returning
contributor @teozkr, for contributing to this release!

[#1460]: #1460
[#1483]: #1483
[#1463]: #1463
[#1453]: #1453
[#1498]: #1498
kaffarell pushed a commit to kaffarell/tracing that referenced this pull request May 22, 2024
# 0.2.20 (August 17, 2021)

### Fixed

- **fmt**: Fixed `fmt` printing only the first `source` for errors with
  a chain of sources ([tokio-rs#1460])
- **fmt**: Fixed missing space between level and event in the `Pretty`
  formatter ([tokio-rs#1498])
- **json**: Fixed `Json` formatter not honoring `without_time` and
  `with_level` configurations ([tokio-rs#1463])

### Added

- **registry**: Improved panic message when cloning a span whose ID
  doesn't exist, to aid in debugging issues with multiple subscribers
  ([tokio-rs#1483])
- **registry**: Improved documentation on span ID generation ([tokio-rs#1453])

Thanks to new contributors @joshtriplett and @lerouxrgd, and returning
contributor @teozkr, for contributing to this release!

[tokio-rs#1460]: tokio-rs#1460
[tokio-rs#1483]: tokio-rs#1483
[tokio-rs#1463]: tokio-rs#1463
[tokio-rs#1453]: tokio-rs#1453
[tokio-rs#1498]: tokio-rs#1498
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants