OpenTelemetry Integration Architecture

Requirements and Dataflow

Core Requirements

  • OpenTelemetry-compatible metrics export with standard format compliance
  • Distributed tracing integration with trace and span management
  • Service identification with environment and version tracking
  • Custom attribute support for application-specific context
  • Resource metadata integration for service discovery and monitoring
  • Standards-compliant metric types and measurement units

Data Flow Patterns

  1. Metrics Export: Internal Metrics → OTel Format Conversion → Export Pipeline → Collector
  2. Trace Generation: Request Start → Span Creation → Context Propagation → Span Completion → Export
  3. Resource Attribution: Service Metadata → Resource Annotation → Metric Attribution → Context Enhancement
  4. Custom Attributes: Application Context → Attribute Extraction → Metric Enrichment → Export
  5. Distributed Context: Trace Context → Span Relationships → Cross-Service Correlation → Analysis

High-level Purpose and Responsibilities

Primary Purpose

Provides OpenTelemetry-compliant observability integration that enables standardized metrics export, distributed tracing, and seamless integration with modern observability platforms and tools.

Core Responsibilities

  • Standards Compliance: OpenTelemetry specification adherence for interoperability
  • Metrics Export: Convert internal metrics to OTel format with proper metadata
  • Distributed Tracing: Span lifecycle management with context propagation
  • Resource Management: Service identification and environment context
  • Custom Attribution: Application-specific context and metadata enrichment
  • Integration Support: Seamless integration with OTel collectors and platforms

Key Abstractions and Interfaces

Core OTel Integration

  • OtelMetricsExporter: Service-aware metrics exporter with custom configuration
  • OtelMetric: Standard-compliant metric representation with resource attribution
  • OtelResource: Service identification and deployment context information
  • OtelSpan: Distributed tracing span with parent-child relationship tracking

Metric Standards

  • MetricType: Counter, Gauge, Histogram, Summary classification system
  • CustomAttributes: Application-specific context and metadata support
  • ResourceAttributes: Service, version, environment, and instance identification
  • TimestampManagement: UTC timestamp handling for metric correlation

Tracing Integration

  • TraceContext: Distributed trace correlation with trace and span IDs
  • SpanRelationships: Parent-child span hierarchy for request flow tracking
  • OperationNaming: Consistent operation identification for trace analysis
  • ContextPropagation: Cross-service trace context transmission

Data Transformations and Flow

Metrics Transformation Pipeline

Internal Metrics → OTel Format Conversion → Resource Attribution → Export Serialization → Collector

Trace Context Flow

Request → Span Creation → Context Injection → Service Calls → Context Extraction → Span Completion

Resource Attribution Process

Service Configuration → Resource Metadata → Metric Attribution → Context Enrichment → Export

Custom Attribute Processing

Application Context → Attribute Extraction → Validation → Metric Enhancement → Export Pipeline

Dependencies and Interactions

External Dependencies

  • chrono: UTC timestamp management for metric correlation and trace timing
  • serde: JSON serialization for OTel format compliance and export
  • std::collections: HashMap for custom attributes and resource metadata
  • tracing: Integration with Rust tracing ecosystem for span management

Internal System Interactions

  • Global Metrics: Integration with internal metrics collection for export conversion
  • HTTP Layer: Request tracing with automatic span generation and context propagation
  • Configuration: Service metadata and OTel exporter configuration
  • External Systems: OTel collector integration for metrics and trace export

Architectural Patterns

Standards-Compliant Export

  • OpenTelemetry specification adherence for maximum interoperability
  • Standard metric types with proper unit and description metadata
  • Resource attribution following OTel semantic conventions
  • Compatible serialization formats for collector integration

Distributed Tracing Integration

  • Automatic span creation with request-response lifecycle tracking
  • Context propagation using standard OTel headers and formats
  • Parent-child span relationships for complex request flows
  • Integration with external tracing systems and APM platforms

Service Discovery and Identification

  • Comprehensive resource metadata for service identification
  • Environment-aware configuration for deployment-specific context
  • Version tracking for release correlation and analysis
  • Instance identification for horizontal scaling scenarios

Custom Context Enhancement

  • Flexible attribute system for application-specific metadata
  • Configurable context extraction from request and application state
  • Custom resource attributes for enhanced service identification
  • Integration with business logic for domain-specific context

Performance and Scalability

  • Efficient metric conversion with minimal overhead
  • Batch export capabilities for high-throughput scenarios
  • Configurable export intervals and buffer management
  • Resource-conscious span creation and management