Upload 5 files

aworld/metrics/README.md

@@ -0,0 +1,80 @@
+# Metrics Module
+
+## Overview
+The `aworld.core.metrics` module provides a unified interface for collecting and exporting metrics. It supports various types of metrics (e.g., counters, histograms) and allows exporting data to different monitoring systems (e.g., Prometheus).
+
+## Key Features
+- **Metric Types**:
+  - `Counter`: A cumulative metric that represents a single numerical value that only ever increases.
+  - `UpDownCounter`: A cumulative metric that can increase or decrease.
+  - `Gauge`: A metric that represents a single numerical value that can arbitrarily go up and down.
+  - `Histogram`: A metric that represents the distribution of a set of values.
+
+- **Adapters**:
+  - `PrometheusAdapter`: Exports metrics to Prometheus.
+  - `ConsoleAdapter`: Prints metrics to the console (for debugging purposes).
+
+## Usage Example
+
+```python
+import random
+import time
+from aworld.core.metrics.metric import set_metric_provider, MetricType
+from aworld.core.metrics.prometheus.prometheus_adapter import PrometheusConsoleMetricExporter,
+
+PrometheusMetricProvider
+from aworld.core.metrics.context_manager import MetricContext, ApiMetricTracker
+from aworld.core.metrics.template import MetricTemplate
+
+# Set OpenTelemetry as the metric provider
+# set_metric_provider(OpentelemetryMetricProvider())
+
+# Set Prometheus as the metric provider
+set_metric_provider(PrometheusMetricProvider(PrometheusConsoleMetricExporter(out_interval_secs=2)))
+
+# Define metric templates
+my_counter = MetricTemplate(
+    type=MetricType.COUNTER,
+    name="my_counter",
+    description="My custom counter",
+    unit="1"
+)
+
+my_gauge = MetricTemplate(
+    type=MetricType.GAUGE,
+    name="my_gauge"
+)
+
+my_histogram = MetricTemplate(
+    type=MetricType.HISTOGRAM,
+    name="my_histogram",
+    buckets=[2, 4, 6, 8, 10]
+)
+
+
+# Track API metrics using decorator
+@ApiMetricTracker()
+def test_api():
+    time.sleep(random.uniform(0, 1))
+
+
+# Track custom code block using context manager
+def test_custom_code():
+    with ApiMetricTracker("test_custom_code"):
+        time.sleep(random.uniform(0, 1))
+
+
+# Main loop to generate and record metrics
+while 1:
+    MetricContext.count(my_counter, random.randint(1, 10))
+    MetricContext.gauge_set(my_gauge, random.randint(1, 10))
+    MetricContext.histogram_record(my_histogram, random.randint(1, 10))
+    test_api()
+    test_custom_code()
+    time.sleep(random.random())
+```
+
+## Notes
+- Before using metrics, you must set a metric provider ( set_metric_provider ).
+- Different metric types serve different purposes; choose the appropriate type based on your needs.
+- For production environments, it is recommended to use Prometheus as the exporter.

aworld/metrics/__init__.py

@@ -0,0 +1,9 @@
+# coding: utf-8
+# Copyright (c) 2025 inclusionAI.
+import os
+from aworld.metrics.context_manager import MetricContext
+
+# MetricContext.configure(provider="otlp",
+#                         backend="logfire",
+#                         write_token=os.getenv("LOGFIRE_WRITE_TOKEN")
+# )

aworld/metrics/context_manager.py

