Metrics

Metrics plugin for collecting and aggregating job and queue metrics.

class chancy.plugins.metrics.Metrics(*, sync_interval: int = 60, max_points_per_resolution: Dict[Literal['1min', '5min', '1hour', '1day'], int] = None, maximum_metric_age: int = 7776000, collection_interval: int = 30)

Bases: Plugin

A plugin that collects and aggregates various metrics from jobs and queues.

The plugin maintains time-series data for various metrics, with automatic aggregation and pruning to keep storage requirements low while providing useful historical data.

Metrics are synchronized across workers, so each worker has access to the full set of metrics.

Example:

from chancy import Chancy
from chancy.plugins.metrics import Metrics

async with Chancy(..., plugins=[Metrics()]) as chancy:
    ...

The metrics are stored in a compact time-series format, with data points aggregated at different resolutions (1 minute, 5 minutes, 1 hour, 1 day).

Note

While you can use this plugin to record your own arbitrary metrics, it’s not designed as a general-purpose monitoring solution. For more advanced monitoring and visualization, consider using a dedicated monitoring tool like Prometheus or Grafana.

api_plugin() → str | None

If this plugin has an associated API component, returns the import string for the plugin.

async cleanup(chancy: Chancy) → int | None

Clean up old metrics data.

Called automatically by the Pruner plugin, or may be manually invoked.

static get_identifier() → str

Returns a unique identifier for this plugin.

This identifier should be unique across all active plugins. If a custom plugin provides compatible functionality to a built-in plugin, it may use the same identifier as the built-in plugin.

async get_metrics(chancy: Chancy, metric_prefix: str | None = None, worker_id: str | None = None) → Dict[str, Metric]

Get metrics matching the given prefix.

If a worker_id is provided, only metrics for that worker are returned and are queried directly from the database. Otherwise, aggregated metrics are returned from the metrics cache.

Parameters:

• chancy – The Chancy application instance

• metric_prefix – Optional prefix to filter metrics by

• worker_id – Optional worker_id to filter metrics by

get_tables() → list[str]

Get the names of all tables this plugin is responsible for.

async increment_counter(metric_key: str, value: int | float) → None

Increment a counter metric.

Counter metrics accumulate values over time periods.

Parameters:

• metric_key – The unique key for the metric

• value – The value to increment the counter by

static matches_prefix(prefix: str, key: str) → bool

Check if the given key matches the given complete prefix.

Parameters:

• prefix – The prefix to match

• key – The key to check

migrate_key() → str

Get the unique identifier for this plugin’s migrations.

migrate_package() → str

Get the package that contains the migrations for the metrics plugin.

async on_job_updated(*, worker: Worker, job: QueuedJob)

Called after a job has been run and saved.

Unlike on_job_completed, this method cannot modify the job, but the job is guaranteed to have been updated in the database by the time it is called.

Parameters:

• worker – The worker that is running the job.

• job – The job that was completed.

async record_gauge(metric_key: str, value: int | float) → None

Record a gauge metric which represents a point-in-time value.

Gauge metrics record the most recent value in each time bucket.

Parameters:

• metric_key – The unique key for the metric

• value – The value to record

async record_histogram_value(metric_key: str, value: int | float) → None

Record a value to a histogram metric.

Histogram metrics track statistics (min, max, avg, count) for values over time periods.

Parameters:

• metric_key – The unique key for the metric

• value – The value to record

async run(worker: Worker, chancy: Chancy)

Run the metrics plugin.

This continuously synchronizes metrics with the database and other workers.