honeyhive.tracer.integration.compatibility

Dynamic backward compatibility functions for the refactored tracer module.

This module provides global functions that maintain backward compatibility with the original API while using the new modular tracer architecture. All compatibility functions use dynamic discovery and fallback patterns.

enrich_session

enrich_session(
    session_id: str,
    metadata: Optional[Dict[str, Any]] = None,
    tracer: Optional[Any] = None,
    tracer_instance: Optional[Any] = None,
) -> None

LEGACY (v1.0+): Dynamically enrich session with metadata.

.. deprecated:: 1.0 This free function pattern is provided for backward compatibility only. Use instance methods instead: tracer.enrich_session() This pattern will be removed in v2.0.

Recommended Pattern (v1.0+): Use the tracer instance method for explicit tracer reference::

tracer = HoneyHiveTracer.init(api_key="...", project="...")
tracer.enrich_session(
    metadata={"user_id": "user-456"},
    user_properties={"plan": "premium"}
)

This function provides backward compatibility for the global enrich_session function using dynamic tracer discovery and flexible metadata handling.

Parameters:

Name	Type	Description	Default
session_id	str	The session ID to enrich	required
metadata	Optional[Dict[str, Any]]	Metadata dictionary to add to the session	None
tracer	Optional[Any]	Optional tracer instance to use	None
tracer_instance	Optional[Any]	Optional tracer instance for logging context	None

Legacy Example

Using default tracer (backward compatibility)

enrich_session("session-123", {"user_id": "user-456"})

Using specific tracer (backward compatibility)

enrich_session("session-123", {"user_id": "user-456"}, tracer=my_tracer)

See Also

• :meth:HoneyHiveTracer.enrich_session - Primary pattern (v1.0+)
• :meth:HoneyHiveTracer.enrich_span - Span enrichment

Source code in src/honeyhive/tracer/integration/compatibility.py

def enrich_session(
    session_id: str,
    metadata: Optional[Dict[str, Any]] = None,
    tracer: Optional[Any] = None,
    tracer_instance: Optional[Any] = None,
) -> None:
    """**LEGACY (v1.0+):** Dynamically enrich session with metadata.

    .. deprecated:: 1.0
       This free function pattern is provided for backward compatibility only.
       **Use instance methods instead:** ``tracer.enrich_session()``
       This pattern will be removed in v2.0.

    **Recommended Pattern (v1.0+):**
    Use the tracer instance method for explicit tracer reference::

        tracer = HoneyHiveTracer.init(api_key="...", project="...")
        tracer.enrich_session(
            metadata={"user_id": "user-456"},
            user_properties={"plan": "premium"}
        )

    This function provides backward compatibility for the global enrich_session
    function using dynamic tracer discovery and flexible metadata handling.

    Args:
        session_id: The session ID to enrich
        metadata: Metadata dictionary to add to the session
        tracer: Optional tracer instance to use
        tracer_instance: Optional tracer instance for logging context

    Legacy Example:
        >>> # Using default tracer (backward compatibility)
        >>> enrich_session("session-123", {"user_id": "user-456"})
        >>>
        >>> # Using specific tracer (backward compatibility)
        >>> enrich_session("session-123", {"user_id": "user-456"}, tracer=my_tracer)

    See Also:
        - :meth:`HoneyHiveTracer.enrich_session` - Primary pattern (v1.0+)
        - :meth:`HoneyHiveTracer.enrich_span` - Span enrichment
    """
    # Dynamic tracer discovery
    active_tracer = _discover_tracer_dynamically(tracer, tracer_instance)

    if active_tracer is None:
        safe_log(
            tracer_instance,
            "warning",
            "No tracer available for session enrichment",
            honeyhive_data={
                "session_id": session_id,
                "metadata_keys": list(metadata.keys()) if metadata else [],
            },
        )
        return

    # Dynamic session enrichment
    try:
        _enrich_session_dynamically(
            active_tracer, session_id, metadata, tracer_instance
        )

        safe_log(
            tracer_instance,
            "debug",
            "Session enriched successfully",
            honeyhive_data={
                "session_id": session_id,
                "tracer_type": type(active_tracer).__name__,
                "metadata_count": len(metadata) if metadata else 0,
            },
        )

    except Exception as e:
        safe_log(
            tracer_instance,
            "error",
            "Failed to enrich session",
            honeyhive_data={
                "session_id": session_id,
                "error": str(e),
                "error_type": type(e).__name__,
            },
        )
    return

get_compatibility_info

get_compatibility_info() -> Dict[str, Any]

Get dynamic compatibility information.

Returns:

Type	Description
Dict[str, Any]	Dictionary with compatibility status and available features

Source code in src/honeyhive/tracer/integration/compatibility.py

def get_compatibility_info() -> Dict[str, Any]:
    """Get dynamic compatibility information.

    Returns:
        Dictionary with compatibility status and available features
    """
    # Dynamic compatibility assessment
    compatibility_info = {
        "backward_compatibility": True,
        "available_functions": ["enrich_session"],
        "tracer_discovery": {
            "explicit_tracer": True,
            "default_tracer": True,
            "context_based": True,
        },
        "enrichment_methods": {
            "direct_method": True,
            "baggage_method": True,
            "attribute_method": True,
        },
    }

    # Dynamic feature detection
    try:
        default_tracer = get_default_tracer()
        compatibility_info["default_tracer_available"] = default_tracer is not None

        if default_tracer:
            compatibility_info["default_tracer_type"] = type(default_tracer).__name__
            compatibility_info["default_tracer_methods"] = [
                method
                for method in dir(default_tracer)
                if not method.startswith("_")
                and callable(getattr(default_tracer, method))
            ]
    except Exception as e:
        compatibility_info["default_tracer_available"] = False
        compatibility_info["default_tracer_error"] = str(e)

    return compatibility_info