honeyhive.tracer.core.priorities

Core attribute priority system for span attribute preservation.

This module defines priority levels for span attributes to ensure critical attributes survive OpenTelemetry's FIFO eviction when span attribute limits are exceeded.

Based on multi-repo code intelligence analysis of hive-kube ingestion service validation requirements (event_schema.js, new_event_validation.js).

Priority Levels

• P0 (CRITICAL): Required for backend validation, span rejected if missing
• P1 (HIGH): Important but can be regenerated, may lose data fidelity
• P2 (NORMAL): Auto-generated by backend or default values available
• P3 (LOW): Optional metadata, safe to evict

Usage

from honeyhive.tracer.core.priorities import ( ... CORE_ATTRIBUTES, ... get_attribute_priority, ... ) priority = get_attribute_priority("honeyhive.session_id") priority 0 # P0 - CRITICAL is_critical = priority == 0

HONEYHIVE_NAMESPACE module-attribute

HONEYHIVE_NAMESPACE = 'honeyhive.'

CRITICAL_ATTRIBUTES module-attribute

CRITICAL_ATTRIBUTES: Set[str] = {
    f"{HONEYHIVE_NAMESPACE}session_id",
    f"{HONEYHIVE_NAMESPACE}event_type",
    f"{HONEYHIVE_NAMESPACE}event_name",
    f"{HONEYHIVE_NAMESPACE}source",
    f"{HONEYHIVE_NAMESPACE}duration",
}

HIGH_PRIORITY_ATTRIBUTES module-attribute

HIGH_PRIORITY_ATTRIBUTES: Set[str] = {
    f"{HONEYHIVE_NAMESPACE}event_id",
    f"{HONEYHIVE_NAMESPACE}outputs",
}

NORMAL_PRIORITY_ATTRIBUTES module-attribute

NORMAL_PRIORITY_ATTRIBUTES: Set[str] = {
    f"{HONEYHIVE_NAMESPACE}project_id",
    f"{HONEYHIVE_NAMESPACE}tenant",
    f"{HONEYHIVE_NAMESPACE}start_time",
    f"{HONEYHIVE_NAMESPACE}end_time",
    f"{HONEYHIVE_NAMESPACE}inputs",
    f"{HONEYHIVE_NAMESPACE}metadata",
}

CORE_ATTRIBUTES module-attribute

CORE_ATTRIBUTES: Set[str] = (
    CRITICAL_ATTRIBUTES
    | HIGH_PRIORITY_ATTRIBUTES
    | NORMAL_PRIORITY_ATTRIBUTES
)

ATTRIBUTE_PRIORITY_MAP module-attribute

ATTRIBUTE_PRIORITY_MAP: Dict[str, AttributePriority] = {
    None: {
        attr: (CRITICAL) for attr in CRITICAL_ATTRIBUTES
    },
    None: {
        attr: (HIGH) for attr in HIGH_PRIORITY_ATTRIBUTES
    },
    None: {
        attr: (NORMAL)
        for attr in NORMAL_PRIORITY_ATTRIBUTES
    },
}

AttributePriority

Bases: IntEnum

Attribute priority levels for eviction protection.

Lower numbers = higher priority = preserved first when limits hit.

Attributes:

Name	Type	Description
CRITICAL		Must survive eviction - span rejected if missing
HIGH		Important data - may lose fidelity if evicted
NORMAL		Can be regenerated or has defaults
LOW		Optional metadata - safe to evict

Source code in src/honeyhive/tracer/core/priorities.py

class AttributePriority(IntEnum):
    """Attribute priority levels for eviction protection.

    Lower numbers = higher priority = preserved first when limits hit.

    Attributes:
        CRITICAL: Must survive eviction - span rejected if missing
        HIGH: Important data - may lose fidelity if evicted
        NORMAL: Can be regenerated or has defaults
        LOW: Optional metadata - safe to evict
    """

    CRITICAL = 0  # P0 - Must preserve
    HIGH = 1  # P1 - Should preserve
    NORMAL = 2  # P2 - Can evict
    LOW = 3  # P3 - First to evict

