Documentation
¶
Overview ¶
Package tracing provides OpenTelemetry SDK tracing initialization for HyperShift components. It configures a TracerProvider that exports spans via OTLP when a collector endpoint is provided, and falls back to a no-op provider otherwise. This lets the same binary run with or without a collector sidecar.
Index ¶
- Constants
- func CorrelationAttrs(value string) []attribute.KeyValue
- func InitProvider(ctx context.Context, serviceName string, cfg Config) (shutdown func(context.Context) error, err error)
- func ReconcileSubSpan(name string) string
- func SetCorrelationAttrs(csv string)
- func SpanLinkFromAnnotations(annotations map[string]string) trace.Link
- func StartSpan(ctx context.Context, t trace.Tracer, name string, ...) (context.Context, trace.Span)
- func Tracer(name string) trace.Tracer
- type Config
Constants ¶
const ( // SpanHostedClusterReconcile is the root span for each HostedCluster reconcile loop. SpanHostedClusterReconcile = "HostedCluster.Reconcile" // SpanHostedClusterDelete is the root span for HostedCluster deletion handling. SpanHostedClusterDelete = "HostedCluster.Delete" // SpanNodePoolReconcile is the root span for each NodePool reconcile loop. SpanNodePoolReconcile = "NodePool.Reconcile" )
Span names for top-level controller operations.
const ( // AttrHostedClusterName identifies the HostedCluster resource name. AttrHostedClusterName = attribute.Key("hostedcluster.name") // AttrHostedClusterNamespace identifies the HostedCluster resource namespace. AttrHostedClusterNamespace = attribute.Key("hostedcluster.namespace") // AttrHostedClusterPlatform identifies the infrastructure platform type (AWS, Azure, etc.). AttrHostedClusterPlatform = attribute.Key("hostedcluster.platform") // AttrHostedClusterInfraID is the globally unique infrastructure identifier for the cluster (spec.infraID). AttrHostedClusterInfraID = attribute.Key("hostedcluster.infraID") // AttrHostedClusterClusterID is the immutable RFC4122 UUID for the cluster (spec.clusterID). AttrHostedClusterClusterID = attribute.Key("hostedcluster.clusterID") // AttrHostedClusterDeleting indicates the HostedCluster has a deletion timestamp set. AttrHostedClusterDeleting = attribute.Key("hostedcluster.deleting") // AttrNodePoolName identifies the NodePool resource name. AttrNodePoolName = attribute.Key("nodepool.name") // AttrNodePoolNamespace identifies the NodePool resource namespace. AttrNodePoolNamespace = attribute.Key("nodepool.namespace") // AttrNodePoolClusterName is the HostedCluster name this NodePool belongs to. AttrNodePoolClusterName = attribute.Key("nodepool.clusterName") // AttrNodePoolReleaseImage is the OCP release image the NodePool targets. AttrNodePoolReleaseImage = attribute.Key("nodepool.releaseImage") // AttrNodePoolDeleting indicates the NodePool has a deletion timestamp set. AttrNodePoolDeleting = attribute.Key("nodepool.deleting") // AttrReconcileOperation names the sub-operation within a reconcile loop. AttrReconcileOperation = attribute.Key("reconcile.operation") // AttrReconcileCritical indicates the operation is critical and blocks downstream work on failure. AttrReconcileCritical = attribute.Key("reconcile.critical") // AttrReconcileBlocked indicates the operation was skipped due to a prior critical failure. AttrReconcileBlocked = attribute.Key("reconcile.blocked") )
Span attribute keys for HyperShift tracing. Shared across controllers and consumed by Grafana dashboards and TraceQL queries.
const ( // TraceparentAnnotation is the W3C Trace Context annotation key used by // CS to inject trace context into ManifestWork payloads. TraceparentAnnotation = "traceparent" // TracestateAnnotation is the optional W3C tracestate companion. TracestateAnnotation = "tracestate" )
Variables ¶
This section is empty.
Functions ¶
func CorrelationAttrs ¶
CorrelationAttrs returns span attributes for cross-service correlation, one per configured key, all set to the given value. Returns nil when no keys are configured.
func InitProvider ¶
func InitProvider(ctx context.Context, serviceName string, cfg Config) (shutdown func(context.Context) error, err error)
InitProvider initializes the global TracerProvider. When cfg.Endpoint is non-empty it creates an OTLP/gRPC exporter targeting that endpoint; otherwise the provider is a no-op and the returned shutdown function does nothing.
The caller must invoke the returned shutdown function on process exit to flush pending spans.
func ReconcileSubSpan ¶
ReconcileSubSpan returns a span name for a named sub-operation within a reconcile loop (e.g. "HostedCluster.Reconcile.EnsureKubeconfig").
func SetCorrelationAttrs ¶
func SetCorrelationAttrs(csv string)
SetCorrelationAttrs configures span attribute keys for cross-service correlation from a comma-separated list. Called by InitProvider.
func SpanLinkFromAnnotations ¶
SpanLinkFromAnnotations extracts W3C trace context from Kubernetes resource annotations and returns a trace.Link suitable for use with trace.WithLinks(). If no traceparent annotation is present, it returns an empty link with an invalid SpanContext.
func StartSpan ¶
func StartSpan(ctx context.Context, t trace.Tracer, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartSpan is a convenience wrapper that starts a child span from the given context. It returns the updated context and span. The caller must call span.End() when the operation completes.
Types ¶
type Config ¶
type Config struct {
// Endpoint is the OTLP/gRPC collector endpoint. Empty disables tracing.
Endpoint string
// Sampler is the trace sampler type (e.g. parentbased_always_on, traceidratio).
Sampler string
// SamplerArg is the sampler argument (e.g. ratio 0.0-1.0).
SamplerArg string
// CorrelationAttrs is a comma-separated list of span attribute names for
// cross-service correlation. Each configured key is set to the cluster's
// infraID on every reconcile span. For example, ROSA sets "cs.cluster.id"
// to correlate with Cluster Service traces. Empty disables correlation.
CorrelationAttrs string
}
Config holds tracing configuration passed from operator flags.
Source Files