grass-metrics

Unified metrics library for Grass projects. Supports DataDog (DogStatsD/UDP) and OpenTelemetry/OpenObserve (OTLP gRPC/HTTP) with automatic backend selection and dual-write mode.

Installation

# Core (no backend dependencies -- bring your own)
pip install grass-metrics

# With DataDog support
pip install "grass-metrics[datadog]"

# With OpenTelemetry support
pip install "grass-metrics[otel]"

# Both backends
pip install "grass-metrics[all]"

Quick Start

from grass_metrics import create_metrics_manager

metrics = create_metrics_manager()

metrics.increment("wl.my_service.items.processed")
metrics.gauge("wl.my_service.queue.size", 42)
metrics.histogram("wl.my_service.latency_seconds", 1.23)

# With extra tags
metrics.increment("wl.my_service.uploads.success", extra_tags=["provider:s3"])

# Shutdown (flushes OTel buffers)
metrics.shutdown()

Backend Selection

The factory picks the backend in this priority order:

Supported values: datadog, otel, dual

• datadog -- Sends metrics via DogStatsD UDP to the DataDog Agent
• otel -- Sends metrics via OTLP (gRPC or HTTP) to an OpenTelemetry Collector / OpenObserve
• dual -- Sends to both simultaneously (DataDog primary, OTel secondary). Useful during migration.

Environment Variables

Common

DataDog

OpenTelemetry / OpenObserve

OTel endpoint resolution: explicit > OTEL_EXPORTER_ENDPOINT > http://{NODE_IP}:4317 > gateway fallback.

Kubernetes Pod Spec

env:
  - name: METRICS_BACKEND
    valueFrom:
      configMapKeyRef:
        name: scraper-config
        key: metrics_backend
  # DataDog
  - name: DD_AGENT_HOST
    valueFrom:
      fieldRef:
        fieldPath: status.hostIP
  # OTel
  - name: NODE_IP
    valueFrom:
      fieldRef:
        fieldPath: status.hostIP

Docker Compose

environment:
  METRICS_BACKEND: "otel"
  DD_AGENT_HOST: "datadog"          # service name
  OTEL_EXPORTER_ENDPOINT: "http://otel-collector:4317"

Domain-Specific Metrics (Consumer Pattern)

For projects with many metrics, wrap MetricsManager in a thin domain class:

from grass_metrics import create_metrics_manager

class YtdMetrics:
    DOWNLOADS_SUCCESS = "wl.ytd.downloads.healthy_count"
    DOWNLOADS_FAILED  = "wl.ytd.downloads.failed_count"
    UPLOAD_DURATION   = "wl.ytd.upload.duration_seconds"

    def __init__(self):
        self._m = create_metrics_manager()

    def increment_downloaded_videos_count(self):
        self._m.increment(self.DOWNLOADS_SUCCESS)

    def increment_failed_downloads_count(self):
        self._m.increment(self.DOWNLOADS_FAILED)

    def send_upload_duration(self, seconds: float):
        self._m.histogram(self.UPLOAD_DURATION, seconds)

    def shutdown(self):
        self._m.shutdown()

Direct Publisher Access

For advanced use cases, publishers can be used directly:

from grass_metrics import DatadogPublisher, OtelPublisher

dd = DatadogPublisher(statsd_host="172.17.0.1", statsd_port=8125)
dd.increment_count("my.counter", 1, ["env:prod"])

otel = OtelPublisher(service_name="my-svc", use_grpc=True)
otel.increment_count("my.counter", 1, ["env:prod"])
otel.shutdown()

Architecture

┌──────────────────────────────────────────────────┐
│                Consumer Project                   │
│  (e.g. YtdMetrics with domain-specific methods)  │
└──────────────────────┬───────────────────────────┘
                       │
         create_metrics_manager(backend=...)
                       │
                ┌──────▼──────┐
                │   Factory    │  resolves backend from
                │  factory.py  │  env / Redis / default
                └──────┬──────┘
                       │
          ┌────────────┼────────────┐
          │            │            │
    ┌─────▼─────┐ ┌───▼────┐ ┌────▼─────┐
    │ MetricsMgr│ │MetrMgr │ │ DualMgr  │
    │ + DD Pub  │ │+ OTel  │ │ DD + OTel│
    └───────────┘ └────────┘ └──────────┘