Skip to content

x/telemetry: give guidance about purpose, API stability, and support #65642

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.

Sign up for GitHub

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

Jump to bottom
Closed
adonovan opened this issue Feb 9, 2024 · 5 comments
Closed

x/telemetry: give guidance about purpose, API stability, and support #65642

adonovan opened this issue Feb 9, 2024 · 5 comments
Assignees
@findleyr
Labels
FrozenDueToAge telemetry x/telemetry issues
Milestone
Unreleased

Comments

@adonovan
Copy link
Member

adonovan commented Feb 9, 2024 •
edited
Loading

It is unclear to a reader stumbling upon the x/telemetry repo what it does, who it is for, and what a user can expect in terms of support or API stability. I think the answers are, respectively:

  • The x/telemetry repo defines a system for counting events and reporting crashes in tools provided and maintained by the Go project, to help us improve those tools. See [link] for the design.
  • Data collection is off by default. Please enable telemetry to help us find and fix bugs. See [link] for privacy policy.
  • Telemetry has no effect on applications built using Go tools.
  • Telemetry is not intended for use in programs other than those written by the Go team, and we do not support such uses. However you are free to use the code as the basis for your own telemetry system as permitted by the license.
  • Although the Go project strives to avoid breaking changes to public APIs, given that this is not a supported public API we make no guarantees of interface stability.

We should document the actual answers in the root README.
@gopherbot gopherbot added the telemetry x/telemetry issues label Feb 9, 2024
@gopherbot gopherbot added this to the Unreleased milestone Feb 9, 2024
@robpike
Copy link
Contributor

robpike commented Feb 9, 2024

Related to #36238? Maybe even a dup, made less obvious by the moves that happened since then.

@adonovan
Copy link
Member Author

adonovan commented Feb 9, 2024

Related to #36238? Maybe even a dup, made less obvious by the moves that happened since then.

The x/tools/internal/event (nee telemetry) package is in fact unrelated to the x/telemetry repo--though I had to dig to confirm this: I wasn't even aware of its old name. Though clearly overengineered^Wintended to integrate with standard protocols like OpenTelemetry, it has to my knowledge never been used as part of a distributed system; it just reports counters visible in the the localhost web server. But its current comment and API seem reasonable: https://pkg.go.dev/golang.org/x/tools/internal/event

@robpike
Copy link
Contributor

robpike commented Feb 9, 2024

I still think the docs there are insufficient, but I'll make that comment on that issue. Thanks for clarifying this confusing situation.

@findleyr
Copy link
Member

@adonovan thanks for filing this issue -- agree on all counts. I'll update the README.

@findleyr findleyr self-assigned this Feb 11, 2024
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/567840 mentions this issue: README.md: give guidance about purpose, API stability, and support

@golang golang locked and limited conversation to collaborators Feb 28, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@findleyr findleyr

Labels
FrozenDueToAge telemetry x/telemetry issues
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
4 participants
@robpike @adonovan @gopherbot @findleyr