instrument_attributes (instrument v1.0.0)

Attribute handling for OpenTelemetry-compatible instrumentation.

Attributes are key-value pairs used for dimensions in metrics and metadata in traces. Keys must be atoms or binaries, values can be binaries, integers, floats, or booleans.

Summary

Apply OTel attribute limits: cap the count, truncate string values. Returns {LimitedAttrs, DroppedCount}. Existing keys in Existing are preserved unconditionally; new keys are added until CountLimit is hit. Use unlimited for either limit to skip that check.

apply_limits(Existing, NewAttrs, CountLimit)

Three-arity form for limiting an addition to an existing attribute map. Useful when merging into a span's existing attributes.

from_list(List)

Creates attributes from a list of {key, value} pairs.

get(Attrs, Key)

Gets a value from the attributes.

get(Attrs, Key, Default)

Gets a value from the attributes with a default.

hash(Attrs)

Computes a hash of the attributes for use as map keys.

merge(Attrs1, Attrs2)

Merges two attribute sets. Values in the second set override the first.

new()

Creates a new empty attribute set.

new(Map)

Creates an attribute set from a map or proplist.

put(Attrs, Key, Value)

Puts a key-value pair into the attributes.

remove(Attrs, Key)

Removes a key from the attributes.

to_label_values(Attrs, Keys)

Extracts label values in order matching the given label keys. This is used for compatibility with the existing vector metrics.

to_list(Attrs)

Converts attributes to a list of {key, value} pairs.

truncate_value(V, Limit)

Truncate a single attribute value to the given length limit. Strings/binaries longer than the limit are truncated. Lists are truncated element by element. Numeric, boolean, and atom values are returned unchanged. unlimited is a no-op.

validate(Attrs)

Validates all attributes in the set. Returns {ok, Attrs} if valid, {error, Reason} if not.

Types

attribute_key/0

-type attribute_key() :: atom() | binary().

attribute_value/0

-type attribute_value() ::
          binary() |
          integer() |
          float() |
          boolean() |
          [binary()] |
          [integer()] |
          [float()] |
          [boolean()].

t/0

-type t() :: #{attribute_key() => attribute_value()}.

Functions

apply_limits(Attrs, CountLimit)

-spec apply_limits(map(), map() | pos_integer() | unlimited) -> {map(), non_neg_integer()}.

Equivalent to apply_limits(Existing, NewAttrs, CountLimit) with the configured value-length limit applied automatically.