Tracer Internals Reference

Reference for internal tracer components and advanced functionality.

Warning

This section documents internal APIs that are primarily for SDK maintainers and advanced use cases. For standard usage, see HoneyHiveTracer API Reference instead.

class honeyhive.tracer.core.base.HoneyHiveTracerBase(config=None, session_config=None, evaluation_config=None, *, api_key=<EXPLICIT>, project=<EXPLICIT>, session_name=<EXPLICIT>, source=<EXPLICIT>, server_url=<EXPLICIT>, session_id=<EXPLICIT>, disable_http_tracing=<EXPLICIT>, disable_batch=<EXPLICIT>, verbose=<EXPLICIT>, inputs=<EXPLICIT>, is_evaluation=<EXPLICIT>, run_id=<EXPLICIT>, dataset_id=<EXPLICIT>, datapoint_id=<EXPLICIT>, link_carrier=<EXPLICIT>, test_mode=<EXPLICIT>, **kwargs)[source]

Bases: object

Base HoneyHive tracer with dynamic initialization and configuration.

This base class provides the core infrastructure for HoneyHive tracing including dynamic configuration handling, initialization logic, and foundational properties. It uses dynamic patterns for flexible setup.

Note: too-many-instance-attributes disabled - Base tracer class requires extensive attributes for configuration management, state tracking, API clients, threading locks, and backward compatibility support.

Parameters:

config (DotDict)
session_config (SessionConfig | None)
evaluation_config (EvaluationConfig | None)
api_key (str | None | _ExplicitType)
project (str | None | _ExplicitType)
session_name (str | None | _ExplicitType)
source (str | _ExplicitType)
server_url (str | None | _ExplicitType)
session_id (str | None | _ExplicitType)
disable_http_tracing (bool | None | _ExplicitType)
disable_batch (bool | _ExplicitType)
verbose (bool | _ExplicitType)
inputs (Dict[str, Any] | None | _ExplicitType)
is_evaluation (bool | _ExplicitType)
run_id (str | None | _ExplicitType)
dataset_id (str | None | _ExplicitType)
datapoint_id (str | None | _ExplicitType)
link_carrier (Dict[str, Any] | None | _ExplicitType)
test_mode (bool | _ExplicitType)
kwargs (Any)

client: HoneyHive | None

session_api: SessionAPI | None

tracer: Any

config: DotDict

classmethod reset()[source]

Reset static state for testing purposes.

This method provides backward compatibility for test environments that expect a reset capability. In the multi-instance architecture, this primarily delegates to the lifecycle management system.

Return type:: None

classmethod init(config=None, session_config=None, evaluation_config=None, **kwargs)[source]

Factory method for creating tracer instances with dynamic configuration.

This is a simple pass-through to __init__ for backwards compatibility.

Parameters:

config (TracerConfig | None) – Pydantic tracer configuration
session_config (SessionConfig | None) – Session-specific configuration
evaluation_config (EvaluationConfig | None) – Evaluation-specific configuration
**kwargs (Any) – Backward-compatible parameters

Returns:

Initialized HoneyHive tracer instance

Return type:

Self

property project_name: str | None: Get project name from unified configuration.

property source_environment: str: Get source environment from unified configuration.

property is_initialized: bool: Check if tracer is properly initialized.

property is_test_mode: bool: Check if tracer is in test mode.

link(carrier)[source]

Link context to carrier for backwards compatibility.

Parameters:: carrier (Dict[str, Any]) – Dictionary to inject context into
Returns:: Token for unlinking (tracer ID for backwards compatibility)
Return type:: str

inject(carrier)[source]

Inject context into carrier for backwards compatibility.

Parameters:: carrier (Dict[str, Any]) – Dictionary to inject context into
Returns:: The carrier with injected context
Return type:: Dict[str, Any]

unlink(_token)[source]

Unlink context for backwards compatibility.

Parameters:: _token (str) – Token returned from link() method (ignored for compatibility)
Return type:: None

NoOpSpan 

class honeyhive.tracer.core.base.NoOpSpan[source]

Bases: object

No-op span implementation for graceful degradation.

This class provides a safe default span that implements the same interface as a real span but performs no operations. This follows OpenTelemetry best practices for error handling - never return None, always return a usable object.

set_attribute(key, value)[source]

Set attribute (no-op).

Parameters:

key (str)
value (Any)

Return type:

None

set_attributes(attributes)[source]

Set multiple attributes (no-op).

Parameters:: attributes (Dict[str, Any])
Return type:: None

add_event(name, attributes=None, timestamp=None)[source]

Add event (no-op).

Parameters:

name (str)
attributes (Dict[str, Any] | None)
timestamp (int | None)

Return type:

None

record_exception(exception, attributes=None, timestamp=None, escaped=False)[source]

Record exception (no-op).

Parameters:

exception (Exception)
attributes (Dict[str, Any] | None)
timestamp (int | None)
escaped (bool)

Return type:

None

set_status(status, description=None)[source]

Set status (no-op).

Parameters:

status (Any)
description (str | None)

Return type:

None

update_name(name)[source]

Update name (no-op).

Parameters:: name (str)
Return type:: None

end(end_time=None)[source]

End span (no-op).

Parameters:: end_time (int | None)
Return type:: None

is_recording()[source]

Check if span is recording (always False for no-op).

Return type:: bool

get_span_context()[source]

Get span context (returns invalid context).

Return type:: Any

Processing 

