Documentation
¶
Index ¶
- Constants
- func ContextProbeReport(ctx context.Context, skipFrames int)
- func ForceFlush(timeout time.Duration)
- func OpenTelemetryInit(ctx context.Context) (context.Context, error)
- func SetSpanError(span trace.Span, input any)
- func StringSlice[E fmt.Stringer](span trace.Span, items iter.Seq[E]) []string
- func Tracer() trace.Tracer
- type ContextProbe
Constants ¶
const DefaultServiceName = "OpenTofu CLI"
DefaultServiceName is the default service name to use if not specified in the environment
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.
const ServiceNameEnvVar = "OTEL_SERVICE_NAME"
ServiceNameEnvVar is the standard OpenTelemetry environment variable for specifying the service name
Variables ¶
This section is empty.
Functions ¶
func ContextProbeReport ¶
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 ¶
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 OpenTelemetryInit ¶
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 SetSpanError ¶
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 StringSlice ¶
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))),
)
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 ¶
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.
Source Files
Directories