Documentation
¶
Overview ¶
Package telemetry is the single seam between bones command code and any OpenTelemetry tracer. Default builds (no -tags=otel) get a zero-cost no-op; `go build -tags=otel` swaps in the real OTel-backed implementation.
This file holds the build-tag-free types every caller speaks: Attr (a typed key/value pair built via String/Int/Bool) and EndFunc (the deferred cleanup returned by RecordCommand). The two RecordCommand implementations live in telemetry_default.go and telemetry_otel.go respectively.
Both implementations live in this package so the OTel branch can read Attr's unexported fields directly without exposing them to callers.
Index ¶
- func Dataset() string
- func Disable() error
- func Enable() error
- func Endpoint() string
- func FirstRunNotice(w io.Writer, endpoint string)
- func Init(ctx context.Context, version, commit string) func(context.Context)
- func InstallID() string
- func IsEnabled() bool
- func IsOptedOut() bool
- func OptOutPath() string
- func StatusReason() string
- func WorkspaceHash(path string) string
- type Attr
- type EndFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Dataset ¶ added in v0.5.0
func Dataset() string
Dataset returns the Axiom dataset baked into this build, or "" on source builds (or self-host overrides where the dataset concept doesn't apply). Surfaces in `bones doctor` so an operator can confirm which Axiom dataset their spans land in.
func Disable ¶ added in v0.5.0
func Disable() error
Disable writes the opt-out marker, idempotent. Returns nil if the marker already exists. Wraps any I/O failure with verb-shaped context so the CLI can print it directly.
The file content is a one-line comment explaining what it does so an operator who finds it via `find ~ -name no-telemetry` knows it was created intentionally and how to undo.
func Enable ¶ added in v0.5.0
func Enable() error
Enable removes the opt-out marker. Idempotent — a missing file is not an error since the post-condition (telemetry not opted-out via file) holds either way.
func Endpoint ¶ added in v0.5.0
func Endpoint() string
Endpoint returns the OTLP URL the resolved config exports to, or "" when telemetry is off. Lets the doctor surface print the concrete URL without re-deriving the resolution.
func FirstRunNotice ¶ added in v0.5.0
FirstRunNotice prints a one-line notice to w if the operator has not yet acknowledged that telemetry is on. The acknowledgment is recorded at ~/.bones/telemetry-acknowledged so subsequent invocations stay quiet. Removing that file (or pointing $HOME elsewhere) re-arms the notice.
Always loud, never silent: the notice is the operator's signal that data will leave their machine. If the ack file can't be written, the notice still prints — better to nag than to silently export.
func Init ¶ added in v0.5.0
Init configures the telemetry exporter and returns a shutdown function the caller (typically cmd/bones/main.go) should defer to flush in-flight spans before exit.
In default builds Init is a no-op and returns a no-op shutdown. In `-tags=otel` builds Init reads BONES_TELEMETRY and BONES_OTEL_ENDPOINT env vars; if both are set, an OTLP HTTP exporter is wired and the global tracer provider is replaced.
Init never returns a fatal error — telemetry is opt-in and must not block or fail bones operations. Configuration errors are logged to stderr and the no-op shutdown is returned in their place.
func InstallID ¶ added in v0.5.0
func InstallID() string
InstallID returns the opaque per-install identifier from ~/.bones/install-id, generating and persisting a fresh UUIDv4 if the file does not yet exist. Returns "" on I/O error — telemetry must never block or fail a bones operation.
The ID is meaningful only to the operator's own SigNoz backend: it lets aggregations like "8% of installs hit hub-bind error in v0.4.1" be answered without identifying any individual user. Hostname, username, and path are deliberately not included anywhere.
func IsEnabled ¶ added in v0.5.0
func IsEnabled() bool
IsEnabled reports whether telemetry is currently configured to export. Reads the same env-var contract Init uses. Useful for `bones doctor` to print "telemetry: on" without re-initializing the exporter.
func IsOptedOut ¶ added in v0.5.0
func IsOptedOut() bool
IsOptedOut reports whether the persistent opt-out marker exists. Distinct from BONES_TELEMETRY=0 (which is a per-process env-var kill switch) — IsOptedOut is the durable state managed by `bones telemetry disable` / `enable`. Errors during stat (other than not-exist) return false: the operator is opted out only when we can prove the file exists, not when we can't tell either way.
func OptOutPath ¶ added in v0.5.0
func OptOutPath() string
OptOutPath returns the absolute path of the opt-out marker for this user. Returns "" if the home directory can't be resolved (rare but possible in stripped sandbox environments). Used by `bones doctor` and the `bones telemetry` verb to print a path the operator can actually look at.
func StatusReason ¶ added in v0.5.0
func StatusReason() string
StatusReason returns a human-readable explanation of the resolved on/off state. Used by `bones telemetry status` and `bones doctor` so operators see exactly why telemetry is on or off, not just the boolean.
func WorkspaceHash ¶ added in v0.5.0
WorkspaceHash returns a 12-char hex prefix of sha256(cleaned-absolute-path). Same workspace path always produces the same hash, but the path itself never reaches a telemetry exporter — so spans can correlate across invocations of the same workspace without leaking the username, project name, or directory layout.
Empty input returns "" (callers can drop the attr rather than emit a hash of nothing).
Types ¶
type Attr ¶
type Attr struct {
// contains filtered or unexported fields
}
Attr is a typed key/value pair attached to a recorded command. Construct values via String, Int, or Bool — the zero value is intentionally useless so unsupported types fail at the constructor rather than silently flowing into the OTel branch.
type EndFunc ¶
EndFunc finalizes a span started by RecordCommand. Pass the operation's terminal error (or nil on success) and any outcome attributes computed during the call (counts, refusal flags, etc.) — the OTel branch attaches the attrs and records the error before closing the span. Always call exactly once — typically via `defer func(){ end(err) }()` against a named-return `err`.
func RecordCommand ¶
RecordCommand is the no-op default. With -tags=otel the implementation in telemetry_otel.go takes over and starts a real span. Returning the same ctx (rather than a derived child) keeps the no-op observably equivalent to "no instrumentation present at all."
Source Files