honeyhive.tracer.instrumentation.initialization

Tracer initialization and OpenTelemetry setup functionality.

This module handles the complex initialization process for HoneyHive tracers, including OpenTelemetry provider detection, configuration, and session setup. It implements the multi-instance architecture with proper provider integration.

initialize_tracer_instance

initialize_tracer_instance(
    tracer_instance: HoneyHiveTracerBase,
) -> None

Initialize a HoneyHiveTracer instance with full setup.

This function handles the complete initialization process for a tracer instance, including OpenTelemetry setup, session creation, and provider configuration. It's called by the HoneyHiveTracer.init() class method.

:param tracer_instance: The tracer instance to initialize :type tracer_instance: HoneyHiveTracer :note: Uses graceful degradation - never crashes host application :note: Missing configuration triggers degraded mode with warnings :note: API failures result in no-op mode with local fallback

Example:

.. code-block:: python

tracer = HoneyHiveTracer(api_key="key", project="project")
initialize_tracer_instance(tracer)
# Tracer is now fully initialized and ready to use

Note:

This function modifies the tracer instance in-place and should only be called once per tracer instance during initialization.

Source code in src/honeyhive/tracer/instrumentation/initialization.py

def initialize_tracer_instance(tracer_instance: "HoneyHiveTracerBase") -> None:
    """Initialize a HoneyHiveTracer instance with full setup.

    This function handles the complete initialization process for a tracer
    instance, including OpenTelemetry setup, session creation, and provider
    configuration. It's called by the HoneyHiveTracer.init() class method.

    :param tracer_instance: The tracer instance to initialize
    :type tracer_instance: HoneyHiveTracer
    :note: Uses graceful degradation - never crashes host application
    :note: Missing configuration triggers degraded mode with warnings
    :note: API failures result in no-op mode with local fallback

    **Example:**

    .. code-block:: python

        tracer = HoneyHiveTracer(api_key="key", project="project")
        initialize_tracer_instance(tracer)
        # Tracer is now fully initialized and ready to use

    **Note:**

    This function modifies the tracer instance in-place and should only
    be called once per tracer instance during initialization.
    """
    # Multi-instance logging architecture uses safe_log utility
    # No need to attach logger directly to tracer instance

    # Enable debug logging if verbose mode is requested
    if getattr(tracer_instance, "verbose", False):
        # Verbose logging is handled by the tracer's logger.update_verbose_setting()
        # in the tracer initialization - no need for direct logging module calls here
        safe_log(
            tracer_instance,
            "debug",
            "Verbose logging enabled for HoneyHive tracer initialization",
        )

    safe_log(
        tracer_instance,
        "debug",
        "Starting tracer initialization",
        honeyhive_data={
            "project": tracer_instance.project_name,
            "source": tracer_instance.source_environment,
            "test_mode": tracer_instance.test_mode,
        },
    )

    # Configuration already loaded and validated during tracer init

    # Step 2: Initialize OpenTelemetry components
    _initialize_otel_components(tracer_instance)

    # Step 3: Initialize session management
    _initialize_session_management(tracer_instance)

    # Step 4: Register tracer for auto-discovery (assigns _tracer_id)
    _register_tracer_instance(tracer_instance)

    # Step 5: Setup baggage context (after registration so _tracer_id is available)
    _setup_baggage_context(tracer_instance)

    # Mark as initialized
    tracer_instance._initialized = True

    safe_log(
        tracer_instance,
        "info",
        "Tracer initialization completed successfully",
        honeyhive_data={
            "project": tracer_instance.project_name,
            "session_id": tracer_instance.session_id,
            "is_main_provider": tracer_instance.is_main_provider,
        },
    )

    # Clean up the temporary initialization logger
    # The tracer has its own logger (tracer_instance.logger) for runtime use
    if hasattr(tracer_instance, "logger"):
        delattr(tracer_instance, "logger")