Skip to content

semconv ​

go
import "github.com/foomo/opentelemetry-go/semconv"

Custom semantic convention attribute keys and constructors. Part of the root module.

Error Attributes ​

FunctionKeyParameterReturn
ErrorType(err error)error.typeerrorattribute.KeyValue

Extends upstream semconv.ErrorType: maps context.Canceled and context.DeadlineExceeded (also when wrapped) to the stable values context.Canceled and context.DeadlineExceeded instead of their reflected type names.

GoTSRPC Attributes ​

FunctionKeyParameterReturn
GoTSRPCFunc(v string)gotsrpc.funcstringattribute.KeyValue
GoTSRPCService(v string)gotsrpc.servicestringattribute.KeyValue
GoTSRPCPackage(v string)gotsrpc.packagestringattribute.KeyValue
GoTSRPCMarshalling(v int64)gotsrpc.marshallingint64attribute.KeyValue
GoTSRPCUnmarshalling(v int64)gotsrpc.unmarshallingint64attribute.KeyValue
GoTSRPCPayload(v string)gotsrpc.payloadstringattribute.KeyValue
GoTSRPCErrorCode(v int)gotsrpc.error.codeintattribute.KeyValue
GoTSRPCErrorMessage(v string)gotsrpc.error.messagestringattribute.KeyValue
GoTSRPCErrorType(v string)gotsrpc.error.typestringattribute.KeyValue

HTTP Attributes ​

FunctionKeyParameterReturn
HTTPXRequestID(v string)http.request.idstringattribute.KeyValue
HTTPXRequestReferer(v string)http.request.refererstringattribute.KeyValue

Deprecated

http.request.* is an upstream namespace. Use semconv.HTTPRequestHeader("x-request-id", v) and semconv.HTTPRequestHeader("referer", v) from go.opentelemetry.io/otel/semconv instead.

Keel Attributes ​

FunctionKeyParameterReturn
KeelServiceType(v string)keel.service.typestringattribute.KeyValue
KeelServiceName(v string)keel.service.namestringattribute.KeyValue
KeelServiceInst(v int)keel.service.instintattribute.KeyValue

Circuit Breaker Attributes ​

FunctionKeyParameterReturn
CircuitBreakerName(v string)circuit_breaker.namestringattribute.KeyValue
CircuitBreakerState(v string)circuit_breaker.statestringattribute.KeyValue

Distributed Lock Attributes ​

FunctionKeyParameterReturn
DistributedLockName(v string)distributed_lock.namestringattribute.KeyValue
DistributedLockSystem(v string)distributed_lock.systemstringattribute.KeyValue
DistributedLockAcquireResult(v string)distributed_lock.acquire.resultstringattribute.KeyValue
DistributedLockOwnerID(v string)distributed_lock.owner.idstringattribute.KeyValue

distributed_lock.name must be the logical lock name, not the per-resource key. distributed_lock.owner.id values are unbounded: use on spans and logs only, never on metrics.

NATS Attributes ​

FunctionKeyParameterReturn
NATSClientName(v string)nats.client.namestringattribute.KeyValue
NATSClientErrorKind(v string)nats.client.error.kindstringattribute.KeyValue
MessagingNATSStream(v string)messaging.nats.streamstringattribute.KeyValue

MessagingSystemNats is a predefined messaging.system="nats" attribute.

Profile Attributes ​

FunctionKeyParameterReturn
ProfileName(v string)profile.namestringattribute.KeyValue

Reflect Attributes ​

FunctionKeyParameterReturn
ReflectType(v any)reflect.typeanyattribute.KeyValue

Trace Attributes ​

FunctionKeyParameterReturn
TraceID(v string)trace.idstringattribute.KeyValue
SpanID(v string)span.idstringattribute.KeyValue
SamplingPriority(v int)sampling.priorityintattribute.KeyValue

sampling.priority > 0 asks samplers to keep the trace. Match it in the collector with a tail_sampling numeric_attribute policy (min_value: 1).

Tracking Attributes ​

FunctionKeyParameterReturn
TrackingID(v string)tracking.idstringattribute.KeyValue

tracking.id values are unbounded: use on spans and logs only, never on metrics.


gotsrpcconv ​

go
import "github.com/foomo/opentelemetry-go/semconv/gotsrpcconv"

Typed metric instrument wrappers for GoTSRPC conventions.

ExecutionDuration ​

go
type ExecutionDuration struct {
	metric.Float64Histogram
}

A Float64Histogram wrapper pre-configured with name gotsrpc.execution.duration, unit s, and description Duration of GOTSRPC execution.

NewExecutionDuration ​

go
func NewExecutionDuration(m metric.Meter, opt ...metric.Float64HistogramOption) (ExecutionDuration, error)

Creates a new ExecutionDuration instrument. Returns a no-op if the meter is nil.

Methods ​

go
func (m ExecutionDuration) Inst() metric.Float64Histogram

Returns the underlying histogram instrument.

go
func (ExecutionDuration) Name() string        // "gotsrpc.execution.duration"
func (ExecutionDuration) Unit() string        // "s"
func (ExecutionDuration) Description() string // "Duration of GOTSRPC execution."
go
func (m ExecutionDuration) Record(
	ctx context.Context,
	val float64,
	pkg string,   // gotsrpc.package
	svs string,   // gotsrpc.service
	fnc string,   // gotsrpc.func
	attrs ...attribute.KeyValue,
)

