telemetry

Documentation

Overview

Package telemetry provides OpenTelemetry tracing for the tfctl CLI. It supports three modes: enabled (OTLP export), log (JSON to stderr), and disabled (no-op). Spans are buffered and flushed on Shutdown.

Index

• Constants
• func SetErrorHandler(handler func(error))
• func WithTelemetry(ctx context.Context, tel *Telemetry) context.Context
• type CommandInfo
• type Config
• type Mode
  • func ResolveMode(profileTelemetry string) Mode
  • func (m Mode) String() string
• type Telemetry
  • func FromContext(ctx context.Context) *Telemetry
  • func Init(ctx context.Context, cfg Config) *Telemetry
  • func (t *Telemetry) Mode() Mode
  • func (t *Telemetry) Shutdown(ctx context.Context, exitStatus int) error
  • func (t *Telemetry) StartCommand(ctx context.Context, info CommandInfo) context.Context
  • func (t *Telemetry) StartNetwork(ctx context.Context, name string, req *http.Request) (context.Context, trace.Span)

Constants

const (
	// EnvTelemetry is the environment variable controlling telemetry mode.
	EnvTelemetry = "TFCTL_TELEMETRY"

	// EnvDoNotTrack is the standard DO_NOT_TRACK environment variable.
	EnvDoNotTrack = "DO_NOT_TRACK"
)

const (

	// DefaultHostname is the default OTLP endpoint hostname:port if not overridden by env var.
	DefaultHostname = "telemetry.terraform.io:4318"
)

Functions

func SetErrorHandler

func SetErrorHandler(handler func(error))

SetErrorHandler allows overriding the default OpenTelemetry error handler. By default, errors are ignored.

func WithTelemetry

func WithTelemetry(ctx context.Context, tel *Telemetry) context.Context

WithTelemetry returns a new context with the provided telemetry.

Types

type CommandInfo

type CommandInfo struct {
	// Command is the full command path (e.g., "run start").
	Command string

	// Profile is the active profile.
	Profile *profile.Profile

	// DryRun indicates whether --dry-run was specified.
	DryRun bool

	// Debug indicates whether --debug mode is enabled or verbose logging is enabled.
	Debug bool

	// JSON indicates whether --json output mode is enabled.
	JSON bool
}

CommandInfo contains metadata about the command being executed. This struct is used instead of raw OTel attributes so that callers do not need to import OTel packages directly.

type Config

type Config struct {
	// DeviceID is the unique identifier for this CLI installation, used for telemetry purposes.
	DeviceID string

	// ProfileTelemetry is the value of the profile's telemetry setting.
	ProfileTelemetry string

	// Hostname is the profile hostname.
	Hostname string

	// Version is the CLI version string.
	Version string

	// ErrWriter is the writer for stderr output (used in log mode and for
	// emitting the traceparent header).
	ErrWriter io.Writer

	// IsTTY indicates whether the terminal is interactive.
	IsTTY bool
}

Config holds the configuration needed to initialize telemetry.

type Mode

type Mode int

Mode represents the telemetry operating mode.

const (
	// ModeEnabled exports spans via OTLP to the configured endpoint.
	ModeEnabled Mode = iota

	// ModeDisabled produces no telemetry output (no-op).
	ModeDisabled

	// ModeLog writes span data as JSON to stderr.
	ModeLog
)

func ResolveMode

func ResolveMode(profileTelemetry string) Mode

ResolveMode determines the telemetry mode from environment variables and the profile setting. Environment variables take precedence over the profile.

Resolution order:

1. DO_NOT_TRACK=true → ModeDisabled
2. TFCTL_TELEMETRY=false/disabled → ModeDisabled
3. TFCTL_TELEMETRY=log → ModeLog
4. Profile telemetry=false/disabled → ModeDisabled
5. Profile telemetry=log → ModeLog
6. Otherwise → ModeEnabled

func (Mode) String

func (m Mode) String() string

type Telemetry

type Telemetry struct {
	// contains filtered or unexported fields
}

Telemetry manages the lifecycle of OpenTelemetry tracing for a CLI invocation.

func FromContext

func FromContext(ctx context.Context) *Telemetry

FromContext extracts the telemetry from the context, or returns nil if not found.

func Init

func Init(ctx context.Context, cfg Config) *Telemetry

Init creates and configures a Telemetry instance based on the resolved mode. If telemetry is disabled, a no-op instance is returned. Errors from exporter setup are non-fatal: telemetry should never break the CLI.

func (*Telemetry) Mode

func (t *Telemetry) Mode() Mode

Mode returns the resolved telemetry mode.

func (*Telemetry) Shutdown

func (t *Telemetry) Shutdown(ctx context.Context, exitStatus int) error

Shutdown ends the active span, emits the traceparent to stderr, and flushes all buffered spans. It should be called once at the end of CLI execution.

func (*Telemetry) StartCommand

func (t *Telemetry) StartCommand(ctx context.Context, info CommandInfo) context.Context

StartCommand begins a new span representing the CLI command invocation. The span is stored internally and will be ended by Shutdown.

func (*Telemetry) StartNetwork

func (t *Telemetry) StartNetwork(ctx context.Context, name string, req *http.Request) (context.Context, trace.Span)

StartNetwork begins a new span representing an outgoing network request.