dj-queue 0.9.0__tar.gz → 0.9.1__tar.gz

{dj_queue-0.9.0 → dj_queue-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dj-queue
-Version: 0.9.0
+Version: 0.9.1
 Summary: Database-backed task queue backend for Django’s Tasks framework.
 License-Expression: MIT
 License-File: LICENSE

{dj_queue-0.9.0 → dj_queue-0.9.1}/dj_queue/admin.py

@@ -35,6 +35,7 @@ from dj_queue.operations.jobs import (
   retry_failed_job,
   retry_failed_jobs,
 )
+from dj_queue.queue_state import status_rank_expression
 
 
 class DjQueueFirstAdminSite(admin.AdminSite):
@@ -503,18 +504,7 @@ class JobAdmin(HiddenSidebarAdminMixin, admin.ModelAdmin):
 
   def get_queryset(self, request):
     queryset = super().get_queryset(request)
-    return queryset.annotate(
-      status_rank=Case(
-        When(ready_execution__isnull=False, then=Value(0)),
-        When(scheduled_execution__isnull=False, then=Value(1)),
-        When(claimed_execution__isnull=False, then=Value(2)),
-        When(blocked_execution__isnull=False, then=Value(3)),
-        When(failed_execution__isnull=False, then=Value(4)),
-        When(finished_at__isnull=False, then=Value(5)),
-        default=Value(99),
-        output_field=IntegerField(),
-      )
-    )
+    return queryset.annotate(status_rank=status_rank_expression())
 
   @admin.display(description="status", ordering="status_rank")
   def display_status(self, obj):

dj_queue-0.9.1/dj_queue/contrib/prometheus.py

@@ -0,0 +1,26 @@
+try:
+  from prometheus_client import CollectorRegistry, generate_latest
+  from prometheus_client.core import GaugeMetricFamily
+except ImportError:
+  DjQueueCollector = None
+  registry = None
+  generate_latest = None
+else:
+  from dj_queue.metrics import metric_families
+
+  class DjQueueCollector:
+    """Prometheus collector that exposes dj_queue metrics from the shared observability snapshot."""
+
+    def collect(self):
+      for family in metric_families():
+        gauge = GaugeMetricFamily(
+          family.name,
+          family.help_text,
+          labels=list(family.labels),
+        )
+        for sample in family.samples:
+          gauge.add_metric(list(sample.labels), sample.value)
+        yield gauge
+
+  registry = CollectorRegistry(auto_describe=False)
+  registry.register(DjQueueCollector())

{dj_queue-0.9.0 → dj_queue-0.9.1}/dj_queue/dashboard.py

@@ -22,51 +22,20 @@ from dj_queue.operations.jobs import (
   enqueue_job_again,
   retry_failed_jobs,
 )
-
-QUEUE_STATE_CONFIG = {
-  "ready": {
-    "label": "ready",
-    "job_actions": ({"name": "discard", "label": "discard selected"},),
-    "query_filter": {"ready_execution__isnull": False},
-    "query_order": ("-priority", "ready_execution__id"),
-  },
-  "claimed": {
-    "label": "claimed",
-    "job_actions": (),
-    "query_filter": {"claimed_execution__isnull": False},
-    "query_order": ("claimed_execution__created_at", "id"),
-  },
-  "scheduled": {
-    "label": "scheduled",
-    "job_actions": ({"name": "discard", "label": "discard selected"},),
-    "query_filter": {"scheduled_execution__isnull": False},
-    "query_order": ("scheduled_execution__scheduled_at", "-priority", "scheduled_execution__id"),
-  },
-  "blocked": {
-    "label": "blocked",
-    "job_actions": ({"name": "discard", "label": "discard selected"},),
-    "query_filter": {"blocked_execution__isnull": False},
-    "query_order": ("blocked_execution__expires_at", "-priority", "blocked_execution__id"),
-  },
-  "failed": {
-    "label": "failed",
-    "job_actions": (
-      {"name": "retry", "label": "retry selected"},
-      {"name": "discard", "label": "discard selected"},
-    ),
-    "query_filter": {"failed_execution__isnull": False},
-    "query_order": ("-failed_execution__created_at", "id"),
-  },
-  "finished": {
-    "label": "finished",
-    "job_actions": ({"name": "enqueue", "label": "enqueue selected again"},),
-    "query_filter": {"finished_at__isnull": False},
-    "query_order": ("-finished_at", "id"),
-  },
+from dj_queue.queue_state import QUEUE_STATE_LABELS, QUEUE_STATES, queue_state_queryset
+
+
+QUEUE_JOB_ACTIONS = {
+  "ready": ({"name": "discard", "label": "discard selected"},),
+  "claimed": (),
+  "scheduled": ({"name": "discard", "label": "discard selected"},),
+  "blocked": ({"name": "discard", "label": "discard selected"},),
+  "failed": (
+    {"name": "retry", "label": "retry selected"},
+    {"name": "discard", "label": "discard selected"},
+  ),
+  "finished": ({"name": "enqueue", "label": "enqueue selected again"},),
 }
-
-QUEUE_STATES = tuple((state, config["label"]) for state, config in QUEUE_STATE_CONFIG.items())
-QUEUE_STATE_LABELS = {state: config["label"] for state, config in QUEUE_STATE_CONFIG.items()}
 PAGE_SIZE = 100
 OVERVIEW_PAGE_SIZES = {
   "queues": 18,
@@ -555,7 +524,7 @@ def apply_job_action(*, backend_alias, queue_name, state, action, job_ids):
 
 
 def job_actions_for_state(state):
-  return QUEUE_STATE_CONFIG[state]["job_actions"]
+  return QUEUE_JOB_ACTIONS[state]
 
 
 def _summary_cards(*, backend_alias, queue_rows, process_rows, recurring_rows, semaphore_rows):
@@ -1181,20 +1150,7 @@ def _failed_execution_changelist_url(backend_alias, **filters):
 
 
 def _jobs_for_queue_state(*, backend_alias, queue_name, state):
-  alias = get_database_alias(backend_alias)
-  queryset = (
-    Job.objects.using(alias)
-    .filter(backend_alias=backend_alias, queue_name=queue_name)
-    .select_related(
-      "ready_execution",
-      "scheduled_execution",
-      "claimed_execution__process",
-      "blocked_execution",
-      "failed_execution",
-    )
-  )
-  state_config = QUEUE_STATE_CONFIG[state]
-  return queryset.filter(**state_config["query_filter"]).order_by(*state_config["query_order"])
+  return queue_state_queryset(backend_alias=backend_alias, queue_name=queue_name, state=state)
 
 
 def _next_run_at(schedule, now):

dj_queue-0.9.1/dj_queue/metrics.py

@@ -0,0 +1,162 @@
+from dataclasses import dataclass
+
+from dj_queue import observability
+
+
+@dataclass(frozen=True, slots=True)
+class MetricSample:
+  labels: tuple[str, ...]
+  value: float
+
+
+@dataclass(frozen=True, slots=True)
+class MetricFamily:
+  name: str
+  help_text: str
+  labels: tuple[str, ...]
+  samples: tuple[MetricSample, ...]
+
+
+def metric_families(*, snapshots=None):
+  if snapshots is None:
+    snapshots = observability.all_backend_snapshots()
+
+  queue_jobs = []
+  queue_paused = []
+  queue_latency = []
+  queue_workers = []
+  runner_processes = []
+  runner_processes_by_kind = []
+  recurring_tasks = []
+  semaphores = []
+  process_rows = []
+  seen_queue_databases = set()
+
+  for snapshot in snapshots:
+    backend_alias = snapshot["backend_alias"]
+    queue_database_alias = snapshot["queue_database_alias"]
+    runner_metrics = snapshot["runner_metrics"]
+
+    for queue in snapshot["queue_rows"]:
+      for state in ("ready", "claimed", "scheduled", "blocked", "failed", "finished"):
+        queue_jobs.append(
+          MetricSample(
+            labels=(backend_alias, queue["name"], state),
+            value=queue[f"{state}_count"],
+          )
+        )
+      queue_paused.append(
+        MetricSample(
+          labels=(backend_alias, queue["name"]),
+          value=1 if queue["paused"] else 0,
+        )
+      )
+      if queue["latency_seconds"] is not None:
+        queue_latency.append(
+          MetricSample(
+            labels=(backend_alias, queue["name"]),
+            value=queue["latency_seconds"],
+          )
+        )
+      queue_workers.append(
+        MetricSample(
+          labels=(backend_alias, queue["name"]),
+          value=queue["live_worker_count"],
+        )
+      )
+
+    for status in ("live", "stale"):
+      runner_processes.append(
+        MetricSample(
+          labels=(backend_alias, status),
+          value=runner_metrics[status],
+        )
+      )
+    for kind, counts in sorted(runner_metrics["by_kind"].items()):
+      for status in ("live", "stale"):
+        runner_processes_by_kind.append(
+          MetricSample(
+            labels=(backend_alias, kind, status),
+            value=counts.get(status, 0),
+          )
+        )
+
+    recurring_tasks.append(
+      MetricSample(
+        labels=(backend_alias,),
+        value=len(snapshot["recurring_rows"]),
+      )
+    )
+    process_rows.append(
+      MetricSample(
+        labels=(backend_alias,),
+        value=len(snapshot["process_rows"]),
+      )
+    )
+
+    if queue_database_alias in seen_queue_databases:
+      continue
+    seen_queue_databases.add(queue_database_alias)
+    semaphores.append(
+      MetricSample(
+        labels=(queue_database_alias,),
+        value=len(snapshot["semaphore_rows"]),
+      )
+    )
+
+  return (
+    MetricFamily(
+      name="dj_queue_queue_jobs",
+      help_text="Current job count by backend, queue, and state",
+      labels=("backend", "queue", "state"),
+      samples=tuple(queue_jobs),
+    ),
+    MetricFamily(
+      name="dj_queue_queue_paused",
+      help_text="Whether a queue is paused for a backend",
+      labels=("backend", "queue"),
+      samples=tuple(queue_paused),
+    ),
+    MetricFamily(
+      name="dj_queue_queue_latency_seconds",
+      help_text="Latency of the oldest ready job in a backend queue",
+      labels=("backend", "queue"),
+      samples=tuple(queue_latency),
+    ),
+    MetricFamily(
+      name="dj_queue_queue_live_workers",
+      help_text="Live workers that can service a backend queue",
+      labels=("backend", "queue"),
+      samples=tuple(queue_workers),
+    ),
+    MetricFamily(
+      name="dj_queue_runner_processes",
+      help_text="Current runner process count by backend and liveness",
+      labels=("backend", "status"),
+      samples=tuple(runner_processes),
+    ),
+    MetricFamily(
+      name="dj_queue_runner_processes_by_kind",
+      help_text="Current runner process count by backend, kind, and liveness",
+      labels=("backend", "kind", "status"),
+      samples=tuple(runner_processes_by_kind),
+    ),
+    MetricFamily(
+      name="dj_queue_recurring_tasks",
+      help_text="Current recurring task count by backend",
+      labels=("backend",),
+      samples=tuple(recurring_tasks),
+    ),
+    MetricFamily(
+      name="dj_queue_semaphores",
+      help_text="Current semaphore count by queue database",
+      labels=("queue_database",),
+      samples=tuple(semaphores),
+    ),
+    MetricFamily(
+      name="dj_queue_process_rows",
+      help_text="Current process row count by backend",
+      labels=("backend",),
+      samples=tuple(process_rows),
+    ),
+  )

{dj_queue-0.9.0 → dj_queue-0.9.1}/dj_queue/observability.py

@@ -25,6 +25,7 @@ from dj_queue.models import (
   ScheduledExecution,
   Semaphore,
 )
+from dj_queue.queue_state import queue_state_counts
 
 
 @dataclass(frozen=True, slots=True)
@@ -414,22 +415,6 @@ def semaphore_rows_for_backend(*, backend_alias):
   ]
 
 
-def queue_state_counts(*, backend_alias, queue_name):
-  alias = get_database_alias(backend_alias)
-  base_queryset = Job.objects.using(alias).filter(
-    backend_alias=backend_alias,
-    queue_name=queue_name,
-  )
-  return {
-    "ready": base_queryset.filter(ready_execution__isnull=False).count(),
-    "claimed": base_queryset.filter(claimed_execution__isnull=False).count(),
-    "scheduled": base_queryset.filter(scheduled_execution__isnull=False).count(),
-    "blocked": base_queryset.filter(blocked_execution__isnull=False).count(),
-    "failed": base_queryset.filter(failed_execution__isnull=False).count(),
-    "finished": base_queryset.filter(finished_at__isnull=False).count(),
-  }
-
-
 def next_run_at(schedule, now):
   return next_cron_run(schedule, now)
 

dj_queue-0.9.1/dj_queue/operations/_helpers.py

@@ -0,0 +1,190 @@
+import json
+
+from dj_queue.db import database_capabilities
+from dj_queue.exceptions import EnqueueError
+from dj_queue.models import BlockedExecution, Pause, ReadyExecution, ScheduledExecution
+
+
+def _normalize_payload(args, kwargs):
+  try:
+    return json.loads(json.dumps({"args": list(args), "kwargs": dict(kwargs)}))
+  except (TypeError, ValueError) as exc:
+    raise EnqueueError("payload must be JSON round-trippable") from exc
+
+
+def _task_option(task, name, default=None):
+  if hasattr(task, name):
+    return getattr(task, name)
+  return getattr(task.func, name, default)
+
+
+def _lock_active_pauses(alias, backend_alias, queue_names=None):
+  queryset = Pause.objects.using(alias).select_for_update().filter(backend_alias=backend_alias)
+  if queue_names is not None:
+    active_queue_names = tuple(queue_name for queue_name in queue_names if queue_name)
+    if not active_queue_names:
+      return set()
+    queryset = queryset.filter(queue_name__in=active_queue_names)
+  return set(queryset.values_list("queue_name", flat=True))
+
+
+def _ready_execution_row(
+  job,
+  *,
+  backend_alias,
+  queue_name=None,
+  priority=None,
+  ready_at=None,
+  created_at=None,
+):
+  return ReadyExecution(
+    **_ready_execution_fields(
+      job,
+      backend_alias=backend_alias,
+      queue_name=queue_name,
+      priority=priority,
+      ready_at=ready_at,
+      created_at=created_at,
+    )
+  )
+
+
+def _create_ready_execution(
+  alias,
+  job,
+  *,
+  backend_alias,
+  queue_name=None,
+  priority=None,
+  ready_at=None,
+  created_at=None,
+):
+  queue_name = _execution_queue_name(job, queue_name)
+  _lock_active_pauses(alias, backend_alias, {queue_name})
+  return ReadyExecution.objects.using(alias).create(
+    **_ready_execution_fields(
+      job,
+      backend_alias=backend_alias,
+      queue_name=queue_name,
+      priority=priority,
+      ready_at=ready_at,
+      created_at=created_at,
+    )
+  )
+
+
+def _scheduled_execution_row(job, *, backend_alias, scheduled_at=None, created_at=None):
+  return ScheduledExecution(
+    **_scheduled_execution_fields(
+      job,
+      backend_alias=backend_alias,
+      scheduled_at=scheduled_at,
+      created_at=created_at,
+    )
+  )
+
+
+def _create_scheduled_execution(alias, job, *, backend_alias, scheduled_at=None):
+  return ScheduledExecution.objects.using(alias).create(
+    **_scheduled_execution_fields(
+      job,
+      backend_alias=backend_alias,
+      scheduled_at=scheduled_at,
+    )
+  )
+
+
+def _create_blocked_execution(
+  alias,
+  job,
+  *,
+  backend_alias,
+  concurrency_key=None,
+  expires_at,
+  queue_name=None,
+  priority=None,
+):
+  return BlockedExecution.objects.using(alias).create(
+    **_blocked_execution_fields(
+      job,
+      backend_alias=backend_alias,
+      concurrency_key=concurrency_key,
+      expires_at=expires_at,
+      queue_name=queue_name,
+      priority=priority,
+    )
+  )
+
+
+def _ready_execution_fields(
+  job,
+  *,
+  backend_alias,
+  queue_name=None,
+  priority=None,
+  ready_at=None,
+  created_at=None,
+):
+  fields = {
+    "job": job,
+    "backend_alias": backend_alias,
+    "queue_name": _execution_queue_name(job, queue_name),
+    "priority": _execution_priority(job, priority),
+    "latency_started_at": ready_at,
+  }
+  if created_at is not None:
+    fields["created_at"] = created_at
+  return fields
+
+
+def _scheduled_execution_fields(job, *, backend_alias, scheduled_at=None, created_at=None):
+  fields = {
+    "job": job,
+    "backend_alias": backend_alias,
+    "queue_name": job.queue_name,
+    "priority": job.priority,
+    "scheduled_at": scheduled_at if scheduled_at is not None else job.scheduled_at,
+  }
+  if created_at is not None:
+    fields["created_at"] = created_at
+  return fields
+
+
+def _blocked_execution_fields(
+  job,
+  *,
+  backend_alias,
+  concurrency_key=None,
+  expires_at,
+  queue_name=None,
+  priority=None,
+):
+  return {
+    "job": job,
+    "backend_alias": backend_alias,
+    "queue_name": _execution_queue_name(job, queue_name),
+    "priority": _execution_priority(job, priority),
+    "concurrency_key": concurrency_key if concurrency_key is not None else job.concurrency_key,
+    "expires_at": expires_at,
+  }
+
+
+def _execution_queue_name(job, queue_name):
+  return job.queue_name if queue_name is None else queue_name
+
+
+def _execution_priority(job, priority):
+  return job.priority if priority is None else priority
+
+
+def _consume_selected_rows(alias, model, rows):
+  if not database_capabilities(alias).uses_serialized_writes:
+    model.objects.using(alias).filter(pk__in=[row.pk for row in rows]).delete()
+    return rows
+
+  consumed_rows = []
+  for row in rows:
+    deleted, _ = model.objects.using(alias).filter(pk=row.pk).delete()
+    if deleted:
+      consumed_rows.append(row)
+  return consumed_rows

{dj_queue-0.9.0 → dj_queue-0.9.1}/dj_queue/operations/concurrency.py

@@ -12,7 +12,8 @@ from dj_queue.log import log_event
 from dj_queue.models import BlockedExecution, ClaimedExecution, ReadyExecution, Semaphore
 from dj_queue.operations._helpers import (
   _consume_selected_rows,
-  _lock_active_pauses,
+  _create_blocked_execution,
+  _create_ready_execution,
   _task_option,
 )
 from dj_queue.operations._insert import create_ignore_conflicts
@@ -170,13 +171,13 @@ def unblock_next_blocked_job(
     queue_name = blocked.queue_name
     priority = blocked.priority
     blocked.delete(using=alias)
-    _lock_active_pauses(alias, backend_alias, {queue_name})
-    ReadyExecution.objects.using(alias).create(
+    _create_ready_execution(
+      alias,
       job=job,
       backend_alias=backend_alias,
       queue_name=queue_name,
       priority=priority,
-      latency_started_at=now,
+      ready_at=now,
     )
 
   log_event(
@@ -258,20 +259,21 @@ def promote_expired_blocked_jobs(*, batch_size=500, backend_alias="default", use
         priority = blocked.priority
         if not uses_serialized_writes:
           blocked.delete(using=alias)
-        _lock_active_pauses(alias, backend_alias, {queue_name})
-        ReadyExecution.objects.using(alias).create(
+        _create_ready_execution(
+          alias,
           job=job,
           backend_alias=backend_alias,
           queue_name=queue_name,
           priority=priority,
-          latency_started_at=now,
+          ready_at=now,
         )
         promoted_jobs.append(job)
       else:
         expires_at = now + timedelta(seconds=duration_seconds)
         if uses_serialized_writes:
-          BlockedExecution.objects.using(alias).create(
-            job=job,
+          _create_blocked_execution(
+            alias,
+            job,
             backend_alias=backend_alias,
             queue_name=blocked.queue_name,
             priority=blocked.priority,