@@ -0,0 +1,186 @@
+import time
+import asyncio
+from typing import Callable
+from functools import wraps
+from aworld.metrics.metric import get_metric_provider, MetricType, BaseMetric
+from aworld.metrics.template import MetricTemplate, MetricTemplates
+
+_GLOBAL_METIRCS = {}
+
+
+class MetricContext:
+
+    _initialized = False
+
+    @classmethod
+    def configure(cls,
+                  provider: str,
+                  backend: str,
+                  base_url: str = None,
+                  write_token: str = None,
+                  **kwargs):
+        """
+        Configure the metric provider.
+        Args:
+            provider: The provider of the metric provider.
+            backend: The backend of the metric provider.
+            base_url: The base url of the metric provider.
+            write_token: The write token of the metric provider.
+            export_console: Whether to export the metrics to console.
+            **kwargs: The other parameters of the metric provider.
+        """
+        if cls._initialized:
+            cls.shutdown()
+        if provider == "prometheus":
+            from aworld.metrics.prometheus.prometheus_adapter import configure_prometheus_provider
+            configure_prometheus_provider(
+                backend, base_url, write_token, **kwargs)
+        elif provider == "otlp":
+            from aworld.metrics.opentelemetry.opentelemetry_adapter import configure_otlp_provider
+            configure_otlp_provider(backend, base_url, write_token, **kwargs)
+        cls._initialized = True
+
+    @classmethod
+    def metric_initialized(cls):
+        return cls._initialized
+
+    @staticmethod
+    def get_or_create_metric(template: MetricTemplate):
+        if template.name in _GLOBAL_METIRCS:
+            return _GLOBAL_METIRCS[template.name]
+
+        metric = None
+        if template.type == MetricType.COUNTER:
+            metric = get_metric_provider().create_counter(template.name, template.description, template.unit,
+                                                          template.labels)
+        elif template.type == MetricType.UPDOWNCOUNTER:
+            metric = get_metric_provider().create_un_down_counter(template.name, template.description, template.unit,
+                                                                  template.labels)
+        elif template.type == MetricType.GAUGE:
+            metric = get_metric_provider().create_gauge(template.name, template.description, template.unit,
+                                                        template.labels)
+        elif template.type == MetricType.HISTOGRAM:
+            metric = get_metric_provider().create_histogram(template.name, template.description, template.unit,
+                                                            template.buckets, template.labels)
+
+        _GLOBAL_METIRCS[template.name] = metric
+        return metric
+
+    @classmethod
+    def _validate_type(cls, metric: BaseMetric, type: str):
+        if type != metric._type:
+            raise ValueError(f"metric type {metric._type} is not {type}")
+
+    @classmethod
+    def count(cls, template: MetricTemplate, value: int, labels: dict = None):
+        """
+        Increment a counter metric.
+        """
+        metric = cls.get_or_create_metric(template)
+        cls._validate_type(metric, MetricType.COUNTER)
+        metric.add(value, labels)
+
+    @classmethod
+    def inc(cls, template: MetricTemplate, value: int, labels: dict = None):
+        """
+        Increment a updowncounter metric.
+        """
+        metric = cls.get_or_create_metric(template)
+        cls._validate_type(metric, MetricType.UPDOWNCOUNTER)
+        metric.inc(value, labels)
+
+    @classmethod
+    def dec(cls, template: MetricTemplate, value: int, labels: dict = None):
+        """
+        Decrement a updowncounter metric.
+        """
+        metric = cls.get_or_create_metric(template)
+        cls._validate_type(metric, MetricType.UPDOWNCOUNTER)
+        metric.dec(value, labels)
+
+    @classmethod
+    def gauge_set(cls, template: MetricTemplate, value: int, labels: dict = None):
+        """
+        Set a value to a gauge metric.
+        """
+        metric = cls.get_or_create_metric(template)
+        cls._validate_type(metric, MetricType.GAUGE)
+        metric.set(value, labels)
+
+    @classmethod
+    def histogram_record(cls, template: MetricTemplate, value: int, labels: dict = None):
+        """
+        Set a value to a histogram metric.
+        """
+        metric = cls.get_or_create_metric(template)
+        cls._validate_type(metric, MetricType.HISTOGRAM)
+        metric.record(value, labels)
+
+    @classmethod
+    def shutdown(cls):
+        """
+        Shutdown the metric provider.
+        """
+        provider = get_metric_provider()
+        if provider:
+            provider.shutdown()
+        cls._initialized = False
+
+
+class ApiMetricTracker:
+    """
+    Decorator to track API metrics.
+    """
+
+    def __init__(self, api_name: str = None, func: Callable = None):
+        self.start_time = None
+        self.status = "success"
+        self.func = func
+        self.api_name = api_name
+        if self.api_name is None and self.func is not None:
+            self.api_name = self.func.__name__
+
+    def _new_tracker(self, func: Callable):
+        return self.__class__(func=func)
+
+    def __enter__(self):
+        self.start_time = time.time() * 1000
+
+    def __exit__(self, exc_type, value, traceback):
+        if exc_type is None:
+            self.status = "success"
+        else:
+            self.status = "failure"
+        self._record_metrics(self.api_name, self.start_time, self.status)
+
+    def __call__(self, func: Callable = None) -> Callable:
+        if func is None:
+            return self
+        return self.decorator(func)
+
+    def _record_metrics(self, api_name: str, start_time: float, status: str) -> None:
+        """
+        Record metrics for the API.
+        """
+        elapsed_time = time.time() * 1000 - start_time
+        MetricContext.count(MetricTemplates.REQUEST_COUNT, 1,
+                            labels={"method": api_name, "status": status})
+        MetricContext.histogram_record(MetricTemplates.REQUEST_LATENCY, elapsed_time,
+                                       labels={"method": api_name, "status": status})
+
+    def decorator(self, func):
+        """
+        Decorator to track API metrics.
+        """
+
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            with self._new_tracker(func):
+                return await func(*args, **kwargs)
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            with self._new_tracker(func):
+                return func(*args, **kwargs)
+
+        return async_wrapper if asyncio.iscoroutinefunction(func) else wrapper

