# Copyright The OpenTelemetry Authors
# SPDX-License-Identifier: Apache-2.0
import copy
import logging
import threading
from collections import OrderedDict
from collections.abc import Mapping, MutableMapping, Sequence
from opentelemetry.util import types
# bytes are accepted as a user supplied value for attributes but
# decoded to strings internally.
_VALID_ATTR_VALUE_TYPES = (bool, str, bytes, int, float)
# AnyValue possible values
_VALID_ANY_VALUE_TYPES = (
type(None),
bool,
bytes,
int,
float,
str,
Sequence,
Mapping,
)
# TODO: Remove this workaround and revert to the simpler implementation
# once Python 3.9 support is dropped (planned around May 2026).
# This exists only to avoid issues caused by deprecated behavior in 3.9.
def _type_name(t):
return getattr(t, "__name__", getattr(t, "_name", repr(t)))
_logger = logging.getLogger(__name__)
# pylint: disable=too-many-return-statements
# pylint: disable=too-many-branches
def _clean_attribute(
key: str, value: types.AttributeValue, max_len: int | None
) -> types.AttributeValue | tuple[str | int | float, ...] | None:
"""Checks if attribute value is valid and cleans it if required.
The function returns the cleaned value or None if the value is not valid.
An attribute value is valid if it is either:
- A primitive type: string, boolean, double precision floating
point (IEEE 754-1985) or integer.
- An array of primitive type values. The array MUST be homogeneous,
i.e. it MUST NOT contain values of different types.
An attribute needs cleansing if:
- Its length is greater than the maximum allowed length.
- It needs to be encoded/decoded e.g, bytes to strings.
"""
if not (key and isinstance(key, str)):
_logger.warning("invalid key `%s`. must be non-empty string.", key)
return None
if isinstance(value, _VALID_ATTR_VALUE_TYPES):
if isinstance(value, bytes):
try:
value = value.decode()
except UnicodeDecodeError:
_logger.warning("Byte attribute could not be decoded.")
return None
if max_len is not None and isinstance(value, str):
value = value[:max_len]
return value
if isinstance(value, Sequence):
sequence_first_valid_type = None
cleaned_seq = []
for element in value:
if isinstance(element, bytes):
try:
element = element.decode()
except UnicodeDecodeError:
_logger.warning("Byte attribute could not be decoded.")
cleaned_seq.append(None)
continue
if max_len is not None and isinstance(element, str):
element = element[:max_len]
elif element is None:
cleaned_seq.append(None)
continue
element_type = type(element)
# Reject attribute value if sequence contains a value with an incompatible type.
if element_type not in _VALID_ATTR_VALUE_TYPES:
_logger.warning(
"Invalid type %s in attribute '%s' value sequence. Expected one of "
"%s or None",
element_type.__name__,
key,
[
valid_type.__name__
for valid_type in _VALID_ATTR_VALUE_TYPES
],
)
return None
# The type of the sequence must be homogeneous. The first non-None
# element determines the type of the sequence
if sequence_first_valid_type is None:
sequence_first_valid_type = element_type
# use equality instead of isinstance as isinstance(True, int) evaluates to True
elif element_type != sequence_first_valid_type:
_logger.warning(
"Attribute %r mixes types %s and %s in attribute value sequence",
key,
sequence_first_valid_type.__name__,
type(element).__name__,
)
return None
cleaned_seq.append(element)
# Freeze mutable sequences defensively
return tuple(cleaned_seq)
_logger.warning(
"Invalid type %s for attribute '%s' value. Expected one of %s or a "
"sequence of those types",
type(value).__name__,
key,
[valid_type.__name__ for valid_type in _VALID_ATTR_VALUE_TYPES],
)
return None
def _clean_extended_attribute_value( # pylint: disable=too-many-branches
value: types.AnyValue, max_len: int | None
) -> types.AnyValue:
# for primitive types just return the value and eventually shorten the string length
if value is None or isinstance(value, _VALID_ATTR_VALUE_TYPES):
if max_len is not None and isinstance(value, str):
value = value[:max_len]
return value
if isinstance(value, Mapping):
cleaned_dict: dict[str, types.AnyValue] = {}
for key, element in value.items():
# skip invalid keys
if not (key and isinstance(key, str)):
_logger.warning(
"invalid key `%s`. must be non-empty string.", key
)
continue
cleaned_dict[key] = _clean_extended_attribute(
key=key, value=element, max_len=max_len
)
return cleaned_dict
if isinstance(value, Sequence):
sequence_first_valid_type = None
cleaned_seq: list[types.AnyValue] = []
for element in value:
if element is None:
cleaned_seq.append(element)
continue
if max_len is not None and isinstance(element, str):
element = element[:max_len]
element_type = type(element)
if element_type not in _VALID_ATTR_VALUE_TYPES:
element = _clean_extended_attribute_value(
element, max_len=max_len
)
element_type = type(element) # type: ignore
# The type of the sequence must be homogeneous. The first non-None
# element determines the type of the sequence
if sequence_first_valid_type is None:
sequence_first_valid_type = element_type
# use equality instead of isinstance as isinstance(True, int) evaluates to True
elif element_type != sequence_first_valid_type:
_logger.warning(
"Mixed types %s and %s in attribute value sequence",
sequence_first_valid_type.__name__,
type(element).__name__,
)
return None
cleaned_seq.append(element)
# Freeze mutable sequences defensively
return tuple(cleaned_seq)
# Some applications such as Django add values to log records whose types fall outside the
# primitive types and `_VALID_ANY_VALUE_TYPES`, i.e., they are not of type `AnyValue`.
# Rather than attempt to whitelist every possible instrumentation, we stringify those values here
# so they can still be represented as attributes, falling back to the original TypeError only if
# converting to string raises.
try:
return str(value)
except Exception:
raise TypeError(
f"Invalid type {type(value).__name__} for attribute value. "
f"Expected one of {[_type_name(valid_type) for valid_type in _VALID_ANY_VALUE_TYPES]} or a "
"sequence of those types",
)
def _clean_extended_attribute(
key: str, value: types.AnyValue, max_len: int | None
) -> types.AnyValue:
"""Checks if attribute value is valid and cleans it if required.
The function returns the cleaned value or None if the value is not valid.
An attribute value is valid if it is an AnyValue.
An attribute needs cleansing if:
- Its length is greater than the maximum allowed length.
"""
if not (key and isinstance(key, str)):
_logger.warning("invalid key `%s`. must be non-empty string.", key)
return None
try:
return _clean_extended_attribute_value(value, max_len=max_len)
except TypeError as exception:
_logger.warning("Attribute %s: %s", key, exception)
return None
[docs]
class BoundedAttributes(MutableMapping): # type: ignore
"""An ordered dict with a fixed max capacity.
Oldest elements are dropped when the dict is full and a new element is
added.
"""
def __init__(
self,
maxlen: int | None = None,
attributes: types._ExtendedAttributes | None = None,
immutable: bool = True,
max_value_len: int | None = None,
extended_attributes: bool = False,
):
if maxlen is not None:
if not isinstance(maxlen, int) or maxlen < 0:
raise ValueError(
"maxlen must be valid int greater or equal to 0"
)
self.maxlen = maxlen
self.dropped = 0
self.max_value_len = max_value_len
self._extended_attributes = extended_attributes
# OrderedDict is not used until the maxlen is reached for efficiency.
self._dict: (
MutableMapping[str, types.AnyValue]
| OrderedDict[str, types.AnyValue]
) = {}
self._lock = threading.RLock()
if attributes:
for key, value in attributes.items():
self[key] = value
self._immutable = immutable
def __repr__(self) -> str:
return f"{dict(self._dict)}"
def __getitem__(self, key: str) -> types.AnyValue:
return self._dict[key]
def __setitem__(self, key: str, value: types.AnyValue) -> None:
if getattr(self, "_immutable", False): # type: ignore
raise TypeError
if self.maxlen is not None and self.maxlen == 0:
with self._lock:
self.dropped += 1
return
if self._extended_attributes:
value = _clean_extended_attribute(key, value, self.max_value_len)
else:
value = _clean_attribute(key, value, self.max_value_len) # type: ignore
if value is None:
return
with self._lock:
self._setitem_locked(key, value)
def _set_items(self, attributes: "types._ExtendedAttributes") -> None:
if getattr(self, "_immutable", False): # type: ignore
raise TypeError
if self.maxlen is not None and self.maxlen == 0:
with self._lock:
self.dropped += len(attributes)
return
cleaned = []
for key, value in attributes.items():
if self._extended_attributes:
cv = _clean_extended_attribute(key, value, self.max_value_len)
else:
cv = _clean_attribute(key, value, self.max_value_len) # type: ignore
if cv is None:
continue
cleaned.append((key, cv))
with self._lock:
for key, cv in cleaned:
self._setitem_locked(key, cv)
def _setitem_locked(self, key: str, value: types.AnyValue) -> None:
if key in self._dict:
del self._dict[key]
elif self.maxlen is not None and len(self._dict) == self.maxlen:
if not isinstance(self._dict, OrderedDict):
self._dict = OrderedDict(self._dict)
self._dict.popitem(last=False) # type: ignore
self.dropped += 1
self._dict[key] = value # type: ignore
def __delitem__(self, key: str) -> None:
if getattr(self, "_immutable", False): # type: ignore
raise TypeError
with self._lock:
del self._dict[key]
def __iter__(self):
if self._immutable:
return iter(self._dict)
with self._lock:
return iter(list(self._dict))
def __len__(self) -> int:
return len(self._dict)
def __deepcopy__(self, memo: dict) -> "BoundedAttributes":
copy_ = BoundedAttributes(
maxlen=self.maxlen,
immutable=self._immutable,
max_value_len=self.max_value_len,
extended_attributes=self._extended_attributes,
)
memo[id(self)] = copy_
with self._lock:
# Assign _dict directly to avoid re-cleaning already clean values
# and to bypass the immutability guard in __setitem__
copy_._dict = copy.deepcopy(self._dict, memo)
copy_.dropped = self.dropped
return copy_
[docs]
def copy(self): # type: ignore
return self._dict.copy() # type: ignore