Skip to content

DI Metrics API Reference

Overview

The TD-020 external bootstrap runtime introduces comprehensive metrics tracking for both container operations and bootstrap execution. This API reference covers the metrics components.

ContainerMetrics

Module: loryth.common.di.container

Container-owned operational metrics tracking registration, resolution, and cache behavior.

Properties

snapshot

Return current metrics snapshot for monitoring.

@property
def snapshot(self) -> ContainerMetricsSnapshot

Returns: ContainerMetricsSnapshot dataclass containing registration and resolution metrics.

Snapshot Dataclasses

@dataclass
class ContainerRegistrationMetricsSnapshot:
    singleton_count: int
    transient_count: int
    factory_count: int
    instance_count: int
    count: int


@dataclass
class ContainerResolutionMetricsSnapshot:
    count: int
    duration_total_ms: float
    duration_avg_ms: float
    cache_hit_count: int
    cache_miss_count: int
    cache_hit_rate: float
    failure_count: int


@dataclass
class ContainerMetricsSnapshot:
    registration: ContainerRegistrationMetricsSnapshot
    resolution: ContainerResolutionMetricsSnapshot

Example

from loryth.common.di.container import Container

# Create container and register services
container = Container()
container.register_singleton(IService, Service)
container.resolve(IService)

# Check metrics
metrics = container.metrics.snapshot
print(f"Total registrations: {metrics.registration.count}")
print(f"Singleton registrations: {metrics.registration.singleton_count}")
print(f"Cache hit rate: {metrics.resolution.cache_hit_rate:.2%}")

BootstrapMetrics

Module: loryth.common.di.bootstrap

Runtime-owned metrics tracking bootstrap execution across all containers bootstrapped by a runtime instance.

Properties

snapshot

Return cumulative metrics snapshot for monitoring.

@property
def snapshot(self) -> BootstrapMetricsSnapshot

Returns: BootstrapMetricsSnapshot dataclass detailing bootstrap throughput, scanning, validation, and timing information.

Snapshot Dataclasses

@dataclass
class BootstrapBootstrapsSnapshot:
    total: int
    successes: int
    failures: int
    success_rate: float
    average_duration_ms: float


@dataclass
class BootstrapRegistrationSnapshot:
    total_steps_executed: int
    average_steps_per_bootstrap: float


@dataclass
class BootstrapScanningSnapshot:
    modules_scanned: int
    classes_discovered: int


@dataclass
class BootstrapValidationSnapshot:
    cycles_detected: int
    dependency_errors: int


@dataclass
class BootstrapPhaseTimingSnapshot:
    registration: float
    validation: float
    preparation: float


@dataclass
class BootstrapTimingSnapshot:
    total_duration_ms: float
    phase_breakdown_ms: BootstrapPhaseTimingSnapshot


@dataclass
class BootstrapMetricsSnapshot:
    bootstraps: BootstrapBootstrapsSnapshot
    registrations: BootstrapRegistrationSnapshot
    scanning: BootstrapScanningSnapshot
    validation: BootstrapValidationSnapshot
    timings: BootstrapTimingSnapshot

Example

from loryth.common.di.bootstrap import BootstrapRuntime, BootstrapPlan

# Create runtime and execute multiple bootstraps
runtime = BootstrapRuntime()

# Bootstrap container 1
plan1 = BootstrapPlan(registrations=(...))
runtime.bootstrap(container1, plan1)

# Bootstrap container 2  
plan2 = BootstrapPlan(registrations=(...))
runtime.bootstrap(container2, plan2)

# Check cumulative metrics
metrics = runtime.metrics.snapshot
print(f"Total bootstraps: {metrics.bootstraps.total}")
print(f"Success rate: {metrics.bootstraps.success_rate:.2%}")

Metrics Access Patterns

Container Operational Monitoring

# Monitor container performance
container = Container()

# Register and resolve services
container.register_singleton(IService, Service)
container.register_transient(ILogger, ConsoleLogger)

service = container.resolve(IService)
logger = container.resolve(ILogger)

# Analyze operational metrics
stats = container.metrics.snapshot
print(f"Registrations: {stats.registration.count}")
print(f"Cache hits: {stats.resolution.cache_hit_count}")
print(f"Cache hit rate: {stats.resolution.cache_hit_rate:.2%}")
print(f"Average resolution time: {stats.resolution.duration_avg_ms:.2f}ms")

Bootstrap Execution Monitoring

# Monitor bootstrap performance
runtime = BootstrapRuntime()

# Execute multiple bootstraps
for i in range(5):
    container = Container()
    plan = BootstrapPlan(registrations=(...))
    runtime.bootstrap(container, plan)