aworld/metrics/metric.py

@@ -0,0 +1,287 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Sequence
+
+
+class MetricType:
+    """
+    MetricType is a class for defining the type of a metric.
+    """
+    COUNTER = "counter"
+    UPDOWNCOUNTER = "updowncounter"
+    GAUGE = "gauge"
+    HISTOGRAM = "histogram"
+
+
+class MetricProvider(ABC):
+    """
+    MeterProvider is the entry point of the API. 
+    """
+
+    def __init__(self):
+        # list of exporters
+        self._exporters = []
+
+    @abstractmethod
+    def shutdown(self):
+        """
+        shutdown the metric provider.
+        """
+
+    def add_exporter(self, exporter):
+        """
+        Add an exporter to the list of exporters.
+        """
+        self._exporters.append(exporter)
+
+    @abstractmethod
+    def create_counter(self, name: str, description: str, unit: str,
+                       label_names: Optional[Sequence[str]] = None) -> "Counter":
+        """
+        Create a counter.
+
+        Args:
+            name: The name of the instrument to be created
+            description: A description for this instrument and what it measures.
+            unit: The unit for observations this instrument reports. For
+                example, ``By`` for bytes. UCUM units are recommended.
+        """
+
+    @abstractmethod
+    def create_un_down_counter(self, name: str, description: str, unit: str,
+                               label_names: Optional[Sequence[str]] = None) -> "UnDownCounter":
+        """
+        Create a un-down counter.
+        Args:
+            name: The name of the instrument to be created
+            description: A description for this instrument and what it measures.
+            unit: The unit for observations this instrument reports. For
+                example, ``By`` for bytes. UCUM units are recommended.
+        """
+
+    @abstractmethod
+    def create_gauge(self, name: str, description: str, unit: str,
+                     label_names: Optional[Sequence[str]] = None) -> "Gauge":
+        """
+        Create a gauge.
+        Args:
+            name: The name of the instrument to be created
+            description: A description for this instrument and what it measures.
+            unit: The unit for observations this instrument reports. For
+                example, ``By`` for bytes. UCUM units are recommended.
+        """
+
+    @abstractmethod
+    def create_histogram(self,
+                         name: str,
+                         description: str,
+                         unit: str,
+                         buckets: Optional[Sequence[float]] = None,
+                         label_names: Optional[Sequence[str]] = None) -> "Histogram":
+        """
+        Create a histogram.
+        Args:
+            name: The name of the instrument to be created
+            description: A description for this instrument and what it measures.
+            unit: The unit for observations this instrument reports. For
+                example, ``By`` for bytes. UCUM units are recommended.
+        """
+
+
+class BaseMetric(ABC):
+    """
+    Metric is the base class for all metrics.
+    Args:
+        name: The name of the metric.
+        description: The description of the metric.
+        unit: The unit of the metric.
+        provider: The provider of the metric.
+    """
+
+    def __init__(self,
+                 name: str,
+                 description: str,
+                 unit: str,
+                 provider: MetricProvider,
+                 label_names: Optional[Sequence[str]] = None):
+        self._name = name
+        self._description = description
+        self._unit = unit
+        self._provider = provider
+        self._label_names = label_names
+        self._type = None
+
+
+class Counter(BaseMetric):
+    """
+    Counter is a subclass of BaseMetric, representing a counter metric.
+    A counter is a cumulative metric that represents a single numerical value that only ever goes up.
+    """
+
+    def __init__(self,
+                 name: str,
+                 description: str,
+                 unit: str,
+                 provider: MetricProvider,
+                 label_names: Optional[Sequence[str]] = None):
+        """
+        Initialize the Counter.
+        Args:
+            name: The name of the metric.
+            description: The description of the metric.
+            unit: The unit of the metric.
+            provider: The provider of the metric.
+        """
+        super().__init__(name, description, unit, provider, label_names)
+        self._type = MetricType.COUNTER
+
+    @abstractmethod
+    def add(self, value: int, labels: dict = None) -> None:
+        """
+        Add a value to the counter.
+        Args:
+            value: The value to add to the counter.
+            labels: The labels to associate with the value.
+        """
+
+
+class UpDownCounter(BaseMetric):
+    """
+    UpDownCounter is a subclass of BaseMetric, representing an un-down counter metric.
+    An un-down counter is a cumulative metric that represents a single numerical value that only ever goes up.
+    """
+
+    def __init__(self,
+                 name: str,
+                 description: str,
+                 unit: str,
+                 provider: MetricProvider,
+                 label_names: Optional[Sequence[str]] = None):
+        """
+        Initialize the UnDownCounter.
+        Args:
+            name: The name of the metric.
+            description: The description of the metric.
+            unit: The unit of the metric.
+            provider: The provider of the metric.
+        """
+        super().__init__(name, description, unit, provider, label_names)
+        self._type = MetricType.UPDOWNCOUNTER
+
+    @abstractmethod
+    def inc(self, value: int, labels: dict = None) -> None:
+        """
+        Add a value to the gauge.
+        Args:
+            value: The value to add to the gauge.
+            labels: The labels to associate with the value.
+        """
+
+    @abstractmethod
+    def dec(self, value: int, labels: dict = None) -> None:
+        """
+        Subtract a value from the gauge.
+        Args:
+            value: The value to subtract from the gauge.
+            labels: The labels to associate with the value.
+        """
+
+
+class Gauge(BaseMetric):
+    """
+    Gauge is a subclass of BaseMetric, representing a gauge metric.
+    A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
+    """
+
+    def __init__(self,
+                 name: str,
+                 description: str,
+                 unit: str,
+                 provider: MetricProvider,
+                 label_names: Optional[Sequence[str]] = None):
+        """
+        Initialize the Gauge.
+        Args:
+            name: The name of the metric.
+            description: The description of the metric.
+            unit: The unit of the metric.
+            provider: The provider of the metric.
+        """
+        super().__init__(name, description, unit, provider, label_names)
+        self._type = MetricType.GAUGE
+
+    @abstractmethod
+    def set(self, value: int, labels: dict = None) -> None:
+        """
+        Set the value of the gauge.
+        Args:
+            value: The value to set the gauge to.
+            labels: The labels to associate with the value.
+        """
+
+
+class Histogram(BaseMetric):
+    """
+    Histogram is a subclass of BaseMetric, representing a histogram metric.
+    A histogram is a metric that represents the distribution of a set of values.
+    """
+
+    def __init__(self,
+                 name: str,
+                 description: str,
+                 unit: str,
+                 provider: MetricProvider,
+                 buckets: Sequence[float] = None,
+                 label_names: Optional[Sequence[str]] = None):
+        """
+        Initialize the Histogram.
+        Args:
+            name: The name of the metric.
+            description: The description of the metric.
+            unit: The unit of the metric.
+            provider: The provider of the metric.
+            buckets: The buckets of the histogram.
+        """
+        super().__init__(name, description, unit, provider, label_names)
+        self._type = MetricType.HISTOGRAM
+        self._buckets = buckets
+
+    @abstractmethod
+    def record(self, value: int, labels: dict = None) -> None:
+        """
+        Record a value in the histogram.
+        Args:
+            value: The value to record in the histogram.
+            labels: The labels to associate with the value.
+        """
+
+
+class MetricExporter(ABC):
+    """
+    MetricExporter is the base class for all metric exporters.
+    """
+    @abstractmethod
+    def shutdown(self):
+        """
+        Export the metrics.
+        """
+
+
+_GLOBAL_METRIC_PROVIDER: Optional[MetricProvider] = None
+
+
+def set_metric_provider(provider):
+    """
+    Set the global metric provider.
+    """
+    global _GLOBAL_METRIC_PROVIDER
+    _GLOBAL_METRIC_PROVIDER = provider
+
+
+def get_metric_provider():
+    """
+    Get the global metric provider.
+    """
+    global _GLOBAL_METRIC_PROVIDER
+    if _GLOBAL_METRIC_PROVIDER is None:
+        raise ValueError("No metric provider has been set.")
+    return _GLOBAL_METRIC_PROVIDER

