tracing

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 8, 2026 License: MPL-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const AggregateSpanPrefix = "Aggregate: "

AggregateSpanPrefix starts the name of every summary span; the rest is the name the members' own spans would have had.

View Source 
const DefaultDetailBudget = 2000

DefaultDetailBudget is the auto mode budget when DetailBudgetEnvVar is unset.

View Source 
const DefaultServiceName = "OpenTofu CLI"

DefaultServiceName is the default service name to use if not specified in the environment

View Source 
const DetailBudgetEnvVar = "CHOUDOUFU_TRACE_SPAN_BUDGET"

DetailBudgetEnvVar is the per-walk detail span budget for auto mode.

View Source 
const DetailModeEnvVar = "CHOUDOUFU_TRACE_DETAIL"

DetailModeEnvVar selects the detail mode: "full", "aggregate" or "auto".

View Source 
const MaxAggregateSpans = 256

MaxAggregateSpans bounds how many summary spans one walk's Emit writes. The smallest groups beyond it are folded into one more summary span named with the "other" group.

View Source 
const OTELExporterEnvVar = "OTEL_TRACES_EXPORTER"

OTELExporterEnvVar is the env var that should be used to instruct opentofu which exporter to use If this environment variable is set to "otlp" when running OpenTofu CLI then we'll enable an experimental OTLP trace exporter.

View Source 
const ServiceNameEnvVar = "OTEL_SERVICE_NAME"

ServiceNameEnvVar is the standard OpenTelemetry environment variable for specifying the service name

Variables

This section is empty.

Functions

func ChildProcessEnv added in v0.22.0 

func ChildProcessEnv(ctx context.Context, base []string) []string

ChildProcessEnv returns base with the span in ctx as the child's trace parent. TRACEPARENT and TRACESTATE already in base (inherited from whoever started this process) are replaced, so the child nests under this process's span rather than beside it. When ctx carries no valid span, base comes back unchanged.

func ContextProbeReport 

func ContextProbeReport(ctx context.Context, skipFrames int)

ContextProbeReport notifies the ContextProbe in the given context, if any, that its caller has been called.

skipFrames is the number of callers to skip when deciding the name of the caller. Zero means to record the direct caller of ContextProbeReport.

When called with a context that does not have a ContextProbe this does only the minimum work required to determine that there is no probe and immediately returns. The overhead is small, but there is still some overhead and so this function should not be called from functions used in tight loops but is okay to leave in normal codepaths otherwise.

func ForceFlush 

func ForceFlush(timeout time.Duration)

ForceFlush ensures that all spans are exported to the collector before the application terminates. This is particularly important for CLI applications where the process exits immediately after the operation.

This should be called before the application terminates to ensure all spans are exported properly.

func MarkRefused added in v0.22.0 

func MarkRefused(span Span, step, reason string)

MarkRefused records on span that the step it covers refused to go on: a wave gate, a set digest mismatch, a resume that does not match. step is a short fixed name for the gate ("digest", "resume", "approval", ...) and reason a fixed phrase, never a resource attribute value. The span's status becomes Error, so a trace viewer shows the refusal at the step itself.

func NewTestTracer added in v0.22.0 

func NewTestTracer(t testing.TB) *tracetest.SpanRecorder

NewTestTracer turns tracing on for the rest of the test with an in-memory recorder as the global tracer provider, and restores the previous state at cleanup. Read the finished spans with recorder.Ended().

func OpenTelemetryInit 

func OpenTelemetryInit(ctx context.Context) (context.Context, error)

OpenTelemetryInit initializes the optional OpenTelemetry exporter.

By default, we don't export telemetry information at all, since OpenTofu is a CLI tool, and so we don't assume we're running in an environment with a telemetry collector available.

However, for those running OpenTofu in automation we allow setting the standard OpenTelemetry environment variable OTEL_TRACES_EXPORTER=otlp to enable an OTLP exporter, which is in turn configured by all the standard OTLP exporter environment variables: 

https://opentelemetry.io/docs/specs/otel/protocol/exporter/#configuration-options

We don't currently support any other telemetry export protocols, because OTLP has emerged as a de-facto standard and each other exporter we support means another relatively-heavy external dependency. OTLP happens to use protocol buffers and gRPC, which OpenTofu would depend on for other reasons anyway.

Returns the context with trace context extracted from environment variables if TRACEPARENT is set.

func OutgoingGRPCContext added in v0.22.0 

func OutgoingGRPCContext(ctx context.Context) context.Context

