Skip to content

honeyhive.config.models.tracer

Tracer configuration models for HoneyHive SDK.

This module provides Pydantic models specifically for tracer initialization and configuration. These models are used to reduce argument count in tracer constructors while maintaining backwards compatibility.

The hybrid approach allows both old and new usage patterns:

Old Usage (Backwards Compatible): tracer = HoneyHiveTracer(api_key="...", project="...", verbose=True)

New Usage (Recommended): config = TracerConfig(api_key="...", project="...", verbose=True) tracer = HoneyHiveTracer(config=config)

All validation follows graceful degradation principles to prevent crashing the host application.

logger module-attribute 

logger = getLogger(__name__)

SpanNameFilter

Bases: BaseModel

A single span name filter entry.

Uses BaseModel (not BaseSettings) since these are nested data models that should not read from environment variables.

Attributes:

Name Type Description
type Literal['prefix']

The filter matching strategy. Only "prefix" is currently supported.
value str

The value to match against span names.
Source code in src/honeyhive/config/models/tracer.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class SpanNameFilter(BaseModel):
    """A single span name filter entry.

    Uses BaseModel (not BaseSettings) since these are nested data models
    that should not read from environment variables.

    Attributes:
        type: The filter matching strategy. Only "prefix" is currently supported.
        value: The value to match against span names.
    """

    type: Literal["prefix"] = Field(
        description='Filter matching strategy. Only "prefix" is currently supported.',
    )
    value: str = Field(
        description="The value to match against span names.",
        examples=["a2a.client.transports.jsonrpc"],
    )

    model_config = {"validate_assignment": True, "extra": "forbid"}

type class-attribute instance-attribute 

type: Literal["prefix"] = Field(
    description='Filter matching strategy. Only "prefix" is currently supported.'
)

value class-attribute instance-attribute 

value: str = Field(
    description="The value to match against span names.",
    examples=["a2a.client.transports.jsonrpc"],
)

SpanNameFilters

Bases: BaseModel

Configuration for filtering spans by name.

Uses BaseModel (not BaseSettings) since these are nested data models that should not read from environment variables.

Supports both include (allow-list) and exclude (block-list) filters. If include is specified, only spans matching at least one include filter are kept. If exclude is specified, spans matching any exclude filter are dropped. If both are specified, a span must match include AND not match exclude.

Example

filters = SpanNameFilters( ... exclude=[SpanNameFilter(type="prefix", value="a2a.client.transports")] ... )

Source code in src/honeyhive/config/models/tracer.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
class SpanNameFilters(BaseModel):
    """Configuration for filtering spans by name.

    Uses BaseModel (not BaseSettings) since these are nested data models
    that should not read from environment variables.

    Supports both include (allow-list) and exclude (block-list) filters.
    If include is specified, only spans matching at least one include filter are kept.
    If exclude is specified, spans matching any exclude filter are dropped.
    If both are specified, a span must match include AND not match exclude.

    Example:
        >>> filters = SpanNameFilters(
        ...     exclude=[SpanNameFilter(type="prefix", value="a2a.client.transports")]
        ... )
    """

    include: Optional[List[SpanNameFilter]] = Field(
        default=None,
        description="Allow-list: only keep spans matching at least one filter.",
    )
    exclude: Optional[List[SpanNameFilter]] = Field(
        default=None,
        description="Block-list: drop spans matching any filter.",
    )

    model_config = {"validate_assignment": True, "extra": "forbid"}

include class-attribute instance-attribute 

include: Optional[List[SpanNameFilter]] = Field(
    default=None,
    description="Allow-list: only keep spans matching at least one filter.",
)

exclude class-attribute instance-attribute 

exclude: Optional[List[SpanNameFilter]] = Field(
    default=None,
    description="Block-list: drop spans matching any filter.",
)

TracerConfig

Bases: BaseHoneyHiveConfig

Core tracer configuration with validation.

This class defines the primary configuration parameters for initializing a HoneyHive tracer instance. It inherits common fields from BaseHoneyHiveConfig and adds tracer-specific parameters.

Inherited Fields
  • api_key: HoneyHive API key for authentication
  • project: Deprecated project name (optional; backend infers scope from API key)
  • test_mode: Enable test mode (no data sent to backend)
  • verbose: Enable verbose logging output
