semantics

package
v0.79.0-devel Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package semantics provides a registry for semantic attribute equivalences across different tracing conventions (Datadog tracers, OpenTelemetry).

Future work (OTel semantic convention updates):

  • rpc.service is deprecated; the replacement is to include it as part of rpc.method, so the fallback system alone cannot extract the concept value. Needs different handling.
  • rpc.system is superseded by rpc.system.name; add rpc.system.name as fallback/canonical.
  • db.system is deprecated in favor of db.system.name; add db.system.name to mappings.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func LookupFloat64 

func LookupFloat64[A Accessor](r Registry, accessor A, concept Concept) (float64, bool)

LookupFloat64 returns the first matching value as float64, or (0, false) if not found or unparseable. Uses typed access (GetFloat64/GetInt64) for tags with known numeric types, and falls back to string parsing for tags with unspecified type.

func LookupInt64 

func LookupInt64[A Accessor](r Registry, accessor A, concept Concept) (int64, bool)

LookupInt64 returns the first matching value as int64, or (0, false) if not found or unparseable. Uses typed access (GetInt64/GetFloat64) for tags with known numeric types, and falls back to string parsing for tags with unspecified type.

func LookupString 

func LookupString[A Accessor](r Registry, accessor A, concept Concept) string

LookupString returns the first matching string value for the concept, or "" if not found.

Types

type Accessor 

type Accessor interface {
	GetString(key string) string
	GetInt64(key string) (int64, bool)
	GetFloat64(key string) (float64, bool)
}

Accessor provides attribute access for semantic lookups. Implementations may return not-found from GetInt64/GetFloat64 when the underlying store has no numeric type information (e.g. map[string]string).

type Concept 

type Concept string

Concept represents a semantic concept identifier (e.g., "db.system", "http.method"). 

const (
	ConceptPeerService              Concept = "peer.service"
	ConceptPeerHostname             Concept = "peer.hostname"
	ConceptPeerDBName               Concept = "peer.db.name"
	ConceptPeerDBSystem             Concept = "peer.db.system"
	ConceptPeerCassandraContactPts  Concept = "peer.cassandra.contact.points"
	ConceptPeerCouchbaseSeedNodes   Concept = "peer.couchbase.seed.nodes"
	ConceptPeerMessagingDestination Concept = "peer.messaging.destination"
	ConceptPeerMessagingSystem      Concept = "peer.messaging.system"
	ConceptPeerKafkaBootstrapSrvs   Concept = "peer.kafka.bootstrap.servers"
	ConceptPeerRPCService           Concept = "peer.rpc.service"
	ConceptPeerRPCSystem            Concept = "peer.rpc.system"
	ConceptPeerAWSS3Bucket          Concept = "peer.aws.s3.bucket"
	ConceptPeerAWSSQSQueue          Concept = "peer.aws.sqs.queue"
	ConceptPeerAWSDynamoDBTable     Concept = "peer.aws.dynamodb.table"
	ConceptPeerAWSKinesisStream     Concept = "peer.aws.kinesis.stream"
)

Peer Tags (used for stats aggregation) 

const (
	ConceptHTTPStatusCode Concept = "http.status_code"
	ConceptHTTPMethod     Concept = "http.method"
	ConceptHTTPRoute      Concept = "http.route"
	ConceptGRPCStatusCode Concept = "rpc.grpc.status_code"
	ConceptSpanKind       Concept = "span.kind"
	ConceptDDBaseService  Concept = "_dd.base_service"
)

Stats Aggregation 

const (
	ConceptServiceName     Concept = "service.name"
	ConceptResourceName    Concept = "resource.name"
	ConceptOperationName   Concept = "operation.name"
	ConceptSpanType        Concept = "span.type"
	ConceptDBSystem        Concept = "db.system"
	ConceptDBStatement     Concept = "db.statement"
	ConceptDBNamespace     Concept = "db.namespace"
	ConceptRPCSystem       Concept = "rpc.system"
	ConceptRPCService      Concept = "rpc.service"
	ConceptMessagingSystem Concept = "messaging.system"
	ConceptMessagingDest   Concept = "messaging.destination"
	ConceptDeploymentEnv   Concept = "deployment.environment"
	ConceptServiceVersion  Concept = "service.version"
	ConceptContainerID     Concept = "container.id"
	ConceptK8sPodUID       Concept = "k8s.pod.uid"
)