OutgoingGRPCContext returns ctx with the span in ctx set as the "traceparent" (and "tracestate") of outgoing gRPC metadata. When ctx carries no valid span, ctx comes back unchanged.

func ParentOf added in v0.22.0 

func ParentOf(spans []sdktrace.ReadOnlySpan, s sdktrace.ReadOnlySpan) sdktrace.ReadOnlySpan

ParentOf returns the ended span that is s's parent, or nil.

func ProviderCallSpanName added in v0.22.0 

func ProviderCallSpanName(service, method string) string

ProviderCallSpanName is the span name for a provider call: "<service>/<method>", as the OpenTelemetry RPC conventions name a gRPC client span.

func SetDetailForTest added in v0.22.0 

func SetDetailForTest(t testing.TB, mode DetailMode, budget int)

SetDetailForTest sets the detail mode and budget until the test ends. Pair it with NewTestTracer, whose cleanup restores the previous values.

func SetSpanError 

func SetSpanError(span trace.Span, input any)

SetSpanError sets the error or diagnostic information on the span. It accepts an error, a string, or a diagnostics object. It also sets the span status to Error and records the error or message.

func SpanAttr added in v0.22.0 

func SpanAttr(s sdktrace.ReadOnlySpan, key string) (attribute.Value, bool)

SpanAttr returns the value of the named attribute on s, and whether it was set.

func SpanAttributes 

func SpanAttributes(attrs ...attribute.KeyValue) trace.SpanStartEventOption

SpanAttributes wraps trace.WithAttributes just so that we can minimize how many different OpenTofu packages directly import the OpenTelemetry packages, because we tend to need to control which versions we're using quite closely to avoid dependency hell.

func SpanFromContext 

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the trace span asssociated with the given context, or nil if there is no associated span.

This is a wrapper around trace.SpanFromContext just to centralize all of our imports of OpenTelemetry packages into our tracing packages, to help avoid dependency hell.

func SpansNamed added in v0.22.0 

func SpansNamed(spans []sdktrace.ReadOnlySpan, name string) []sdktrace.ReadOnlySpan

SpansNamed returns the ended spans with the given name, in end order.

func StringSlice 

func StringSlice[E fmt.Stringer](span trace.Span, items iter.Seq[E]) []string

StringSlice takes a sequence of any type that implements fmt.Stringer and returns a slice containing the results of calling the String method on each item in that sequence.

If the given span is not recording then this immediately returns nil without consuming the iterator at all.

Use slices.Values to use the elements of an existing slice. For example: 

span.SetAttributes(
    otelAttr.StringSlice("example", tracing.StringSlice(span, slices.Values(opts.Targets))),
)

func TraceEnv added in v0.22.0 

func TraceEnv(ctx context.Context) []string

TraceEnv returns "TRACEPARENT=..." (and "TRACESTATE=..." when there is a trace state) for the span in ctx, or nil when ctx carries no valid span.

func TraceIDOf added in v0.22.0 

func TraceIDOf(ctx context.Context) trace.TraceID

TraceIDOf is the trace ID of the span in ctx, for tests that compare traces.

func Tracer 

func Tracer() trace.Tracer

Types

type ContextProbe 

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