Tracer-Specific Fields
  • session_name: Human-readable session identifier
  • source: Source environment identifier
  • server_url: Custom HoneyHive server URL (from HH_API_URL env var)
  • disable_http_tracing: Disable HTTP request tracing (disabled by default)
  • disable_batch: Disable batch processing of spans
Example

config = TracerConfig( ... api_key="hh_1234567890abcdef", ... project="my-llm-project", ... session_name="user-chat-session", ... source="production", ... verbose=True ... ) tracer = HoneyHiveTracer(config=config)

Backwards compatible usage still works:

tracer = HoneyHiveTracer( ... api_key="hh_1234567890abcdef", ... project="my-llm-project", ... verbose=True ... )

Source code in src/honeyhive/config/models/tracer.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
class TracerConfig(BaseHoneyHiveConfig):
    """Core tracer configuration with validation.

    This class defines the primary configuration parameters for initializing
    a HoneyHive tracer instance. It inherits common fields from BaseHoneyHiveConfig
    and adds tracer-specific parameters.

    Inherited Fields:
        - api_key: HoneyHive API key for authentication
        - project: Deprecated project name (optional; backend infers scope from API key)
        - test_mode: Enable test mode (no data sent to backend)
        - verbose: Enable verbose logging output

    Tracer-Specific Fields:
        - session_name: Human-readable session identifier
        - source: Source environment identifier
        - server_url: Custom HoneyHive server URL (from HH_API_URL env var)
        - disable_http_tracing: Disable HTTP request tracing (disabled by default)
        - disable_batch: Disable batch processing of spans

    Example:
        >>> config = TracerConfig(
        ...     api_key="hh_1234567890abcdef",
        ...     project="my-llm-project",
        ...     session_name="user-chat-session",
        ...     source="production",
        ...     verbose=True
        ... )
        >>> tracer = HoneyHiveTracer(config=config)

        # Backwards compatible usage still works:
        >>> tracer = HoneyHiveTracer(
        ...     api_key="hh_1234567890abcdef",
        ...     project="my-llm-project",
        ...     verbose=True
        ... )
    """

    session_name: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Human-readable session identifier",
        examples=["user-chat-session", "batch-processing-job"],
    )

    source: str = Field(  # type: ignore[call-overload,pydantic-alias]
        default="dev",
        description="Source environment identifier",
        validation_alias=AliasChoices("HH_SOURCE", "source"),
        examples=["dev", "staging", "production"],
    )

    server_url: str = Field(  # type: ignore[call-overload,pydantic-alias]
        default="https://api.dp1.us.honeyhive.ai",
        description="Custom HoneyHive server URL",
        validation_alias=AliasChoices("HH_API_URL", "server_url"),
        examples=[
            "https://api.dp1.us.honeyhive.ai",
            "https://custom.honeyhive.com",
        ],
    )

    disable_http_tracing: bool = Field(  # type: ignore[call-overload,pydantic-alias]
        default=True,
        description="Disable HTTP request tracing (disabled by default)",
        validation_alias=AliasChoices(
            "HH_DISABLE_HTTP_TRACING", "disable_http_tracing"
        ),
    )

    disable_batch: bool = Field(  # type: ignore[call-overload,pydantic-alias]
        default=False,
        description="Disable batch processing of spans",
        validation_alias=AliasChoices("HH_DISABLE_BATCH", "disable_batch"),
    )

    disable_tracing: bool = Field(  # type: ignore[call-overload,pydantic-alias]
        default=False,
        description="Disable all tracing functionality",
        validation_alias=AliasChoices("HH_DISABLE_TRACING", "disable_tracing"),
    )

    span_name_filters: Optional[SpanNameFilters] = Field(
        default=None,
        description=(
            "Filter spans by name using include/exclude lists. "
            "Each filter entry specifies a type ('prefix') and value to match. "
            "Excluded spans are dropped before enrichment and export."
        ),
        examples=[
            {"exclude": [{"type": "prefix", "value": "a2a.client.transports.jsonrpc"}]}
        ],
    )

    # OpenTelemetry Span Limits Configuration
    max_attributes: int = Field(  # type: ignore[call-overload,pydantic-alias]
        default=1024,
        description=(
            "Maximum number of attributes per span "
            "(OpenTelemetry default: 128, HoneyHive default: 1024)"
        ),
        validation_alias=AliasChoices("HH_MAX_ATTRIBUTES", "max_attributes"),
        examples=[128, 256, 500, 1024, 2000],
    )

    max_events: int = Field(  # type: ignore[call-overload,pydantic-alias]
        default=1024,
        description=(
            "Maximum number of events per span (matches max_attributes "
            "because events are flattened to pseudo-attributes)"
        ),
        validation_alias=AliasChoices("HH_MAX_EVENTS", "max_events"),
    )

    max_links: int = Field(  # type: ignore[call-overload,pydantic-alias]
        default=128,
        description="Maximum number of links per span",
        validation_alias=AliasChoices("HH_MAX_LINKS", "max_links"),
    )

    max_span_size: int = Field(  # type: ignore[call-overload,pydantic-alias]
        default=10 * 1024 * 1024,  # 10MB default
        description="Maximum total size of span (attributes + events + links) in bytes",
        validation_alias=AliasChoices("HH_MAX_SPAN_SIZE", "max_span_size"),
        examples=[1048576, 5242880, 10485760, 20971520],  # 1MB, 5MB, 10MB, 20MB
    )

    # Core Attribute Preservation Configuration
    preserve_core_attributes: bool = Field(  # type: ignore[pydantic-alias]
        default=True,
        description=(
            "Enable core attribute preservation to prevent FIFO eviction "
            "of critical attributes (session_id, event_type, etc.). When "
            "enabled, re-sets core attributes before span.end() to ensure "
            "they survive eviction. Disable only for debugging or extreme "
            "performance requirements."
        ),
        validation_alias=AliasChoices(
            "HH_PRESERVE_CORE_ATTRIBUTES", "preserve_core_attributes"
        ),
    )

    # Dynamic Cache Configuration - Uses dynamic logic for performance optimization
    cache_enabled: bool = Field(  # type: ignore[call-overload,pydantic-alias]
        default=True,
        description="Enable dynamic caching for performance optimization",
        validation_alias=AliasChoices("HH_CACHE_ENABLED", "cache_enabled"),
    )

    cache_max_size: Optional[int] = Field(  # type: ignore[call-overload,pydantic-alias]
        None,
        description="Maximum cache size per cache type (dynamic sizing if None)",
        validation_alias=AliasChoices("HH_CACHE_MAX_SIZE", "cache_max_size"),
        examples=[1000, 5000, 10000],
    )

    cache_ttl: Optional[float] = Field(  # type: ignore[call-overload,pydantic-alias]
        None,
        description="Cache TTL in seconds (dynamic TTL based on cache type if None)",
        validation_alias=AliasChoices("HH_CACHE_TTL", "cache_ttl"),
        examples=[300.0, 600.0, 3600.0],
    )

    cache_cleanup_interval: Optional[float] = Field(  # type: ignore[call-overload,pydantic-alias]  # pylint: disable=line-too-long
        None,
        description="Cache cleanup interval in seconds (dynamic interval if None)",
        validation_alias=AliasChoices(
            "HH_CACHE_CLEANUP_INTERVAL", "cache_cleanup_interval"
        ),
        examples=[60.0, 120.0, 300.0],
    )

    # Session-related fields (for hybrid approach)
    session_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Existing session ID to attach to (must be valid UUID)",
        examples=["550e8400-e29b-41d4-a716-446655440000"],
    )

    inputs: Optional[Dict[str, Any]] = Field(  # type: ignore[call-overload]
        None,
        description="Session input data",
        examples=[{"user_id": "123", "query": "Hello world"}],
    )

    link_carrier: Optional[Dict[str, Any]] = Field(  # type: ignore[call-overload]
        None,
        description="Context propagation carrier for distributed tracing",
        examples=[{"traceparent": "00-...", "baggage": "..."}],
    )

    # Evaluation-related fields (for hybrid approach)
    is_evaluation: bool = Field(default=False, description="Enable evaluation mode")  # type: ignore[call-overload]

    run_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Evaluation run identifier",
        examples=["eval-run-123", "experiment-2024-01-15"],
    )

    dataset_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Dataset identifier for evaluation",
        examples=["dataset-456", "qa-dataset-v2"],
    )

    datapoint_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Specific datapoint identifier",
        examples=["datapoint-789", "question-42"],
    )

    model_config = SettingsConfigDict(
        validate_assignment=True,
        extra="forbid",
        case_sensitive=False,
    )

    @field_validator("server_url", mode="before")
    @classmethod
    def validate_server_url(cls, v: Any) -> str:
        """Validate server URL format with graceful degradation.

        Args:
            v: The server URL to validate

        Returns:
            The validated and normalized server URL, or default if invalid
        """
        if v is None:
            return "https://api.dp1.us.honeyhive.ai"

        validated = _safe_validate_url(
            v,
            "server_url",
            allow_none=False,
            default="https://api.dp1.us.honeyhive.ai",
        )
        # Remove trailing slash for consistency
        return validated.rstrip("/") if validated else "https://api.dp1.us.honeyhive.ai"

    @field_validator("source", mode="before")
    @classmethod
    def validate_source(cls, v: Any) -> str:
        """Validate source environment with graceful degradation.

        Args:
            v: The source environment to validate

        Returns:
            The validated source environment, or "dev" if invalid
        """
        validated = _safe_validate_string(v, "source", allow_none=False, default="dev")
        return validated or "dev"  # Ensure we always return a non-None value

    @field_validator("session_id", mode="before")
    @classmethod
    def validate_session_id(cls, v: Any) -> Optional[str]:
        """Validate session ID format with graceful degradation.

        Args:
            v: The session ID to validate

        Returns:
            The validated and normalized session ID, or None if invalid
        """
        validated = _safe_validate_string(
            v, "session_id", allow_none=True, default=None
        )
        if validated is not None:
            try:
                # Validate UUID format
                uuid.UUID(validated)
                return validated.lower()  # Normalize to lowercase
            except ValueError:
                logger.warning(
                    "Invalid session_id: must be a valid UUID. Using None.",
                    extra={"honeyhive_data": {"session_id": validated}},
                )
                return None
        return validated

    @field_validator("run_id", "dataset_id", "datapoint_id", mode="before")
    @classmethod
    def validate_ids(cls, v: Any) -> Optional[str]:
        """Validate ID fields with graceful degradation.

        Args:
            v: The ID value to validate

        Returns:
            The validated ID, or None if invalid
        """
        return _safe_validate_string(v, "ID field", allow_none=True, default=None)