Environment Profile 

class honeyhive.tracer.processing.otlp_profiles.EnvironmentProfile(*, name, pool_connections, pool_maxsize, max_retries, timeout, backoff_factor, description='', pool_block=False, additional_config=None)[source]

Bases: BaseModel

Environment-specific OTLP configuration profile.

Parameters:

name (str)
pool_connections (int)
pool_maxsize (int)
max_retries (int)
timeout (float)
backoff_factor (float)
description (str)
pool_block (bool)
additional_config (Dict[str, Any] | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': False, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

pool_connections: int

pool_maxsize: int

max_retries: int

timeout: float

backoff_factor: float

description: str

pool_block: bool

additional_config: Dict[str, Any] | None

classmethod validate_pool_maxsize(v, info)[source]

Ensure pool_maxsize is at least as large as pool_connections.

Note: This validation logic is intentionally duplicated between EnvironmentProfile and OTLPSessionConfig classes as both need the same pool size validation constraints.

Parameters:

v (int)
info (Any)

Return type:

int

OTLP Exporters 

class honeyhive.tracer.processing.otlp_exporter.HoneyHiveOTLPExporter(tracer_instance=None, session_config=None, use_optimized_session=True, protocol='http/protobuf', **kwargs)[source]

Bases: SpanExporter

HoneyHive OTLP exporter with optimized connection pooling.

This exporter is an enhanced wrapper around the standard OpenTelemetry OTLP exporter that includes optimized HTTP session with connection pooling for better performance and reliability. All span processing should have been completed by the HoneyHiveSpanProcessor before spans reach this exporter.

Features: - Optimized HTTP session with connection pooling - Enhanced retry strategies for reliable span delivery - Session statistics and monitoring capabilities - Graceful fallback to standard sessions if optimization fails

Parameters:

tracer_instance (Any)
session_config (OTLPSessionConfig | None)
use_optimized_session (bool)
protocol (str)
kwargs (Any)

export(spans)[source]

Export spans to HoneyHive via OTLP.

This method exports spans that have already been processed by the HoneyHiveSpanProcessor. All attribute processing should have been completed before reaching this exporter.

Parameters:: spans (Sequence[ReadableSpan]) – Sequence of ReadableSpan objects to export
Returns:: SpanExportResult indicating success or failure
Return type:: SpanExportResult

force_flush(timeout_millis=30000)[source]

Force flush any buffered spans.

Parameters:: timeout_millis (int)
Return type:: bool

get_session_stats()[source]

Get connection pool statistics from the HTTP session.

Returns:: Dictionary containing session and connection pool statistics
Return type:: Dict[str, Any]

log_session_stats()[source]

Log current session statistics for monitoring.

Return type:: None

shutdown()[source]

Shutdown the exporter and log final statistics.

Return type:: None

class honeyhive.tracer.processing.otlp_exporter.OTLPJSONExporter(endpoint, *, headers=None, session=None, timeout=None, tracer_instance=None)[source]

Bases: SpanExporter

OTLP JSON exporter that sends spans in JSON format over HTTP.

This exporter serializes spans to OTLP JSON format and sends them via HTTP POST with Content-Type: application/json. It implements the SpanExporter interface and can be used as a drop-in replacement for OTLPSpanExporter when JSON format is required.

Parameters:

endpoint (str)
headers (Dict[str, str] | None)
session (Session | None)
timeout (float | None)
tracer_instance (Any)

export(spans)[source]

Export spans to HoneyHive via OTLP JSON format.

Parameters:: spans (Sequence[ReadableSpan]) – Sequence of ReadableSpan objects to export
Returns:: SpanExportResult indicating success or failure
Return type:: SpanExportResult

force_flush(timeout_millis=30000)[source]

Force flush any buffered spans (no-op for this exporter).

Parameters:: timeout_millis (int)
Return type:: bool

shutdown()[source]

Shutdown the exporter.

Return type:: None

Infrastructure 

Environment Detector 

class honeyhive.tracer.infra.environment.EnvironmentDetector(tracer_instance=None)[source]

Bases: object

Comprehensive environment and resource detection.

Parameters:: tracer_instance (Any | None)

get_comprehensive_analysis()[source]

Get comprehensive environment analysis with caching.

Returns:: Complete environment analysis including all detection results
Return type:: Dict[str, Any]

detect_primary_environment_type()[source]

Detect the primary environment type.

Returns:: Primary environment type string
Return type:: str

detect_container_environment()[source]

Detect container environment characteristics.

Returns:: Dictionary with container environment details
Return type:: Dict[str, Any]

detect_cloud_environment()[source]

Detect cloud provider and environment.

Returns:: Dictionary with cloud environment details
Return type:: Dict[str, Any]

detect_resource_constraints()[source]

Detect system resource constraints using dynamic analysis.

Returns:: Dictionary with resource constraint information
Return type:: Dict[str, Any]

detect_performance_characteristics()[source]

Detect performance characteristics using dynamic analysis.

Returns:: Dictionary with performance characteristics
Return type:: Dict[str, Any]

detect_system_info()[source]

Detect basic system information.

Returns:: Dictionary with system information
Return type:: Dict[str, Any]

clear_cache()[source]

Clear the detection cache to force re-detection.

Return type:: None

Tracer Internals Reference

Core Components 

Base Classes 

NoOpSpan 

Processing 

Environment Profile 

OTLP Exporters 

Infrastructure 

Environment Detector 

See Also 