ContextProbe is a testing helper to allow tests to check whether context.Context values are being propagated correctly to various downstream functions where context value continuity is important for certain functionality, like tracing. (It's in this package because tracing is our primary motivation, but could potentially be used for other context-value-related situations too.)

To use it, first call NewContextProbe from the test that wants to verify propagation, which returns both a ContextProbe and a context.Context that carries a value referring to it. Then in the function whose functionality requires context values to reach it, call ContextProbeReport with that function's own local context to notify any active context probe that the function was called. Finally, at the end of the test call ContextProbe.ExpectReportsFrom with all of the functions that the test expects should have been able to successfully call ContextProbeReport.

func NewContextProbe 

func NewContextProbe(t testing.TB, base context.Context) (context.Context, *ContextProbe)

NewContextProbe creates a new ContextProbe and a new context (child of base) that is bound to it, so that ContextProbeReport with that context would record the call in the probe.

func (*ContextProbe) ExpectReportsFrom 

func (p *ContextProbe) ExpectReportsFrom(t testing.TB, names ...string) bool

ExpectReportsFrom generates test errors (but does not terminate the test) if any of the given function names have not yet been reported by a call to ContextProbeReport.

Returns true if no errors were generated, or false if at least one error was generated.

func (*ContextProbe) FunctionsReported 

func (p *ContextProbe) FunctionsReported() iter.Seq[string]

FunctionsReported returns an interable sequence of all of the functions that have called ContextProbeReport so far, in no particular order.

Most tests should prefer to use ContextProbe.ExpectReportsFrom so that they don't get broken by reports intended for use by other tests, but this can be useful as a temporary addition to a test for debugging purposes, or to find out how the Go runtime describes a particular function of interest.

type DetailKind added in v0.22.0 

type DetailKind string

DetailKind names what a detail span is about. It is the choudoufu.aggregate.kind attribute of a summary span. 

const (
	DetailResourceInstance DetailKind = "resource_instance"
	DetailProviderCall     DetailKind = "provider_call"
)

type DetailMode added in v0.22.0 

type DetailMode int

DetailMode is one of the three detail modes. 

const (
	DetailAuto DetailMode = iota
	DetailFull
	DetailAggregate
)

func CurrentDetail added in v0.22.0 

func CurrentDetail() (DetailMode, int)

CurrentDetail returns the configured detail mode and auto mode budget.

func ParseDetailMode added in v0.22.0 

func ParseDetailMode(s string) (DetailMode, bool)

ParseDetailMode reads a mode name. An empty string is auto.

func (DetailMode) String added in v0.22.0 

func (m DetailMode) String() string

type DetailRecorder added in v0.22.0 

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

DetailRecorder holds one graph walk's detail span count and its groups.

func DetailRecorderFromContext added in v0.22.0 

func DetailRecorderFromContext(ctx context.Context) *DetailRecorder

DetailRecorderFromContext returns the context's recorder, or nil.

func WithDetailRecorder added in v0.22.0 

func WithDetailRecorder(ctx context.Context) (context.Context, *DetailRecorder)

WithDetailRecorder returns a context carrying a fresh recorder for one walk, using the configured mode and budget. Call DetailRecorder.Emit with the walk's own context when the walk ends.

func (*DetailRecorder) DetailedCount added in v0.22.0 

func (r *DetailRecorder) DetailedCount() int

DetailedCount is how many detail spans the walk has emitted.

func (*DetailRecorder) Emit added in v0.22.0 

func (r *DetailRecorder) Emit(ctx context.Context) int

Emit writes the walk's summary spans under the span in ctx, if the mode calls for them: always in aggregate mode, in auto mode only when some detail span was counted without being emitted, never in full mode. It returns how many summary spans it wrote.

type DetailSpec added in v0.22.0 

type DetailSpec struct {
	Kind DetailKind
	// Name is the span name. Members of one group share it.
	Name string
	// Group is the aggregation key within Kind and Name, such as a resource
	// type, or a provider address and RPC method joined by a space.
	Group string
	// GroupAttrs are copied onto the group's summary span. Types, addresses
	// and method names only, never values.
	GroupAttrs []attribute.KeyValue
	// Label identifies this member in a summary's choudoufu.aggregate.slowest
	// attribute, such as a resource instance address.
	Label string
}

DetailSpec describes one detail span.

type ProviderCall added in v0.22.0 

type ProviderCall struct {
	// Service is the gRPC service, "tfplugin5.Provider" or "tfplugin6.Provider".
	Service string
	// Method is the RPC method, such as "ReadResource".
	Method string
	// Provider is the provider source address, when the caller knows it.
	Provider string
	// TypeName is the resource or data source type the call is about, if any.
	TypeName string
	// Detail puts the span under the detail budget: true for the per-resource
	// calls (ReadResource, PlanResourceChange, ApplyResourceChange,
	// ReadDataSource, ImportResourceState), false for the once-per-provider
	// calls (GetProviderSchema, ConfigureProvider), which are always emitted.
	Detail bool
}

ProviderCall describes one gRPC call into a provider plugin.

type Span 

type Span = trace.Span

Span is an alias for trace.Span just to centralize all of our direct imports of OpenTelemetry packages into our tracing packages, to help avoid dependency hell.

func StartDetail added in v0.22.0 

func StartDetail(ctx context.Context, spec DetailSpec, opts ...trace.SpanStartOption) (context.Context, Span)

StartDetail starts a detail span, or counts one, as the context's recorder and the detail mode decide. When it only counts, the returned context is the one passed in, so anything started under it nests in the enclosing span, and the returned span records nothing but still must be ended.

func StartProviderCall added in v0.22.0 

func StartProviderCall(ctx context.Context, c ProviderCall) (context.Context, Span)

StartProviderCall starts the span for a provider call and returns a context whose outgoing gRPC metadata carries the current span as "traceparent", so a provider instrumented with otelgrpc joins the trace. When the call is only counted (over the budget, or in aggregate mode), the metadata carries the enclosing span instead.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.