session_name class-attribute instance-attribute 

session_name: Optional[str] = Field(
    None,
    description="Human-readable session identifier",
    examples=["user-chat-session", "batch-processing-job"],
)

source class-attribute instance-attribute 

source: str = Field(
    default="dev",
    description="Source environment identifier",
    validation_alias=AliasChoices("HH_SOURCE", "source"),
    examples=["dev", "staging", "production"],
)

server_url class-attribute instance-attribute 

server_url: str = Field(
    default="https://api.dp1.us.honeyhive.ai",
    description="Custom HoneyHive server URL",
    validation_alias=AliasChoices(
        "HH_API_URL", "server_url"
    ),
    examples=[
        "https://api.dp1.us.honeyhive.ai",
        "https://custom.honeyhive.com",
    ],
)

disable_http_tracing class-attribute instance-attribute 

disable_http_tracing: bool = Field(
    default=True,
    description="Disable HTTP request tracing (disabled by default)",
    validation_alias=AliasChoices(
        "HH_DISABLE_HTTP_TRACING", "disable_http_tracing"
    ),
)

disable_batch class-attribute instance-attribute 

disable_batch: bool = Field(
    default=False,
    description="Disable batch processing of spans",
    validation_alias=AliasChoices(
        "HH_DISABLE_BATCH", "disable_batch"
    ),
)

