@@ -98,7 +98,26 @@ graph TB
9898 - Preserve existing span attributes and metadata
9999 - Handle span lifecycle events (start, end, error)
100100
101- #### REQ-NOI-003: Initialization Order Independence
101+ #### REQ-NOI-003: OTLP Span Export Integration
102+ ** Requirement** : Ensure spans are exported to HoneyHive backend via OTLP protocol regardless of provider setup
103+
104+ ** Implementation Components** :
105+ - ** COMP-SE-001** : OTLP Exporter Manager
106+ - Configure OTLPSpanExporter with HoneyHive endpoint
107+ - Set proper authentication headers (Bearer token, X-Project, X-Source)
108+ - Handle OTLP export in both main and secondary provider scenarios
109+
110+ - ** COMP-SE-002** : Export Strategy Selector
111+ - Main Provider Strategy: Add OTLP exporter directly to HoneyHive provider
112+ - Secondary Provider Strategy: Add OTLP exporter to existing provider
113+ - Fallback Strategy: Console export when OTLP integration fails
114+
115+ - ** COMP-SE-003** : Export Configuration Manager
116+ - Endpoint: ` {api_url}/opentelemetry/v1/traces `
117+ - Headers: Authorization, X-Project, X-Source
118+ - Batch processing with configurable batch size and timeout
119+
120+ #### REQ-NOI-004: Initialization Order Independence
102121** Requirement** : Work correctly regardless of HoneyHive vs framework initialization order
103122
104123** Implementation Components** :
@@ -119,6 +138,7 @@ graph TB
119138# HoneyHive initializes first and becomes main provider
120139tracer = HoneyHiveTracer.init(api_key = " ..." , project = " ..." )
121140# Creates new TracerProvider, sets as global
141+ # Adds HoneyHive span processor + OTLP exporter
122142
123143# Framework uses existing global provider
124144framework = AIFramework() # Uses HoneyHive's TracerProvider
@@ -127,10 +147,26 @@ result = framework.execute("task") # Automatically traced
127147
128148** Flow** :
1291491 . HoneyHive creates TracerProvider
130- 2 . HoneyHive sets global TracerProvider
131- 3 . Framework discovers existing provider
132- 4 . Framework uses HoneyHive's provider
133- 5 . All spans automatically enriched
150+ 2 . HoneyHive adds span processor for enrichment
151+ 3 . HoneyHive adds OTLP exporter to ship spans to backend
152+ 4 . HoneyHive sets global TracerProvider
153+ 5 . Framework discovers existing provider
154+ 6 . Framework uses HoneyHive's provider
155+ 7 . All spans automatically enriched and exported to HoneyHive
156+
157+ ** OTLP Export Configuration** :
158+ ``` python
159+ # Automatic OTLP exporter setup
160+ otlp_exporter = OTLPSpanExporter(
161+ endpoint = f " { config.api_url} /opentelemetry/v1/traces " ,
162+ headers = {
163+ " Authorization" : f " Bearer { api_key} " ,
164+ " X-Project" : project,
165+ " X-Source" : source,
166+ },
167+ )
168+ provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
169+ ```
134170
135171#### Pattern 2: Framework First (Secondary Provider)
136172``` python
@@ -139,17 +175,42 @@ framework = AIFramework() # Creates and sets TracerProvider
139175
140176# HoneyHive detects existing provider and integrates
141177tracer = HoneyHiveTracer.init(api_key = " ..." , project = " ..." )
142- # Adds span processor to existing provider
178+ # Adds span processor + OTLP exporter to existing provider
143179
144- result = framework.execute(" task" ) # Spans enriched by HoneyHive processor
180+ result = framework.execute(" task" ) # Spans enriched and exported to HoneyHive
145181```
146182
147183** Flow** :
1481841 . Framework creates TracerProvider
149- 2 . Framework sets global TracerProvider
185+ 2 . Framework sets global TracerProvider (may have its own exporters)
1501863 . HoneyHive detects existing provider
151- 4 . HoneyHive adds span processor to existing provider
152- 5 . Framework spans enriched with HoneyHive context
187+ 4 . HoneyHive adds span processor to existing provider for enrichment
188+ 5 . HoneyHive adds OTLP exporter to existing provider for HoneyHive export
189+ 6 . Framework spans enriched with HoneyHive context and exported to both framework backend and HoneyHive
190+
191+ ** Critical OTLP Export Handling** :
192+ ``` python
193+ # HoneyHive adds OTLP exporter to existing provider
194+ existing_provider = trace.get_tracer_provider()
195+
196+ # Add HoneyHive span processor for enrichment
197+ honeyhive_processor = HoneyHiveSpanProcessor(session_id = session_id)
198+ existing_provider.add_span_processor(honeyhive_processor)
199+
200+ # Add OTLP exporter for HoneyHive backend
201+ if otlp_enabled and not test_mode:
202+ otlp_exporter = OTLPSpanExporter(
203+ endpoint = f " { config.api_url} /opentelemetry/v1/traces " ,
204+ headers = {
205+ " Authorization" : f " Bearer { api_key} " ,
206+ " X-Project" : project,
207+ " X-Source" : source,
208+ },
209+ )
210+ existing_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
211+
212+ # Result: Spans go to both framework's exporters AND HoneyHive
213+ ```
153214
154215#### Pattern 3: Multi-Framework Integration
155216``` python
@@ -250,21 +311,80 @@ def validate_integration() -> IntegrationStatus:
250311 )
251312```
252313
314+ ### OTLP Export Strategy
315+
316+ #### Export Endpoint Configuration
317+ ``` python
318+ # HoneyHive OTLP endpoint
319+ endpoint = f " { config.api_url} /opentelemetry/v1/traces "
320+ # Default: https://api.honeyhive.ai/opentelemetry/v1/traces
321+
322+ # Required headers for authentication and context
323+ headers = {
324+ " Authorization" : f " Bearer { api_key} " ,
325+ " X-Project" : project, # Project context
326+ " X-Source" : source, # Environment (dev, staging, production)
327+ }
328+ ```
329+
330+ #### Export Scenarios
331+
332+ ** Scenario 1: HoneyHive as Main Provider**
333+ - HoneyHive controls the TracerProvider
334+ - Adds OTLP exporter directly to its provider
335+ - All spans (framework + custom) exported to HoneyHive
336+ - Framework may not have its own export mechanism
337+
338+ ** Scenario 2: HoneyHive as Secondary Provider**
339+ - Framework controls the TracerProvider
340+ - Framework may have its own exporters (console, custom backend, etc.)
341+ - HoneyHive adds OTLP exporter to existing provider
342+ - ** Result** : Spans exported to BOTH framework backend AND HoneyHive
343+ - ** Benefit** : Unified observability without disrupting existing telemetry
344+
345+ ** Scenario 3: Export Conflicts and Resolution**
346+ - Multiple OTLP exporters can coexist on same provider
347+ - Each exporter runs independently via BatchSpanProcessor
348+ - No conflicts between HoneyHive and framework exporters
349+ - Performance impact: Additional network calls per span batch
350+
351+ #### Export Configuration Management
352+ ``` python
353+ # Environment variable controls
354+ HH_OTLP_ENABLED = true # Enable/disable OTLP export (default: true)
355+ HH_OTLP_ENDPOINT = ... # Override default endpoint
356+ HH_API_URL = ... # Base API URL (affects OTLP endpoint)
357+
358+ # Batch processing configuration
359+ OTEL_BSP_MAX_EXPORT_BATCH_SIZE = 512 # Batch size (default: 512)
360+ OTEL_BSP_EXPORT_TIMEOUT = 30000 # Export timeout ms (default: 30s)
361+ OTEL_BSP_SCHEDULE_DELAY = 5000 # Batch delay ms (default: 5s)
362+ ```
363+
253364## Requirements
254365
255- ### REQ-NOI-004 : Performance Requirements
366+ ### REQ-NOI-005 : Performance Requirements
256367- ** Span Processing Overhead** : <1ms per span for HoneyHive enrichment
257368- ** Memory Overhead** : <5% increase in memory usage
258369- ** Provider Detection** : <10ms for provider detection and integration
370+ - ** OTLP Export Overhead** : <2ms additional latency per span batch
259371- ** Concurrent Access** : Thread-safe operation in multi-threaded environments
260372
261- ### REQ-NOI-005: Compatibility Requirements
373+ ### REQ-NOI-006: OTLP Export Requirements
374+ - ** Export Reliability** : 99.9% successful export rate under normal conditions
375+ - ** Batch Processing** : Configurable batch size (default 512 spans)
376+ - ** Export Timeout** : Configurable timeout with graceful degradation
377+ - ** Dual Export Support** : Coexist with framework exporters without conflicts
378+ - ** Authentication** : Proper Bearer token and project context headers
379+ - ** Endpoint Flexibility** : Support custom HoneyHive API endpoints
380+
381+ ### REQ-NOI-007: Compatibility Requirements
262382- ** OpenTelemetry Versions** : Support OpenTelemetry SDK 1.20+
263383- ** Python Versions** : Support Python 3.11, 3.12, 3.13
264384- ** Framework Compatibility** : Work with any framework using OpenTelemetry directly
265385- ** Provider Types** : Support TracerProvider, ProxyTracerProvider, custom implementations
266386
267- ### REQ-NOI-006 : Error Handling Requirements
387+ ### REQ-NOI-008 : Error Handling Requirements
268388- ** Graceful Degradation** : Framework functionality preserved if HoneyHive integration fails
269389- ** Error Logging** : Clear error messages for integration failures
270390- ** Fallback Modes** : Console logging when full integration impossible
0 commit comments