babylon.metrics

Metrics collection and analysis for Babylon/Babylon.

Metrics are the nervous system of the simulation. They provide feedback on the health of all subsystems.

class babylon.metrics.MetricsCollector[source]

Bases: object

Centralized metrics collection and aggregation.

This class creates independent instances for dependency injection. Each ServiceContainer should have its own MetricsCollector instance.

Note: MetricsCollector is NOT thread-safe for concurrent access. Each ServiceContainer instance MUST have its own MetricsCollector. Concurrent access from multiple threads to the same collector is not supported (simulation runs single-threaded).

Metrics Categories: - performance: Timing, throughput, latency - simulation: Game state metrics (P(S|A), P(S|R), Rent flow) - cache: Hit rates, evictions, memory usage - embedding: Generation times, batch sizes, errors

__init__()[source]

Initialize the metrics collector.

Return type:

None

property enabled: bool

Check if metrics collection is enabled.

record(name, value, tags=None, metadata=None)[source]

Record a metric value.

Parameters:

  • name (str) – Metric name (e.g., “simulation.p_revolution”)

  • value (float) – Numeric value

  • tags (dict[str, str] | None) – Key-value pairs for filtering/grouping

  • metadata (dict[str, Any] | None) – Additional context

Return type:

None

increment(name, value=1)[source]

Increment a counter metric.

Parameters:

  • name (str) – Counter name

  • value (int) – Amount to increment

Return type:

None

gauge(name, value)[source]

Set a gauge metric to a specific value.

Parameters:

  • name (str) – Gauge name

  • value (float) – Current value

Return type:

None

time(name)[source]

Context manager for timing operations.

Parameters:

name (str) – Timer name

Return type:

TimerContext

Returns:

TimerContext that records duration on exit

Example

with collector.time(“embedding.generation”):

embeddings = generate_embeddings(texts)

record_timing(name, duration)[source]

Record a timing measurement directly.

Parameters:

  • name (str) – Timer name

  • duration (float) – Duration in seconds

Return type:

None

record_metric(name, value, context='', object_id=None, context_level=None)[source]

Record a named metric with context.

Parameters:

  • name (str) – Metric name

  • value (float) – Metric value

  • context (str) – Optional context string

  • object_id (str | None) – Optional object identifier

  • context_level (str | None) – Optional context level

Return type:

None

record_cache_event(level, hit)[source]

Record a cache hit or miss event.

Parameters:

  • level (str) – Cache level (e.g., “L1”, “L2”, “embedding”)

  • hit (bool) – Whether this was a cache hit (True) or miss (False)

Return type:

None

record_token_usage(tokens)[source]

Record token usage.

Parameters:

tokens (int) – Number of tokens used

Return type:

None

record_memory_usage(memory_bytes)[source]

Record memory usage.

Parameters:

memory_bytes (float) – Memory usage in bytes

Return type:

None

clear()[source]

Clear all collected metrics.

Used primarily for testing or resetting between game sessions.

Return type:

None

summary()[source]

Get a summary of all collected metrics.

Return type:

dict[str, Any]

Returns:

Dict with counters, gauges, and timer statistics

Modules

collector

Metrics collection system for Babylon/Babylon.