disable_tracing class-attribute instance-attribute 

disable_tracing: bool = Field(
    default=False,
    description="Disable all tracing functionality",
    validation_alias=AliasChoices(
        "HH_DISABLE_TRACING", "disable_tracing"
    ),
)

span_name_filters class-attribute instance-attribute 

span_name_filters: Optional[SpanNameFilters] = Field(
    default=None,
    description="Filter spans by name using include/exclude lists. Each filter entry specifies a type ('prefix') and value to match. Excluded spans are dropped before enrichment and export.",
    examples=[
        {
            "exclude": [
                {
                    "type": "prefix",
                    "value": "a2a.client.transports.jsonrpc",
                }
            ]
        }
    ],
)

max_attributes class-attribute instance-attribute 

max_attributes: int = Field(
    default=1024,
    description="Maximum number of attributes per span (OpenTelemetry default: 128, HoneyHive default: 1024)",
    validation_alias=AliasChoices(
        "HH_MAX_ATTRIBUTES", "max_attributes"
    ),
    examples=[128, 256, 500, 1024, 2000],
)

max_events class-attribute instance-attribute 

max_events: int = Field(
    default=1024,
    description="Maximum number of events per span (matches max_attributes because events are flattened to pseudo-attributes)",
    validation_alias=AliasChoices(
        "HH_MAX_EVENTS", "max_events"
    ),
)