CRITICAL class-attribute instance-attribute

CRITICAL = 0

HIGH class-attribute instance-attribute

HIGH = 1

NORMAL class-attribute instance-attribute

NORMAL = 2

LOW class-attribute instance-attribute

LOW = 3

get_attribute_priority

get_attribute_priority(
    attribute_key: str,
) -> AttributePriority

Get priority level for a span attribute.

Determines the eviction priority for an attribute key. Critical attributes (P0) must be preserved to prevent span rejection. Lower priority attributes can be safely evicted when span limits are reached.

:param attribute_key: Span attribute key (e.g., "honeyhive.session_id") :type attribute_key: str :return: Priority level (0=CRITICAL, 1=HIGH, 2=NORMAL, 3=LOW) :rtype: AttributePriority

Examples:

>>> get_attribute_priority("honeyhive.session_id")
<AttributePriority.CRITICAL: 0>
>>> get_attribute_priority("honeyhive.custom_field")
<AttributePriority.LOW: 3>
>>> get_attribute_priority("openinference.span.kind")
<AttributePriority.LOW: 3>

Source code in src/honeyhive/tracer/core/priorities.py

def get_attribute_priority(attribute_key: str) -> AttributePriority:
    """Get priority level for a span attribute.

    Determines the eviction priority for an attribute key. Critical attributes
    (P0) must be preserved to prevent span rejection. Lower priority attributes
    can be safely evicted when span limits are reached.

    :param attribute_key: Span attribute key (e.g., "honeyhive.session_id")
    :type attribute_key: str
    :return: Priority level (0=CRITICAL, 1=HIGH, 2=NORMAL, 3=LOW)
    :rtype: AttributePriority

    Examples:
        >>> get_attribute_priority("honeyhive.session_id")
        <AttributePriority.CRITICAL: 0>
        >>> get_attribute_priority("honeyhive.custom_field")
        <AttributePriority.LOW: 3>
        >>> get_attribute_priority("openinference.span.kind")
        <AttributePriority.LOW: 3>
    """
    return ATTRIBUTE_PRIORITY_MAP.get(attribute_key, AttributePriority.LOW)

is_critical_attribute

is_critical_attribute(attribute_key: str) -> bool

Check if attribute is critical (P0) and must survive eviction.

Critical attributes cause span rejection if missing during backend validation. These must be preserved when attribute limits are hit.

:param attribute_key: Span attribute key to check :type attribute_key: str :return: True if attribute is critical (P0), False otherwise :rtype: bool

Examples:

>>> is_critical_attribute("honeyhive.session_id")
True
>>> is_critical_attribute("honeyhive.metadata")
False

Source code in src/honeyhive/tracer/core/priorities.py

def is_critical_attribute(attribute_key: str) -> bool:
    """Check if attribute is critical (P0) and must survive eviction.

    Critical attributes cause span rejection if missing during backend
    validation. These must be preserved when attribute limits are hit.

    :param attribute_key: Span attribute key to check
    :type attribute_key: str
    :return: True if attribute is critical (P0), False otherwise
    :rtype: bool

    Examples:
        >>> is_critical_attribute("honeyhive.session_id")
        True
        >>> is_critical_attribute("honeyhive.metadata")
        False
    """
    return attribute_key in CRITICAL_ATTRIBUTES

is_core_attribute

is_core_attribute(attribute_key: str) -> bool

Check if attribute is a core HoneyHive attribute (any priority).

Core attributes are managed by the SDK and have defined priority levels. This includes P0 (critical), P1 (high), and P2 (normal) attributes.

:param attribute_key: Span attribute key to check :type attribute_key: str :return: True if attribute is a core attribute, False otherwise :rtype: bool

Examples:

>>> is_core_attribute("honeyhive.session_id")
True
>>> is_core_attribute("honeyhive.event_type")
True
>>> is_core_attribute("custom.field")
False

Source code in src/honeyhive/tracer/core/priorities.py