# Analyze cumulative bootstrap metrics
stats = runtime.metrics.snapshot
print(f"Total bootstraps: {stats.bootstraps.total}")
print(f"Success rate: {stats.bootstraps.success_rate:.2%}")
print(f"Average steps per bootstrap: {stats.registrations.average_steps_per_bootstrap:.1f}")
print(
    f"Phase breakdown: "
    f"registration={stats.timings.phase_breakdown_ms.registration:.2f}ms, "
    f"validation={stats.timings.phase_breakdown_ms.validation:.2f}ms, "
    f"preparation={stats.timings.phase_breakdown_ms.preparation:.2f}ms"
)

Performance Analysis

# Compare bootstrap performance
runtime = BootstrapRuntime()

# Bootstrap with validation
plan_with_validation = BootstrapPlan(
    registrations=(...),
    validate_dependencies=True,
    eager_prepare=True,
)
runtime.bootstrap(container1, plan_with_validation)

# Bootstrap without validation
plan_without_validation = BootstrapPlan(
    registrations=(...),
    validate_dependencies=False,
    eager_prepare=False,
)
runtime.bootstrap(container2, plan_without_validation)

# Compare timing breakdown
stats = runtime.metrics.snapshot
validation_time = stats.timings.phase_breakdown_ms.validation
preparation_time = stats.timings.phase_breakdown_ms.preparation
print(f"Validation time: {validation_time:.2f}ms")
print(f"Preparation time: {preparation_time:.2f}ms")

Error Rate Monitoring

# Monitor bootstrap failure rates
runtime = BootstrapRuntime()

# Execute bootstraps (some may fail)
for i in range(10):
    try:
        container = Container()
        plan = BootstrapPlan(registrations=(...))
        runtime.bootstrap(container, plan)
    except Exception:
        # Handle bootstrap failures
        pass

# Analyze failure patterns
stats = runtime.metrics.snapshot
print(f"Total attempts: {stats.bootstraps.total}")
print(f"Successes: {stats.bootstraps.successes}")
print(f"Failures: {stats.bootstraps.failures}")
print(f"Success rate: {stats.bootstraps.success_rate:.2%}")

Integration with Observability

Container Metrics in Production

# Export container metrics to monitoring system
container = Container()

# ... application logic ...

# Periodically export metrics
metrics = container.metrics.snapshot

# Send to monitoring system
monitoring_system.record("di.registrations.total", metrics.registration.count)
monitoring_system.record("di.cache.hit_rate", metrics.resolution.cache_hit_rate)
monitoring_system.record(
    "di.resolutions.average_duration_ms", metrics.resolution.duration_avg_ms
)

Bootstrap Metrics in CI/CD

# Monitor bootstrap performance in CI
runtime = BootstrapRuntime()

# Bootstrap application
container = Container()
plan = build_bootstrap_plan()
runtime.bootstrap(container, plan)

# Check performance thresholds
stats = runtime.metrics.snapshot
total_duration = stats.timings.total_duration_ms

if total_duration > 1000:  # 1 second threshold
    print(f"WARNING: Slow bootstrap detected: {total_duration:.2f}ms")
    # Fail CI build or log warning

Field Descriptions

ContainerMetrics Fields

  • registration.singleton_count: Singleton registrations recorded
  • registration.transient_count: Transient registrations recorded
  • registration.factory_count: Factory registrations recorded
  • registration.instance_count: Instance registrations recorded
  • registration.count: Total registrations across all lifecycles
  • resolution.count: Total resolution attempts (hits + misses + failures)
  • resolution.duration_total_ms: Aggregate resolution duration in milliseconds
  • resolution.duration_avg_ms: Average resolution duration in milliseconds
  • resolution.cache_hit_count: Number of cache hits during resolution
  • resolution.cache_miss_count: Number of cache misses during resolution
  • resolution.cache_hit_rate: Cache hit percentage
  • resolution.failure_count: Failed resolution attempts

BootstrapMetrics Fields

  • bootstraps.total: Total bootstrap executions
  • bootstraps.successes: Successful bootstraps
  • bootstraps.failures: Failed bootstraps
  • bootstraps.success_rate: Bootstrap success percentage
  • bootstraps.average_duration_ms: Average bootstrap duration
  • registrations.total_steps_executed: Total registration steps executed
  • registrations.average_steps_per_bootstrap: Average steps executed per bootstrap
  • scanning.modules_scanned: Modules scanned (when scanning enabled)
  • scanning.classes_discovered: Annotated classes discovered during scanning
  • validation.cycles_detected: Cycle validation failures recorded
  • validation.dependency_errors: Dependency-related bootstrap failures
  • timings.total_duration_ms: Total bootstrap duration in milliseconds
  • timings.phase_breakdown_ms.registration: Registration phase duration
  • timings.phase_breakdown_ms.validation: Validation phase duration
  • timings.phase_breakdown_ms.preparation: Preparation phase duration
  • scanning.classes_discovered: Classes discovered (when scanning enabled)
  • validation.cycles_detected: Circular dependencies detected
  • validation.dependency_errors: Dependency validation errors
  • timings.total_duration_ms: Total bootstrap time across all executions
  • timings.phase_breakdown_ms: Time breakdown by bootstrap phase

See Also