Motivation

The existing Counter implementation follows a parsing-based approach, relying on metric name patterns like label1:label2:* and inferring implicit relationships through JSON structures, dictionaries, or other nested data formats. Since these structures can vary depending on the feature or how each feature owner decides to implement them, querying, filtering, and aggregating metrics become inconsistent and complex. This lack of explicit structure makes it harder to standardize analysis across different use cases.

This refactor introduces a structured and extensible approach to metric collection, enforcing clear label standards and dimensional analysis while making all relationships and classifications explicit, rather than relying on naming conventions, positional placement, or nested JSON structures. By ensuring consistency, we can simplify querying, filtering, and aggregations, making analytics more scalable and reducing the need for custom metric handling.

Changes

• Moved metrics to metrics.py, making them a standalone concept, not strictly tied to usage.py.
• Introduced MetricRegistry as a singleton for managing all registered metrics (Counters, Gauges, etc.).
• Introduced Metric as the base interface for metrics, enforcing the implementation of the collect() method in all metric types (e.g., Counters, Gauges).
• Updated published event name from ls:usage to ls_metrics
• Set a limit of 8 labels per metric to ensure labels are used effectively as dimensions for time-series analysis, filtering, and aggregations, preventing misuse or unnecessary complexity. A dedicated guide will follow to outline best practices.

Usage Examples

Basic Counter
A Counter tracks the occurrences of an event. It can be used without labels for simple counting:

from localstack.utils.analytics.metrics import Counter

# Define a counter
http_responses = Counter(namespace="http", name="requests")

# Increment
http_responses.increment()
http_responses.increment(value=3)

# Reset
http_responses.reset()

Counters with Labels
Counters can include labels to categorize events more effectively:

from localstack.utils.analytics.metrics import Counter

# Define a counter with labels
chaos_invocations = Counter(namespace="chaos", name="invocations", labels=["operation"])

# Increment
chaos_invocations.labels(operation="fault").increment(value=3)
chaos_invocations.labels(operation="network-effect").increment(value=4)

# Reset
chaos_invocations.labels(operation="fault").reset()
chaos_invocations.labels(operation="network-effect").reset()

Testing

Unit Tests (No External Services Required)

• The test suite includes unit tests that validate metric collection and registry behavior without requiring event publishing to the analytics backend.

End-to-End Testing with the Analytics Backend

For a more in-depth test, follow these steps:

1. Run the Analytics Backend Locally

• Start the analytics backend to capture and process metric events.
• Ensure that environment variables are correctly set to send events to the data platform.

2. Start LocalStack Core with Analytics Enabled

• Start LocalStack Core with the appropriate environment variables to enable analytics and send events to the local backend:

ANALYTICS_API="http://localhost:8000/v1" \
DEBUG=1 \
DEBUG_ANALYTICS=1 \
python -m localstack.cli.main start --host

TODO

What's left to do:

• Instrument Chaos API - PR.
• Complete internal documentation on best practices for metrics and label naming