Service & Resource Identification 

const (
	ConceptDBQuery           Concept = "db.query"
	ConceptMongoDBQuery      Concept = "mongodb.query"
	ConceptElasticsearchBody Concept = "elasticsearch.body"
	ConceptOpenSearchBody    Concept = "opensearch.body"
	ConceptRedisRawCommand   Concept = "redis.raw_command"
	ConceptValkeyRawCommand  Concept = "valkey.raw_command"
	ConceptMemcachedCommand  Concept = "memcached.command"
	ConceptHTTPURL           Concept = "http.url"
)

Obfuscation 

const (
	ConceptMessagingOperation   Concept = "messaging.operation"
	ConceptGraphQLOperationType Concept = "graphql.operation.type"
	ConceptGraphQLOperationName Concept = "graphql.operation.name"
	ConceptFaaSInvokedProvider  Concept = "faas.invoked.provider"
	ConceptFaaSInvokedName      Concept = "faas.invoked.name"
	ConceptFaaSTrigger          Concept = "faas.trigger"
	ConceptNetworkProtocolName  Concept = "network.protocol.name"
	ConceptRPCMethod            Concept = "rpc.method"
	ConceptComponent            Concept = "component"
	ConceptLinkName             Concept = "link.name"
)

Normalization 

const (
	ConceptDDMeasured       Concept = "_dd.measured"
	ConceptDDTopLevel       Concept = "_dd.top_level"
	ConceptSamplingPriority Concept = "_sampling_priority_v1"
	ConceptOTelTraceID      Concept = "otel.trace_id"
	ConceptDDTraceIDHigh    Concept = "_dd.p.tid"
	ConceptDDPartialVersion Concept = "_dd.partial_version"
)

Sampling

type ConceptMapping 

type ConceptMapping struct {
	Canonical string    `json:"canonical"`
	Fallbacks []TagInfo `json:"fallbacks"`
}

ConceptMapping represents a semantic concept and its equivalent attributes.

type EmbeddedRegistry 

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

EmbeddedRegistry loads semantic mappings from embedded JSON.

func NewEmbeddedRegistry 

func NewEmbeddedRegistry() (*EmbeddedRegistry, error)

NewEmbeddedRegistry creates a registry from embedded JSON mappings.

func (*EmbeddedRegistry) GetAllEquivalences 

func (r *EmbeddedRegistry) GetAllEquivalences() map[Concept][]TagInfo

GetAllEquivalences returns all semantic equivalences as a map from concept to the ordered list of equivalent attribute keys.

func (*EmbeddedRegistry) GetAttributePrecedence 

func (r *EmbeddedRegistry) GetAttributePrecedence(concept Concept) []TagInfo

GetAttributePrecedence returns the ordered attribute keys for a concept.

func (*EmbeddedRegistry) Version 

func (r *EmbeddedRegistry) Version() string

Version returns the semantic registry version string.

type LookupResult 

type LookupResult struct {
	TagInfo     TagInfo
	StringValue string
}

LookupResult contains the result of a semantic attribute lookup.

func Lookup 

func Lookup[A Accessor](r Registry, accessor A, concept Concept) (LookupResult, bool)

Lookup performs a semantic attribute lookup in precedence order and returns the first match. For string-typed tags it uses GetString; for numeric-typed tags it uses the typed getter and formats the result as a string, so LookupString works correctly on any concept regardless of the underlying pdata storage type.

type OTelSpanAccessor 

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

OTelSpanAccessor provides typed access to combined span and resource attributes. The primary accessor (typically span attributes) takes precedence over the secondary.

func NewOTelSpanAccessor 

func NewOTelSpanAccessor(spanAttrs, resAttrs pcommon.Map) OTelSpanAccessor