max_links: int = Field(
    default=128,
    description="Maximum number of links per span",
    validation_alias=AliasChoices(
        "HH_MAX_LINKS", "max_links"
    ),
)

max_span_size class-attribute instance-attribute 

max_span_size: int = Field(
    default=10 * 1024 * 1024,
    description="Maximum total size of span (attributes + events + links) in bytes",
    validation_alias=AliasChoices(
        "HH_MAX_SPAN_SIZE", "max_span_size"
    ),
    examples=[1048576, 5242880, 10485760, 20971520],
)

preserve_core_attributes class-attribute instance-attribute 

preserve_core_attributes: bool = Field(
    default=True,
    description="Enable core attribute preservation to prevent FIFO eviction of critical attributes (session_id, event_type, etc.). When enabled, re-sets core attributes before span.end() to ensure they survive eviction. Disable only for debugging or extreme performance requirements.",
    validation_alias=AliasChoices(
        "HH_PRESERVE_CORE_ATTRIBUTES",
        "preserve_core_attributes",
    ),
)

cache_enabled class-attribute instance-attribute 

cache_enabled: bool = Field(
    default=True,
    description="Enable dynamic caching for performance optimization",
    validation_alias=AliasChoices(
        "HH_CACHE_ENABLED", "cache_enabled"
    ),
)

cache_max_size class-attribute instance-attribute 

cache_max_size: Optional[int] = Field(
    None,
    description="Maximum cache size per cache type (dynamic sizing if None)",
    validation_alias=AliasChoices(
        "HH_CACHE_MAX_SIZE", "cache_max_size"
    ),
    examples=[1000, 5000, 10000],
)

cache_ttl class-attribute instance-attribute 

cache_ttl: Optional[float] = Field(
    None,
    description="Cache TTL in seconds (dynamic TTL based on cache type if None)",
    validation_alias=AliasChoices(
        "HH_CACHE_TTL", "cache_ttl"
    ),
    examples=[300.0, 600.0, 3600.0],
)

cache_cleanup_interval class-attribute instance-attribute 

cache_cleanup_interval: Optional[float] = Field(
    None,
    description="Cache cleanup interval in seconds (dynamic interval if None)",
    validation_alias=AliasChoices(
        "HH_CACHE_CLEANUP_INTERVAL",
        "cache_cleanup_interval",
    ),
    examples=[60.0, 120.0, 300.0],
)

session_id class-attribute instance-attribute 

session_id: Optional[str] = Field(
    None,
    description="Existing session ID to attach to (must be valid UUID)",
    examples=["550e8400-e29b-41d4-a716-446655440000"],
)

inputs class-attribute instance-attribute 

inputs: Optional[Dict[str, Any]] = Field(
    None,
    description="Session input data",
    examples=[{"user_id": "123", "query": "Hello world"}],
)

link_carrier: Optional[Dict[str, Any]] = Field(
    None,
    description="Context propagation carrier for distributed tracing",
    examples=[{"traceparent": "00-...", "baggage": "..."}],
)

is_evaluation class-attribute instance-attribute 

is_evaluation: bool = Field(
    default=False, description="Enable evaluation mode"
)

run_id class-attribute instance-attribute 

run_id: Optional[str] = Field(
    None,
    description="Evaluation run identifier",
    examples=["eval-run-123", "experiment-2024-01-15"],
)