def is_core_attribute(attribute_key: str) -> bool:
    """Check if attribute is a core HoneyHive attribute (any priority).

    Core attributes are managed by the SDK and have defined priority levels.
    This includes P0 (critical), P1 (high), and P2 (normal) attributes.

    :param attribute_key: Span attribute key to check
    :type attribute_key: str
    :return: True if attribute is a core attribute, False otherwise
    :rtype: bool

    Examples:
        >>> is_core_attribute("honeyhive.session_id")
        True
        >>> is_core_attribute("honeyhive.event_type")
        True
        >>> is_core_attribute("custom.field")
        False
    """
    return attribute_key in CORE_ATTRIBUTES

get_critical_attributes

get_critical_attributes() -> Set[str]

Get set of all critical (P0) attributes that must survive eviction.

Returns a copy of the critical attributes set to prevent modification of the internal state.

:return: Set of critical attribute keys :rtype: Set[str]

Examples:

>>> critical = get_critical_attributes()
>>> "honeyhive.session_id" in critical
True
>>> len(critical)
5

Source code in src/honeyhive/tracer/core/priorities.py

def get_critical_attributes() -> Set[str]:
    """Get set of all critical (P0) attributes that must survive eviction.

    Returns a copy of the critical attributes set to prevent modification
    of the internal state.

    :return: Set of critical attribute keys
    :rtype: Set[str]

    Examples:
        >>> critical = get_critical_attributes()
        >>> "honeyhive.session_id" in critical
        True
        >>> len(critical)
        5
    """
    return CRITICAL_ATTRIBUTES.copy()

get_core_attributes

get_core_attributes() -> Set[str]

Get set of all core attributes (P0, P1, P2) managed by the SDK.

Returns a copy of the core attributes set to prevent modification of the internal state.

:return: Set of core attribute keys :rtype: Set[str]

Examples:

>>> core = get_core_attributes()
>>> "honeyhive.session_id" in core
True
>>> "honeyhive.metadata" in core
True

Source code in src/honeyhive/tracer/core/priorities.py

def get_core_attributes() -> Set[str]:
    """Get set of all core attributes (P0, P1, P2) managed by the SDK.

    Returns a copy of the core attributes set to prevent modification
    of the internal state.

    :return: Set of core attribute keys
    :rtype: Set[str]

    Examples:
        >>> core = get_core_attributes()
        >>> "honeyhive.session_id" in core
        True
        >>> "honeyhive.metadata" in core
        True
    """
    return CORE_ATTRIBUTES.copy()

get_attributes_by_priority

get_attributes_by_priority(
    priority: AttributePriority,
) -> Set[str]

Get all attributes with a specific priority level.

:param priority: Priority level to filter by :type priority: AttributePriority :return: Set of attribute keys with the specified priority :rtype: Set[str] :raises ValueError: If priority is not a valid AttributePriority

Examples:

>>> critical_attrs = get_attributes_by_priority(AttributePriority.CRITICAL)
>>> len(critical_attrs)
5
>>> high_attrs = get_attributes_by_priority(AttributePriority.HIGH)
>>> len(high_attrs)
2

Source code in src/honeyhive/tracer/core/priorities.py

def get_attributes_by_priority(priority: AttributePriority) -> Set[str]:
    """Get all attributes with a specific priority level.

    :param priority: Priority level to filter by
    :type priority: AttributePriority
    :return: Set of attribute keys with the specified priority
    :rtype: Set[str]
    :raises ValueError: If priority is not a valid AttributePriority

    Examples:
        >>> critical_attrs = get_attributes_by_priority(AttributePriority.CRITICAL)
        >>> len(critical_attrs)
        5
        >>> high_attrs = get_attributes_by_priority(AttributePriority.HIGH)
        >>> len(high_attrs)
        2
    """
    if not isinstance(priority, AttributePriority):
        raise ValueError(
            f"priority must be AttributePriority, got {type(priority).__name__}"
        )

    return {attr for attr, prio in ATTRIBUTE_PRIORITY_MAP.items() if prio == priority}