Documentation
¶
Overview ¶
Package attributes provides expression evaluation and validation for custom attributes, trace IDs, and parent span IDs.
Values are treated as literal strings by default. To use a dynamic expression evaluated against process metadata, prefix the value with "expr:".
Examples:
"my-service" → literal string "my-service" "expr:env[\"SVC\"]" → evaluates env["SVC"] at runtime
Expressions use the expr language with the following environment:
- env: map[string]string of process environment variables
- args: []string of command-line arguments
- cmdline: string of the full command line
Three evaluators:
- Evaluator: Evaluates custom attribute values (literal or expr)
- TraceIDEvaluator: Evaluates and validates trace ID values (32 hex chars)
- ParentIDEvaluator: Evaluates and validates parent span ID values (16 hex chars)
Invalid trace IDs are automatically hashed with SHA-256 to produce valid IDs. Invalid parent IDs result in a null parent (zero span ID).
Index ¶
Constants ¶
const ( SourceUnconfigured = "unconfigured" SourceLiteral = "literal" SourceExpr = "expr" )
Source values for TraceIDResolution and ParentIDResolution.
const ( ValidationNone = "" // unconfigured ValidationValid = "valid" // parsed as proper hex ID ValidationHashed = "hashed" // invalid hex, SHA-256 fallback used (both trace ID and parent ID) ValidationInvalid = "invalid" // deprecated: parent ID now uses ValidationHashed like trace ID ValidationError = "error" // expression evaluation failed ValidationEmptyFallback = "empty_fallback" // expr evaluated to empty string; random ID assigned to avoid sha256("") collision )
Validation values.
Variables ¶
This section is empty.
Functions ¶
func ParseExprPrefix ¶ added in v0.4.0
ParseExprPrefix checks whether s starts with "expr:" and returns the expression body and a boolean indicating expression mode. If s does not start with "expr:", it is treated as a literal value.
Types ¶
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator handles compilation and evaluation of custom attribute values. Values without the "expr:" prefix are used as literal strings. Values with the "expr:" prefix are compiled and evaluated at runtime.
func NewEvaluator ¶
func NewEvaluator(customAttrs []config.CustomAttribute, skipEmptyValues bool) (*Evaluator, error)
NewEvaluator creates a new attribute evaluator. Literal values (no "expr:" prefix) are stored as-is. Expressions ("expr:" prefix) are pre-compiled; invalid ones are warned and skipped. When skipEmptyValues is true, attributes that evaluate to an empty string are omitted from the result.
func (*Evaluator) AnyExprAttributeNonEmpty ¶ added in v0.8.3
func (e *Evaluator) AnyExprAttributeNonEmpty(metadata *procmeta.ProcessMetadata) bool
AnyExprAttributeNonEmpty returns true iff at least one attribute declared with the "expr:" prefix evaluates to a non-empty string against metadata. Literal attributes are ignored — they resolve non-empty unconditionally and so carry no signal about whether env is context-ful yet.
func (*Evaluator) EvaluateCustomAttributes ¶
func (e *Evaluator) EvaluateCustomAttributes(metadata *procmeta.ProcessMetadata) ([]attribute.KeyValue, error)
EvaluateCustomAttributes evaluates custom attribute values for a given process metadata. Literal attributes are returned as-is. Expression attributes are evaluated at runtime.
func (*Evaluator) HasExprAttributes ¶ added in v0.8.3
HasExprAttributes reports whether any attribute was declared with the "expr:" prefix. A rule with no expr-backed attributes cannot use attribute resolution as a readiness signal — each literal attribute resolves non-empty unconditionally.
type ParentIDEvaluator ¶
type ParentIDEvaluator struct {
// contains filtered or unexported fields
}
ParentIDEvaluator handles evaluation and validation of parent span ID values. Without the "expr:" prefix, the value is treated as a literal span ID string. With the "expr:" prefix, the value is compiled and evaluated at runtime.
func NewParentIDEvaluator ¶
func NewParentIDEvaluator(value string) (*ParentIDEvaluator, error)
NewParentIDEvaluator creates a new parent ID evaluator. Empty string → no parent (zero span ID). "expr:..." → compile expression; on failure, warn and behave as empty. Otherwise → treat as literal span ID string.
func (*ParentIDEvaluator) EvaluateAndValidate ¶
func (e *ParentIDEvaluator) EvaluateAndValidate(metadata *procmeta.ProcessMetadata) (trace.SpanID, []attribute.KeyValue, ParentIDResolution, error)
EvaluateAndValidate evaluates the parent-id value and validates the result. Returns the parent span ID, any warnings to attach to the span, a Resolution describing how the ID was derived (for debug attributes), and an error. If unconfigured, returns zero span ID (no parent). If the value is not valid 16-char hex, it is SHA-256 hashed to produce a deterministic SpanID.
type ParentIDResolution ¶ added in v0.6.0
type ParentIDResolution struct {
Source string // one of SourceUnconfigured, SourceLiteral, SourceExpr
Expression string // expr body (only when Source == SourceExpr)
ResolvedValue string // post-evaluation, pre-validation string (only when Source != SourceUnconfigured)
Validation string // one of ValidationNone, ValidationValid, ValidationHashed, ValidationError
Error string // non-empty when Validation == ValidationError
}
ParentIDResolution records how a parent span ID was derived, for debugging.
type TraceIDEvaluator ¶
type TraceIDEvaluator struct {
// contains filtered or unexported fields
}
TraceIDEvaluator handles evaluation and validation of trace ID values. Without the "expr:" prefix, the value is treated as a literal trace ID string. With the "expr:" prefix, the value is compiled and evaluated at runtime.
func NewTraceIDEvaluator ¶
func NewTraceIDEvaluator(value string) (*TraceIDEvaluator, error)
NewTraceIDEvaluator creates a new trace ID evaluator. Empty string → SDK auto-generates random trace IDs. "expr:..." → compile expression; on failure, warn and behave as empty. Otherwise → treat as literal trace ID string.
func (*TraceIDEvaluator) EvaluateAndValidate ¶
func (e *TraceIDEvaluator) EvaluateAndValidate(metadata *procmeta.ProcessMetadata) (trace.TraceID, []attribute.KeyValue, TraceIDResolution, error)
EvaluateAndValidate evaluates the trace-id value and validates the result. Returns the trace ID, any warnings to attach to the span, a Resolution describing how the ID was derived (for debug attributes), and an error. If unconfigured, returns a zero trace ID (caller should generate random).
type TraceIDResolution ¶ added in v0.6.0
type TraceIDResolution struct {
Source string // one of SourceUnconfigured, SourceLiteral, SourceExpr
Expression string // expr body (only when Source == SourceExpr)
ResolvedValue string // post-evaluation, pre-validation string (only when Source != SourceUnconfigured)
Validation string // one of ValidationNone, ValidationValid, ValidationHashed, ValidationError
Error string // non-empty when Validation == ValidationError
}
TraceIDResolution records how a trace ID was derived, for debugging.
Source Files