dataset_id class-attribute instance-attribute 

dataset_id: Optional[str] = Field(
    None,
    description="Dataset identifier for evaluation",
    examples=["dataset-456", "qa-dataset-v2"],
)

datapoint_id class-attribute instance-attribute 

datapoint_id: Optional[str] = Field(
    None,
    description="Specific datapoint identifier",
    examples=["datapoint-789", "question-42"],
)

validate_server_url classmethod 

validate_server_url(v: Any) -> str

Validate server URL format with graceful degradation.

Parameters:

Name Type Description Default
v Any

The server URL to validate

 required

Returns:

Type Description
str

The validated and normalized server URL, or default if invalid
Source code in src/honeyhive/config/models/tracer.py 
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
@field_validator("server_url", mode="before")
@classmethod
def validate_server_url(cls, v: Any) -> str:
    """Validate server URL format with graceful degradation.

    Args:
        v: The server URL to validate

    Returns:
        The validated and normalized server URL, or default if invalid
    """
    if v is None:
        return "https://api.dp1.us.honeyhive.ai"

    validated = _safe_validate_url(
        v,
        "server_url",
        allow_none=False,
        default="https://api.dp1.us.honeyhive.ai",
    )
    # Remove trailing slash for consistency
    return validated.rstrip("/") if validated else "https://api.dp1.us.honeyhive.ai"

validate_source classmethod 

validate_source(v: Any) -> str

Validate source environment with graceful degradation.

Parameters:

Name Type Description Default
v Any

The source environment to validate

 required

Returns:

Type Description
str

The validated source environment, or "dev" if invalid
Source code in src/honeyhive/config/models/tracer.py 
329
330
331
332
333
334
335
336
337
338
339
340
341
@field_validator("source", mode="before")
@classmethod
def validate_source(cls, v: Any) -> str:
    """Validate source environment with graceful degradation.

    Args:
        v: The source environment to validate

    Returns:
        The validated source environment, or "dev" if invalid
    """
    validated = _safe_validate_string(v, "source", allow_none=False, default="dev")
    return validated or "dev"  # Ensure we always return a non-None value

validate_session_id classmethod 

validate_session_id(v: Any) -> Optional[str]

Validate session ID format with graceful degradation.

Parameters:

Name Type Description Default
v Any

The session ID to validate

 required

Returns:

Type Description
Optional[str]

The validated and normalized session ID, or None if invalid
Source code in src/honeyhive/config/models/tracer.py 
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
@field_validator("session_id", mode="before")
@classmethod
def validate_session_id(cls, v: Any) -> Optional[str]:
    """Validate session ID format with graceful degradation.

    Args:
        v: The session ID to validate

    Returns:
        The validated and normalized session ID, or None if invalid
    """
    validated = _safe_validate_string(
        v, "session_id", allow_none=True, default=None
    )
    if validated is not None:
        try:
            # Validate UUID format
            uuid.UUID(validated)
            return validated.lower()  # Normalize to lowercase
        except ValueError:
            logger.warning(
                "Invalid session_id: must be a valid UUID. Using None.",
                extra={"honeyhive_data": {"session_id": validated}},
            )
            return None
    return validated

validate_ids classmethod 

validate_ids(v: Any) -> Optional[str]

Validate ID fields with graceful degradation.

Parameters:

Name Type Description Default
v Any

The ID value to validate

 required

Returns:

Type Description
Optional[str]

The validated ID, or None if invalid
Source code in src/honeyhive/config/models/tracer.py 
370
371
372
373
374
375
376
377
378
379
380
381
@field_validator("run_id", "dataset_id", "datapoint_id", mode="before")
@classmethod
def validate_ids(cls, v: Any) -> Optional[str]:
    """Validate ID fields with graceful degradation.

    Args:
        v: The ID value to validate

    Returns:
        The validated ID, or None if invalid
    """
    return _safe_validate_string(v, "ID field", allow_none=True, default=None)

SessionConfig

Bases: BaseHoneyHiveConfig

Session-specific configuration parameters.

This class handles configuration related to session management, including session linking and input/output data.

Example