Records a duration value with GoTSRPC context attributes automatically added.

go
func (m ExecutionDuration) RecordSet(ctx context.Context, val float64, set attribute.Set)

Records a duration value with a pre-built attribute set.

go
func (ExecutionDuration) AttrError(val bool) attribute.KeyValue

Returns attribute.Bool("gotsprc.error", val).


natsconv ​

go
import "github.com/foomo/opentelemetry-go/semconv/natsconv"

Typed metric instrument wrappers for NATS conventions in the nats and messaging.nats namespaces. Every constructor New<Instrument>(m metric.Meter, opt ...) returns a no-op instrument if the meter is nil. Each instrument exposes Inst(), Name(), Unit() and Description().

Counters ​

InstrumentNameUnitRecord
ClientDisconnectsnats.client.disconnects{event}Add(ctx, incr, serverAddress, attrs...)
ClientReconnectsnats.client.reconnects{event}Add(ctx, incr, serverAddress, attrs...)
ClientAsyncErrorsnats.client.async_errors{error}Add(ctx, incr, kind AsyncErrorKindAttr, attrs...)

All counters also provide AddSet(ctx, incr, set attribute.Set).

Optional attribute helpers:

  • ClientDisconnects, ClientReconnects: AttrServerPort(int), AttrClientName(string)
  • ClientAsyncErrors: AttrSubject(string) (messaging.destination.name), AttrServerAddress(string)

Observable Gauges ​

InstrumentNameUnitRecord
JetStreamConsumerPendingnats.jetstream.consumer.pending{message}Observe(o, val, stream, consumerGroupName, attrs...)
JetStreamConsumerAckPendingnats.jetstream.consumer.ack_pending{message}Observe(o, val, stream, consumerGroupName, attrs...)
JetStreamConsumerRedeliverednats.jetstream.consumer.redelivered{message}Observe(o, val, stream, consumerGroupName, attrs...)

All gauges also provide ObserveSet(o, val, set attribute.Set). Call Observe from a callback registered with the meter. stream maps to messaging.nats.stream, consumerGroupName to messaging.consumer.group.name.

Enums ​

  • AsyncErrorKindAttr (nats.client.error.kind): AsyncErrorKindSlowConsumer, AsyncErrorKindPermissionViolation, AsyncErrorKindAuthExpired, AsyncErrorKindAuthRevoked, AsyncErrorKindOther (_OTHER)
  • ConnectionStatusAttr (nats.client.connection.status): ConnectionStatusConnected, ConnectionStatusDisconnected, ConnectionStatusReconnecting, ConnectionStatusConnecting, ConnectionStatusDraining, ConnectionStatusClosed

circuitbreakerconv ​

go
import "github.com/foomo/opentelemetry-go/semconv/circuitbreakerconv"

Library-agnostic metric instrument wrappers for circuit breakers in the circuit_breaker namespace. Every constructor New<Instrument>(m metric.Meter, opt ...) returns a no-op instrument if the meter is nil. Each instrument exposes Inst(), Name(), Unit() and Description().

Counters ​

InstrumentNameUnitRecord
StateChangescircuit_breaker.state_changes{change}Add(ctx, incr, name, state StateAttr, attrs...)
Rejectionscircuit_breaker.rejections{call}Add(ctx, incr, name, attrs...)

All counters also provide AddSet(ctx, incr, set attribute.Set). name maps to circuit_breaker.name; for StateChanges, state is the state transitioned to.

Optional attribute helpers:

  • Rejections: AttrState(StateAttr)

Enums ​

  • StateAttr (circuit_breaker.state): StateClosed, StateOpen, StateHalfOpen

distributedlockconv ​

go
import "github.com/foomo/opentelemetry-go/semconv/distributedlockconv"

Backend-agnostic metric instrument wrappers for distributed locks in the distributed_lock namespace. Every constructor New<Instrument>(m metric.Meter, opt ...) returns a no-op instrument if the meter is nil. Each instrument exposes Inst(), Name(), Unit() and Description().

Histograms ​

InstrumentNameUnitRecord
AcquireDurationdistributed_lock.acquire.durationsRecord(ctx, val, name, system SystemAttr, result AcquireResultAttr, attrs...)
HoldDurationdistributed_lock.hold.durationsRecord(ctx, val, name, system SystemAttr, attrs...)

All histograms also provide RecordSet(ctx, val, set attribute.Set). AcquireDuration includes time spent waiting; its count doubles as the number of acquire attempts.

Optional attribute helpers:

  • AcquireDuration: AttrErrorType(error) (error.type)

Counters ​

InstrumentNameUnitRecord
Lostdistributed_lock.lost{lock}Add(ctx, incr, name, system SystemAttr, attrs...)

Also provides AddSet(ctx, incr, set attribute.Set). Counts locks lost while still held (lease expired or taken over).

Enums ​

  • SystemAttr (distributed_lock.system): SystemRedis, SystemMongoDB, SystemNATS, SystemEtcd, SystemPostgreSQL
  • AcquireResultAttr (distributed_lock.acquire.result): AcquireResultAcquired, AcquireResultContended, AcquireResultTimeout, AcquireResultError