Documentation
¶
Index ¶
- Constants
- func InitOTel(cfg ObservabilityConfig) error
- func NewSpanAttributePolicyProcessor(policy *SpanAttributePolicy) sdktrace.SpanProcessor
- func ShutdownOTel(ctx context.Context) error
- func ShutdownWithDefaultTimeout() error
- type OTLPExporterConfig
- type ObservabilityConfig
- type ResourceAttributes
- type SpanAttributePolicy
- type SpanAttributeViolation
- type SpanAttributeViolationReason
- type TracesConfig
Constants ¶
const ( // DefaultAttributeCardinalityLimit is the maximum number of unique values // allowed per custom span attribute key before values are redacted. DefaultAttributeCardinalityLimit = 1000 // AttributeRedactedValue is used when an attribute key is denied for PII/sensitive content. AttributeRedactedValue = "[REDACTED]" // AttributeDisallowedValue is used when an attribute key is not in the allow-list. AttributeDisallowedValue = "[DISALLOWED]" // AttributeHighCardinalityValue is used once cardinality guardrails are exceeded. AttributeHighCardinalityValue = "[HIGH_CARDINALITY]" )
const ( ConfigOtelExporterOtlpEndpoint = "observability.exporter.endpoint" ConfigOtelExporterOtlpProtocol = "observability.exporter.protocol" ConfigOtelTracesSampler = "observability.traces.sampler" ConfigOtelTracesSamplerArg = "observability.traces.samplerArg" )
const ( ResourceAttributeServiceName = "service.name" ResourceAttributeServiceNamespace = "service.namespace" ResourceAttributeServiceVersion = "service.version" ResourceAttributeServiceInstance = "service.instance.id" )
Variables ¶
This section is empty.
Functions ¶
func InitOTel ¶
func InitOTel(cfg ObservabilityConfig) error
InitOTel initializes the global OpenTelemetry tracer provider with the given configuration. This function is fail-open: if the OTLP collector is unreachable, it logs the error but returns success to allow the service to start. The tracer provider is set globally via otel.SetTracerProvider() and W3C propagators are registered via otel.SetTextMapPropagator().
Returns an error only if configuration is invalid or critical setup fails (not collector reachability).
func NewSpanAttributePolicyProcessor ¶
func NewSpanAttributePolicyProcessor(policy *SpanAttributePolicy) sdktrace.SpanProcessor
NewSpanAttributePolicyProcessor creates a span processor that sanitizes span attributes at span start using the configured policy and applies OnEnd guardrails for attributes added after span start.
Constraint: OTel SDK processors cannot mutate attributes on ended spans. Therefore, attributes set via span.SetAttributes(...) after OnStart cannot be rewritten at processor level. OnEnd logs policy violations as an operational guardrail.
func ShutdownOTel ¶
ShutdownOTel gracefully shuts down the global tracer provider, flushing any pending spans to the collector.
func ShutdownWithDefaultTimeout ¶
func ShutdownWithDefaultTimeout() error
ShutdownWithDefaultTimeout gracefully shuts down the global tracer provider with a default timeout. The default timeout is 5s.
Types ¶
type OTLPExporterConfig ¶
type ObservabilityConfig ¶
type ObservabilityConfig struct {
Enabled bool
Exporter OTLPExporterConfig
Traces TracesConfig
Resource ResourceAttributes
}
func (*ObservabilityConfig) ApplyResourceDefaults ¶
func (c *ObservabilityConfig) ApplyResourceDefaults(serviceName string)
func (ObservabilityConfig) Validate ¶
func (c ObservabilityConfig) Validate() error
type ResourceAttributes ¶
type ResourceAttributes struct {
// Service name is the name of the service.
// Required attribute, with key `service.name`.
ServiceName string
// Service version is the version of the service.
// Required attribute, with key `service.version`.
ServiceVersion string
// Service instance is a unique identifier for the service instance.
// Required attribute, with key `service.instance.id`.
ServiceInstance string
// Extra attributes if specified will be added to the resource attributes.
// These can be used to add additional metadata about the service instance.
Extra map[string]string
}
ResourceAttributes define the required OpenTelemetry service identity contract.
type SpanAttributePolicy ¶
type SpanAttributePolicy struct {
// contains filtered or unexported fields
}
SpanAttributePolicy defines guardrails for span attribute keys and values.
Policy summary:
- Allow-list: rpc.*, http.*, net.*, server.*, service.*, armada.*, trace_id, span_id
- Deny-list: explicit sensitive keys and key-name patterns (password/secret/token/api_key/apikey)
- Cardinality: custom (non-standard) keys capped at DefaultAttributeCardinalityLimit unique values
Important: OTel SDK span processors cannot delete already-set attributes from an active span. To prevent raw PII leakage, denied/disallowed keys are overwritten with marker values.
func NewDefaultSpanAttributePolicy ¶
func NewDefaultSpanAttributePolicy() *SpanAttributePolicy
NewDefaultSpanAttributePolicy returns the default attribute policy for Armada traces.
func (*SpanAttributePolicy) SanitizeForSpan ¶
func (p *SpanAttributePolicy) SanitizeForSpan(attrs []attribute.KeyValue) []attribute.KeyValue
SanitizeForSpan returns attributes safe for emission by applying deny-list, allow-list, and cardinality guardrails.
This function only sanitizes the attributes passed to it. In the OTel SDK processor model, OnStart can sanitize initial attributes, but attributes added later via span.SetAttributes(...) cannot be rewritten at OnEnd. See ViolationsForSpan/OnEnd guardrails for post-start detection.
func (*SpanAttributePolicy) ViolationsForSpan ¶
func (p *SpanAttributePolicy) ViolationsForSpan(attrs []attribute.KeyValue) []SpanAttributeViolation
ViolationsForSpan returns policy violations present in the provided attributes.
Use this as a guardrail for ended spans where mutation is no longer possible, e.g. to detect attributes that were added after OnStart and therefore bypassed processor-time sanitization.
type SpanAttributeViolation ¶
type SpanAttributeViolation struct {
Key string
Reason SpanAttributeViolationReason
}
type SpanAttributeViolationReason ¶
type SpanAttributeViolationReason string
const ( SpanAttributeViolationDenied SpanAttributeViolationReason = "denied" SpanAttributeViolationDisallowed SpanAttributeViolationReason = "disallowed" SpanAttributeViolationHighCardinality SpanAttributeViolationReason = "high_cardinality" )
type TracesConfig ¶
type TracesConfig struct {
// Sampler controls root trace sampling policy.
// Supported values:
// - always_on
// - always_off
// - trace_id_ratio
// - parent_based_trace_id_ratio
Sampler string
// SamplerArg is the sampler parameter used by ratio samplers.
// Valid range for ratio samplers is 0.0 to 1.0.
SamplerArg float64
}
Source Files