session_config = SessionConfig( ... session_id="550e8400-e29b-41d4-a716-446655440000", ... inputs={"user_id": "123", "query": "Hello world"} ... ) tracer = HoneyHiveTracer( ... config=tracer_config, ... session_config=session_config ... )

Source code in src/honeyhive/config/models/tracer.py 
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
class SessionConfig(BaseHoneyHiveConfig):
    """Session-specific configuration parameters.

    This class handles configuration related to session management,
    including session linking and input/output data.

    Example:
        >>> session_config = SessionConfig(
        ...     session_id="550e8400-e29b-41d4-a716-446655440000",
        ...     inputs={"user_id": "123", "query": "Hello world"}
        ... )
        >>> tracer = HoneyHiveTracer(
        ...     config=tracer_config,
        ...     session_config=session_config
        ... )
    """

    session_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Existing session ID to attach to (must be valid UUID)",
        examples=["550e8400-e29b-41d4-a716-446655440000"],
    )

    skip_backend_session_creation: bool = Field(  # type: ignore[call-overload]
        default=False,
        description=(
            "If True, skip the init-time backend session creation call. "
            "If a valid session_id is also provided, the SDK trusts that the "
            "session already exists on the backend. Otherwise, callers are "
            "expected to manage session_ids via per-request "
            "create_session(session_id=<uuid>, skip_api_call=True) calls. "
            "Note: an invalid session_id (e.g. non-UUID) triggers the "
            "degraded-mode path and still calls the backend."
        ),
    )

    inputs: Optional[Dict[str, Any]] = Field(  # type: ignore[call-overload]
        None,
        description="Session input data",
        examples=[{"user_id": "123", "query": "Hello world"}],
    )

    link_carrier: Optional[Dict[str, Any]] = Field(  # type: ignore[call-overload]
        None,
        description="Context propagation carrier for distributed tracing",
        examples=[{"traceparent": "00-...", "baggage": "..."}],
    )

    model_config = SettingsConfigDict(
        validate_assignment=True,
        extra="forbid",
        case_sensitive=False,
    )

    @field_validator("session_id", mode="before")
    @classmethod
    def validate_session_id(cls, v: Any) -> Optional[str]:
        """Validate session ID format with graceful degradation.

        Args:
            v: The session ID to validate

        Returns:
            The validated and normalized session ID, or None if invalid
        """
        validated = _safe_validate_string(
            v, "session_id", allow_none=True, default=None
        )
        if validated is not None:
            try:
                # Validate UUID format
                uuid.UUID(validated)
                return validated.lower()  # Normalize to lowercase
            except ValueError:
                logger.warning(
                    "Invalid session_id: must be a valid UUID. Using None.",
                    extra={"honeyhive_data": {"session_id": validated}},
                )
                return None
        return validated

session_id class-attribute instance-attribute 

session_id: Optional[str] = Field(
    None,
    description="Existing session ID to attach to (must be valid UUID)",
    examples=["550e8400-e29b-41d4-a716-446655440000"],
)

skip_backend_session_creation class-attribute instance-attribute 

skip_backend_session_creation: bool = Field(
    default=False,
    description="If True, skip the init-time backend session creation call. If a valid session_id is also provided, the SDK trusts that the session already exists on the backend. Otherwise, callers are expected to manage session_ids via per-request create_session(session_id=<uuid>, skip_api_call=True) calls. Note: an invalid session_id (e.g. non-UUID) triggers the degraded-mode path and still calls the backend.",
)

inputs class-attribute instance-attribute 

inputs: Optional[Dict[str, Any]] = Field(
    None,
    description="Session input data",
    examples=[{"user_id": "123", "query": "Hello world"}],
)

link_carrier: Optional[Dict[str, Any]] = Field(
    None,
    description="Context propagation carrier for distributed tracing",
    examples=[{"traceparent": "00-...", "baggage": "..."}],
)

validate_session_id classmethod 

validate_session_id(v: Any) -> Optional[str]

Validate session ID format with graceful degradation.

Parameters:

Name Type Description Default
v Any

The session ID to validate

 required

Returns:

Type Description
Optional[str]