NewOTelSpanAccessor returns an OTelSpanAccessor for OTel span and resource attributes. Span attributes take precedence over resource attributes.

func (OTelSpanAccessor) GetFloat64 

func (a OTelSpanAccessor) GetFloat64(key string) (float64, bool)

GetFloat64 returns the first found float64 value, checking primary then secondary.

func (OTelSpanAccessor) GetInt64 

func (a OTelSpanAccessor) GetInt64(key string) (int64, bool)

GetInt64 returns the first found int64 value, checking primary then secondary.

func (OTelSpanAccessor) GetString 

func (a OTelSpanAccessor) GetString(key string) string

GetString returns the first non-empty string value, checking primary then secondary.

type PDataMapAccessor 

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

PDataMapAccessor provides typed access to a pcommon.Map for semantic lookups.

func NewPDataMapAccessor 

func NewPDataMapAccessor(attrs pcommon.Map) PDataMapAccessor

NewPDataMapAccessor returns a PDataMapAccessor for a pcommon.Map.

func (PDataMapAccessor) GetFloat64 

func (a PDataMapAccessor) GetFloat64(key string) (float64, bool)

GetFloat64 returns the attribute value as float64 if the underlying pdata type is Double.

func (PDataMapAccessor) GetInt64 

func (a PDataMapAccessor) GetInt64(key string) (int64, bool)

GetInt64 returns the attribute value as int64 if the underlying pdata type is Int.

func (PDataMapAccessor) GetString 

func (a PDataMapAccessor) GetString(key string) string

GetString returns the attribute value if the underlying pdata type is Str, or "" otherwise. Numeric attributes should be accessed via GetInt64 or GetFloat64 for type safety.

type Provider 

type Provider string

Provider indicates the source of a semantic attribute definition. 

const (
	ProviderDatadog Provider = "datadog"
	ProviderOTel    Provider = "otel"
)

type Registry 

type Registry interface {
	// GetAttributePrecedence returns ordered list of attribute keys to check
	GetAttributePrecedence(concept Concept) []TagInfo

	// GetAllEquivalences returns all semantic equivalences as a map from concept to the ordered list of equivalent attribute keys.
	GetAllEquivalences() map[Concept][]TagInfo

	// Version returns the semantic registry version string.
	Version() string
}

Registry provides access to semantic equivalences for span attributes.

func DefaultRegistry 

func DefaultRegistry() Registry

DefaultRegistry returns the default semantic registry.

type StringMapAccessor 

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

StringMapAccessor adapts a map[string]string into an Accessor. GetInt64 and GetFloat64 always return not-found; numeric attributes must be registered with type "string" in mappings.json to be reachable via this accessor.

func NewStringMapAccessor 

func NewStringMapAccessor(m map[string]string) StringMapAccessor

NewStringMapAccessor returns a StringMapAccessor for a map[string]string (e.g. DD span meta).

func (StringMapAccessor) GetFloat64 

func (a StringMapAccessor) GetFloat64(_ string) (float64, bool)

GetFloat64 always returns (0, false) for the same reason as GetInt64.

func (StringMapAccessor) GetInt64 

func (a StringMapAccessor) GetInt64(_ string) (int64, bool)

GetInt64 always returns (0, false). map[string]string has no numeric type information, so numeric registry entries are intentionally skipped. Use the string-typed entry for the same attribute (e.g. http.status_code as "string" in mappings.json) instead.

func (StringMapAccessor) GetString 

func (a StringMapAccessor) GetString(key string) string

GetString returns the value for key, or "" if missing or nil map.

type TagInfo 

type TagInfo struct {
	Name     string    `json:"name"`
	Provider Provider  `json:"provider"`
	Version  string    `json:"version,omitempty"`
	Type     ValueType `json:"type,omitempty"`
}

TagInfo contains metadata about a semantic attribute and its location.

type ValueType 

type ValueType string

ValueType indicates the type of the attribute value. 

const (
	ValueTypeString  ValueType = "string"
	ValueTypeFloat64 ValueType = "float64"
	ValueTypeInt64   ValueType = "int64"
)

Source Files

View all Source files

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.