Architecture Overview

Note

This document provides a high-level overview of the HoneyHive SDK architecture and how its components work together.

System Overview

The HoneyHive Python SDK is built around several key architectural principles:

  • OpenTelemetry Native: Built on industry-standard observability frameworks

  • BYOI (Bring Your Own Instrumentor): Flexible dependency management

  • Multi-Instance Support: Independent tracer instances for complex applications

  • Graceful Degradation: Never crashes your application

High-Level Architecture:

        %%{init: {'theme':'base', 'themeVariables': {'primaryColor': '#1565c0', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'secondaryColor': '#2e7d32', 'tertiaryColor': '#ef6c00', 'background': 'transparent', 'mainBkg': 'transparent', 'secondBkg': 'transparent', 'nodeBkg': '#1565c0', 'nodeBorder': '#333333', 'clusterBkg': 'transparent', 'clusterBorder': '#333333', 'defaultLinkColor': '#333333', 'titleColor': '#333333', 'edgeLabelBackground': 'transparent', 'nodeTextColor': '#ffffff'}, 'flowchart': {'linkColor': '#333333', 'linkWidth': 2}}}%%
graph TB
    subgraph "Application Layer"
        UA[User Code]
    end

    subgraph "HoneyHive SDK"
        subgraph "SDK Layer"
            T["Tracers<br/>(Multi-Instance)"]
            API[API Client]
            E[Evaluation]
        end

        subgraph "OpenTelemetry Layer"
            TP["TracerProvider<br/>(Smart Management)"]
            SE[Span Exporter]
            I[Instrumentation]
        end

        subgraph "Transport Layer"
            H[HTTPX]
            CP[Connection Pool]
            R[Retry Logic]
        end
    end

    subgraph "HoneyHive API"
        S[Sessions]
        EV[Events]
        M[Metrics]
    end

    UA ==> T
    UA ==> API
    UA ==> E

    T ==> TP
    API ==> H
    E ==> API

    TP ==> SE
    SE ==> H
    H ==> CP
    CP ==> R

    R ==> S
    R ==> EV
    R ==> M

    classDef sdkLayer fill:#1a237e,stroke:#333333,stroke-width:2px,color:#ffffff
    classDef otelLayer fill:#e65100,stroke:#333333,stroke-width:2px,color:#ffffff
    classDef transportLayer fill:#ad1457,stroke:#333333,stroke-width:2px,color:#ffffff
    classDef apiLayer fill:#4a148c,stroke:#333333,stroke-width:2px,color:#ffffff
    classDef userLayer fill:#1b5e20,stroke:#333333,stroke-width:2px,color:#ffffff

    class T,API,E sdkLayer
    class TP,SE,I otelLayer
    class H,CP,R transportLayer
    class S,EV,M apiLayer
    class UA userLayer

Core Architecture Components

1. HoneyHiveTracer

The central component that manages observability:

HoneyHiveTracer
├── OpenTelemetry TracerProvider
├── Span Processors
├── Exporters (HoneyHive API)
└── Instrumentor Management

2. Instrumentor System

Pluggable components for different LLM providers:

Instrumentor Architecture
├── OpenAI Instrumentor
├── Anthropic Instrumentor
├── Google AI Instrumentor
└── Custom Instrumentors

3. Evaluation Framework

Built-in and custom evaluation capabilities:

Evaluation System
├── Built-in Evaluators
├── Custom Evaluator Base Classes
├── Multi-Evaluator Support
└── Batch Evaluation

4. Data Pipeline

How observability data flows through the system:

Data Flow
Function Call → Span Creation → Attribute Collection →
Evaluation (optional) → Export → HoneyHive Platform

Key Design Decisions

OpenTelemetry Foundation

Built on OpenTelemetry for: - Industry standard compliance - Interoperability with existing tools - Future-proofing - Community support

BYOI Architecture

Separates concerns between: - Core observability infrastructure (HoneyHive) - LLM library integration (Instrumentors) - Business logic (Your application)

Multi-Instance Design

Enables: - Environment separation (dev/staging/prod) - Service isolation in microservices - Workflow-specific configuration - Team-based access control

Provider Strategy Intelligence

HoneyHive automatically detects the OpenTelemetry environment and chooses the optimal integration strategy:

  • Main Provider: When no functioning provider exists (NoOp/Proxy/Empty TracerProvider)

    • HoneyHive becomes the global TracerProvider

    • All instrumentor spans (OpenAI, Anthropic, etc.) flow through HoneyHive

    • Prevents span loss from empty providers

  • Independent Provider: When a functioning provider already exists

    • HoneyHive creates an isolated TracerProvider

    • Maintains complete separation from existing observability systems

    • Ensures no interference with existing tracing infrastructure

See Also