Skip to content

Commit 4858c4c

Browse files
committed
docs: add OTLP span export strategy to non-instrumentor integration spec
- Add comprehensive OTLP export configuration and strategy section - Document how spans are shipped to HoneyHive backend via OTLP protocol - Cover dual export scenarios (framework + HoneyHive exporters) - Add export endpoint configuration and authentication details - Include performance requirements for OTLP export overhead - Address export conflicts and coexistence patterns - Update requirements numbering and add export-specific requirements Key additions: - OTLP endpoint: {api_url}/opentelemetry/v1/traces - Authentication headers: Bearer token, X-Project, X-Source - Batch processing configuration via environment variables - Export reliability requirements (99.9% success rate) - Dual export support without conflicts
1 parent 4474e14 commit 4858c4c

1 file changed

Lines changed: 133 additions & 13 deletions

File tree

  • .agent-os/specs/2025-09-05-non-instrumentor-integrations

‎.agent-os/specs/2025-09-05-non-instrumentor-integrations/specs.md‎

Lines changed: 133 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -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
120139
tracer = 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
124144
framework = AIFramework() # Uses HoneyHive's TracerProvider
@@ -127,10 +147,26 @@ result = framework.execute("task") # Automatically traced
127147

128148
**Flow**:
129149
1. 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
141177
tracer = 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**:
148184
1. Framework creates TracerProvider
149-
2. Framework sets global TracerProvider
185+
2. Framework sets global TracerProvider (may have its own exporters)
150186
3. 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

Comments
 (0)