The validated and normalized session ID, or None if invalid
Source code in src/honeyhive/config/models/tracer.py 
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
@field_validator("session_id", mode="before")
@classmethod
def validate_session_id(cls, v: Any) -> Optional[str]:
    """Validate session ID format with graceful degradation.

    Args:
        v: The session ID to validate

    Returns:
        The validated and normalized session ID, or None if invalid
    """
    validated = _safe_validate_string(
        v, "session_id", allow_none=True, default=None
    )
    if validated is not None:
        try:
            # Validate UUID format
            uuid.UUID(validated)
            return validated.lower()  # Normalize to lowercase
        except ValueError:
            logger.warning(
                "Invalid session_id: must be a valid UUID. Using None.",
                extra={"honeyhive_data": {"session_id": validated}},
            )
            return None
    return validated

EvaluationConfig

Bases: BaseHoneyHiveConfig

Evaluation-specific configuration parameters.

This class handles configuration for evaluation scenarios, including dataset and run management.

Example

eval_config = EvaluationConfig( ... is_evaluation=True, ... run_id="eval-run-123", ... dataset_id="dataset-456", ... datapoint_id="datapoint-789" ... ) tracer = HoneyHiveTracer( ... config=tracer_config, ... evaluation_config=eval_config ... )

Source code in src/honeyhive/config/models/tracer.py 
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
class EvaluationConfig(BaseHoneyHiveConfig):
    """Evaluation-specific configuration parameters.

    This class handles configuration for evaluation scenarios,
    including dataset and run management.

    Example:
        >>> eval_config = EvaluationConfig(
        ...     is_evaluation=True,
        ...     run_id="eval-run-123",
        ...     dataset_id="dataset-456",
        ...     datapoint_id="datapoint-789"
        ... )
        >>> tracer = HoneyHiveTracer(
        ...     config=tracer_config,
        ...     evaluation_config=eval_config
        ... )
    """

    is_evaluation: bool = Field(default=False, description="Enable evaluation mode")  # type: ignore[call-overload]

    run_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Evaluation run identifier",
        examples=["eval-run-123", "experiment-2024-01-15"],
    )

    dataset_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Dataset identifier for evaluation",
        examples=["dataset-456", "qa-dataset-v2"],
    )

    datapoint_id: Optional[str] = Field(  # type: ignore[call-overload]
        None,
        description="Specific datapoint identifier",
        examples=["datapoint-789", "question-42"],
    )

    model_config = SettingsConfigDict(
        validate_assignment=True,
        extra="forbid",
        case_sensitive=False,
    )

    @field_validator("run_id", "dataset_id", "datapoint_id", mode="before")
    @classmethod
    def validate_ids(cls, v: Any) -> Optional[str]:
        """Validate ID fields with graceful degradation.

        Args:
            v: The ID value to validate

        Returns:
            The validated ID, or None if invalid
        """
        return _safe_validate_string(v, "ID field", allow_none=True, default=None)

is_evaluation class-attribute instance-attribute 

is_evaluation: bool = Field(
    default=False, description="Enable evaluation mode"
)

run_id class-attribute instance-attribute 

run_id: Optional[str] = Field(
    None,
    description="Evaluation run identifier",
    examples=["eval-run-123", "experiment-2024-01-15"],
)

dataset_id class-attribute instance-attribute 

dataset_id: Optional[str] = Field(
    None,
    description="Dataset identifier for evaluation",
    examples=["dataset-456", "qa-dataset-v2"],
)

datapoint_id class-attribute instance-attribute 

datapoint_id: Optional[str] = Field(
    None,
    description="Specific datapoint identifier",
    examples=["datapoint-789", "question-42"],
)

validate_ids classmethod 

validate_ids(v: Any) -> Optional[str]

Validate ID fields with graceful degradation.

Parameters:

Name Type Description Default
v Any

The ID value to validate

 required

Returns:

Type Description
Optional[str]

The validated ID, or None if invalid
Source code in src/honeyhive/config/models/tracer.py 
511
512
513
514
515
516
517
518
519
520
521
522
@field_validator("run_id", "dataset_id", "datapoint_id", mode="before")
@classmethod
def validate_ids(cls, v: Any) -> Optional[str]:
    """Validate ID fields with graceful degradation.

    Args:
        v: The ID value to validate

    Returns:
        The validated ID, or None if invalid
    """
    return _safe_validate_string(v, "ID field", allow_none=True, default=None)