aworld/metrics/template.py

@@ -0,0 +1,43 @@
+from typing import Sequence
+from pydantic import BaseModel, Field, root_validator
+from typing import Optional
+
+
+class MetricTemplate(BaseModel):
+    """
+    MetricTemplate is a class for defining a metric template.
+    """
+    type: str
+    name: str
+    description: Optional[str] = None
+    unit: Optional[str] = Field(default="1")
+    labels: Optional[list[str]] = None
+    buckets: Optional[Sequence[float]] = None
+
+    @root_validator(pre=True)
+    def set_default_description(cls, values):
+        """
+        Set the default description if it is not set.
+        """
+        if 'description' not in values or values['description'] is None:
+            values['description'] = values['name']
+        return values
+
+
+class MetricTemplates:
+    REQUEST_COUNT = MetricTemplate(**{
+        "type": "counter",
+        "name": "request_count",
+        "description": "The number of requests received",
+        "unit": "1",
+        "labels": ["method", "status"]
+    })
+
+    REQUEST_LATENCY = MetricTemplate(**{
+        "type": "histogram",
+        "name": "request_latency",
+        "description": "The latency of requests",
+        "unit": "ms",
+        "labels": ["method", "status"],
+        # "buckets": [0.01, 0.05, 0.1, 0.5, 1, 5, 10, 50, 100, 500, 1000]
+    })