conductor-python 1.3.11__tar.gz → 1.4.0__tar.gz

{conductor_python-1.3.11 → conductor_python-1.4.0}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: conductor-python
-Version: 1.3.11
+Version: 1.4.0
 Summary: Python SDK for working with https://github.com/conductor-oss/conductor
 License: Apache-2.0
 Author: Orkes
 Author-email: developers@orkes.io
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -27,10 +26,11 @@ Requires-Dist: h2 (>=4.1.0)
 Requires-Dist: httpx[http2] (>=0.26.0)
 Requires-Dist: prometheus-client (>=0.13.1)
 Requires-Dist: python-dateutil (>=2.8.2,<3.0.0)
-Requires-Dist: requests (>=2.31.0)
+Requires-Dist: requests (>=2.33.0)
 Requires-Dist: shortuuid (>=1.0.11)
 Requires-Dist: six (>=1.10)
 Requires-Dist: typing-extensions (>=4.2.0)
+Requires-Dist: urllib3 (>=2.6.3)
 Description-Content-Type: text/markdown
 
 # Python SDK for Conductor
@@ -141,7 +141,7 @@ Create a `quickstart.py` with the following:
 ```python
 from conductor.client.automator.task_handler import TaskHandler
 from conductor.client.configuration.configuration import Configuration
-from conductor.client.orkes_clients import OrkesClients  # works with OSS Conductor and Orkes Conductor
+from conductor.client.orkes_clients import ConductorClients  # OrkesClients is an alias for the same class
 from conductor.client.workflow.conductor_workflow import ConductorWorkflow
 from conductor.client.worker.worker_task import worker_task
 
@@ -156,7 +156,7 @@ def main():
     # Configure the SDK (reads CONDUCTOR_SERVER_URL / CONDUCTOR_AUTH_* from env).
     config = Configuration()
 
-    clients = OrkesClients(configuration=config)
+    clients = ConductorClients(configuration=config)
     executor = clients.get_workflow_executor()
 
     # Build a workflow with the >> operator.
@@ -188,6 +188,8 @@ Run it:
 python quickstart.py
 ```
 
+> **About `OrkesClients`:** This is the standard client factory for Conductor. The `Orkes` prefix reflects the implementing organization — it works identically with self-hosted OSS Conductor. No Orkes account or paid service is required.
+
 > ### Using Orkes Conductor / Remote Server?
 > Export your authentication credentials as well:
 >
@@ -355,7 +357,7 @@ with TaskHandler(configuration=config, metrics_settings=metrics, scan_for_annota
 curl http://localhost:8000/metrics
 ```
 
-See [examples/metrics_example.py](examples/metrics_example.py) and [METRICS.md](METRICS.md) for details on all tracked metrics.
+Legacy metrics are emitted by default. Set `WORKER_CANONICAL_METRICS=true` before starting workers to use the canonical metric catalog. See [examples/metrics_example.py](examples/metrics_example.py) and [METRICS.md](METRICS.md) for the full legacy and canonical reference.
 
 ### Managing Workflow Executions
 
@@ -364,10 +366,10 @@ Full lifecycle control — start, execute, pause, resume, terminate, retry, rest
 ```python
 from conductor.client.configuration.configuration import Configuration
 from conductor.client.http.models import StartWorkflowRequest, RerunWorkflowRequest, TaskResult
-from conductor.client.orkes_clients import OrkesClients
+from conductor.client.orkes_clients import ConductorClients
 
 config = Configuration()
-clients = OrkesClients(configuration=config)
+clients = ConductorClients(configuration=config)
 workflow_client = clients.get_workflow_client()
 task_client = clients.get_task_client()
 executor = clients.get_workflow_executor()
@@ -525,6 +527,37 @@ Yes. Conductor ensures workflows complete reliably even in the face of infrastru
 
 No. While Conductor excels at asynchronous orchestration, it also supports synchronous workflow execution when immediate results are required.
 
+**Why did `execute()` return `status: RUNNING` with no output?**
+
+`execute()` blocks until the workflow finishes **or** `wait_for_seconds` elapses (default: 10 s),
+whichever comes first. If it times out, you get `status='RUNNING'` — that is correct behavior,
+not a bug.
+
+The most common cause: your worker raised an exception. Conductor marks the task FAILED and
+schedules a retry after `retryDelaySeconds` (default: **60 s**). The default 10 s wait expires
+while the retry is pending, so `execute()` returns before the workflow completes.
+
+**To fix**: increase `wait_for_seconds` to outlast the retry cycle:
+
+```python
+# default retryDelaySeconds is 60 — wait long enough to cover one retry
+run = executor.execute(name='my_workflow', version=1, workflow_input={...}, wait_for_seconds=70)
+```
+
+**To debug** when a workflow is stuck:
+
+```python
+# Inspect task statuses and failure reasons
+wf = executor.get_workflow(run.workflow_id, include_tasks=True)
+for task in wf.tasks:
+    if task.status in ('FAILED', 'FAILED_WITH_TERMINAL_ERROR'):
+        print(task.reference_task_name, task.reason_for_incompletion)
+```
+
+You can also open the Conductor UI at `<server>/execution/<workflow_id>` — it shows each task's
+status, retry count, and the worker exception message directly. Worker tracebacks are also logged
+at ERROR level by the SDK in the `TaskHandler` process.
+
 **Do I need to use a Conductor-specific framework?**
 
 No. Conductor is language and framework agnostic. Use your preferred language and framework — the [SDKs](https://github.com/conductor-oss/conductor#conductor-sdks) provide native integration for Python, Java, JavaScript, Go, C#, and more.

{conductor_python-1.3.11 → conductor_python-1.4.0}/README.md

@@ -106,7 +106,7 @@ Create a `quickstart.py` with the following:
 ```python
 from conductor.client.automator.task_handler import TaskHandler
 from conductor.client.configuration.configuration import Configuration
-from conductor.client.orkes_clients import OrkesClients  # works with OSS Conductor and Orkes Conductor
+from conductor.client.orkes_clients import ConductorClients  # OrkesClients is an alias for the same class
 from conductor.client.workflow.conductor_workflow import ConductorWorkflow
 from conductor.client.worker.worker_task import worker_task
 
@@ -121,7 +121,7 @@ def main():
     # Configure the SDK (reads CONDUCTOR_SERVER_URL / CONDUCTOR_AUTH_* from env).
     config = Configuration()
 
-    clients = OrkesClients(configuration=config)
+    clients = ConductorClients(configuration=config)
     executor = clients.get_workflow_executor()
 
     # Build a workflow with the >> operator.
@@ -153,6 +153,8 @@ Run it:
 python quickstart.py
 ```
 
+> **About `OrkesClients`:** This is the standard client factory for Conductor. The `Orkes` prefix reflects the implementing organization — it works identically with self-hosted OSS Conductor. No Orkes account or paid service is required.
+
 > ### Using Orkes Conductor / Remote Server?
 > Export your authentication credentials as well:
 >
@@ -320,7 +322,7 @@ with TaskHandler(configuration=config, metrics_settings=metrics, scan_for_annota
 curl http://localhost:8000/metrics
 ```
 
-See [examples/metrics_example.py](examples/metrics_example.py) and [METRICS.md](METRICS.md) for details on all tracked metrics.
+Legacy metrics are emitted by default. Set `WORKER_CANONICAL_METRICS=true` before starting workers to use the canonical metric catalog. See [examples/metrics_example.py](examples/metrics_example.py) and [METRICS.md](METRICS.md) for the full legacy and canonical reference.
 
 ### Managing Workflow Executions
 
@@ -329,10 +331,10 @@ Full lifecycle control — start, execute, pause, resume, terminate, retry, rest
 ```python
 from conductor.client.configuration.configuration import Configuration
 from conductor.client.http.models import StartWorkflowRequest, RerunWorkflowRequest, TaskResult
-from conductor.client.orkes_clients import OrkesClients
+from conductor.client.orkes_clients import ConductorClients
 
 config = Configuration()
-clients = OrkesClients(configuration=config)
+clients = ConductorClients(configuration=config)
 workflow_client = clients.get_workflow_client()
 task_client = clients.get_task_client()
 executor = clients.get_workflow_executor()
@@ -490,6 +492,37 @@ Yes. Conductor ensures workflows complete reliably even in the face of infrastru
 
 No. While Conductor excels at asynchronous orchestration, it also supports synchronous workflow execution when immediate results are required.
 
+**Why did `execute()` return `status: RUNNING` with no output?**
+
+`execute()` blocks until the workflow finishes **or** `wait_for_seconds` elapses (default: 10 s),
+whichever comes first. If it times out, you get `status='RUNNING'` — that is correct behavior,
+not a bug.
+
+The most common cause: your worker raised an exception. Conductor marks the task FAILED and
+schedules a retry after `retryDelaySeconds` (default: **60 s**). The default 10 s wait expires
+while the retry is pending, so `execute()` returns before the workflow completes.
+
+**To fix**: increase `wait_for_seconds` to outlast the retry cycle:
+
+```python
+# default retryDelaySeconds is 60 — wait long enough to cover one retry
+run = executor.execute(name='my_workflow', version=1, workflow_input={...}, wait_for_seconds=70)
+```
+
+**To debug** when a workflow is stuck:
+
+```python
+# Inspect task statuses and failure reasons
+wf = executor.get_workflow(run.workflow_id, include_tasks=True)
+for task in wf.tasks:
+    if task.status in ('FAILED', 'FAILED_WITH_TERMINAL_ERROR'):
+        print(task.reference_task_name, task.reason_for_incompletion)
+```
+
+You can also open the Conductor UI at `<server>/execution/<workflow_id>` — it shows each task's
+status, retry count, and the worker exception message directly. Worker tracebacks are also logged
+at ERROR level by the SDK in the `TaskHandler` process.
+
 **Do I need to use a Conductor-specific framework?**
 
 No. Conductor is language and framework agnostic. Use your preferred language and framework — the [SDKs](https://github.com/conductor-oss/conductor#conductor-sdks) provide native integration for Python, Java, JavaScript, Go, C#, and more.

{conductor_python-1.3.11 → conductor_python-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "conductor-python"
-version = "1.3.11" # Do not change! Placeholder. Real version injected during build (edited) 
+version = "1.4.0" # Do not change! Placeholder. Real version injected during build (edited) 
 description = "Python SDK for working with https://github.com/conductor-oss/conductor"
 authors = ["Orkes <developers@orkes.io>"]
 license = "Apache-2.0"
@@ -23,11 +23,11 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.9"
+python = ">=3.10"
 certifi = ">=14.05.14"
 prometheus-client = ">=0.13.1"
 six = ">=1.10"
-requests = ">=2.31.0"
+requests = ">=2.33.0"
 typing-extensions = ">=4.2.0"
 astor = ">=0.8.1"
 shortuuid = ">=1.0.11"
@@ -36,6 +36,7 @@ deprecated = ">=1.2.14"
 python-dateutil = "^2.8.2"
 httpx = {version = ">=0.26.0", extras = ["http2"]}
 h2 = ">=4.1.0"
+urllib3 = ">=2.6.3"
 
 [tool.poetry.group.dev.dependencies]
 pylint = ">=2.17.5"
@@ -44,10 +45,13 @@ pytest-cov = ">=4.1.0"
 ruff = "^0.12.0"
 pre-commit = "^4.2.0"
 setuptools = "^80.9.0"
-pytest = "^8.4.1"
+pytest = "^9.0.3"
+pygments = ">=2.20.0"
+filelock = ">=3.20.3"
+virtualenv = ">=20.36.1"
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 100
 src = ["src"]
 extend-exclude = [

{conductor_python-1.3.11 → conductor_python-1.4.0}/src/conductor/client/__init__.py

@@ -3,7 +3,7 @@
 from conductor.client.configuration.configuration import Configuration
 from conductor.client.automator.task_handler import TaskHandler
 from conductor.client.automator.task_runner import TaskRunner
-from conductor.client.orkes_clients import OrkesClients
+from conductor.client.orkes_clients import OrkesClients, ConductorClients
 from conductor.client.workflow.conductor_workflow import ConductorWorkflow
 from conductor.client.workflow.executor.workflow_executor import WorkflowExecutor
 from conductor.client.worker.worker_task import worker_task
@@ -18,6 +18,7 @@ __all__ = [
     "TaskHandler",
     "TaskRunner",
     "OrkesClients",
+    "ConductorClients",
     "ConductorWorkflow",
     "WorkflowExecutor",
     "worker_task",

{conductor_python-1.3.11 → conductor_python-1.4.0}/src/conductor/client/automator/async_task_runner.py

@@ -27,7 +27,7 @@ from conductor.client.http.models.schema_def import SchemaDef, SchemaType
 from conductor.client.http.rest import AuthorizationException, ApiException
 from conductor.client.orkes.orkes_metadata_client import OrkesMetadataClient
 from conductor.client.orkes.orkes_schema_client import OrkesSchemaClient
-from conductor.client.telemetry.metrics_collector import MetricsCollector
+from conductor.client.telemetry.metrics_factory import create_metrics_collector
 from conductor.client.worker.worker_interface import WorkerInterface
 from conductor.client.worker.worker_config import resolve_worker_config, get_worker_config_oneline
 from conductor.client.worker.exception import NonRetryableException
@@ -88,7 +88,7 @@ class AsyncTaskRunner:
 
         self.metrics_collector = None
         if metrics_settings is not None:
-            self.metrics_collector = MetricsCollector(
+            self.metrics_collector = create_metrics_collector(
                 metrics_settings
             )
             # Register metrics collector as event listener
@@ -863,6 +863,7 @@ class AsyncTaskRunner:
             if attempt > 0:
                 # Exponential backoff: [10s, 20s, 30s] before retry
                 await asyncio.sleep(attempt * 10)
+            update_start = time.time()
             try:
                 if self._use_update_v2:
                     next_task = await self.async_task_client.update_task_v2(body=task_result)
@@ -873,6 +874,10 @@ class AsyncTaskRunner:
                         task_definition_name,
                         next_task.task_id if next_task else None
                     )
+                    if self.metrics_collector is not None:
+                        self.metrics_collector.record_task_update_time(
+                            task_definition_name, time.time() - update_start, status="SUCCESS"
+                        )
                     return next_task
                 else:
                     await self.async_task_client.update_task(body=task_result)
@@ -882,6 +887,10 @@ class AsyncTaskRunner:
                         task_result.workflow_instance_id,
                         task_definition_name,
                     )
+                    if self.metrics_collector is not None:
+                        self.metrics_collector.record_task_update_time(
+                            task_definition_name, time.time() - update_start, status="SUCCESS"
+                        )
                     return None
             except ApiException as e:
                 if e.status in (404, 405) and self._use_update_v2:
@@ -895,12 +904,19 @@ class AsyncTaskRunner:
                     # Retry immediately with v1
                     try:
                         await self.async_task_client.update_task(body=task_result)
+                        if self.metrics_collector is not None:
+                            self.metrics_collector.record_task_update_time(
+                                task_definition_name, time.time() - update_start, status="SUCCESS"
+                            )
                         return None
                     except Exception as fallback_e:
                         last_exception = fallback_e
                         continue
                 last_exception = e
                 if self.metrics_collector is not None:
+                    self.metrics_collector.record_task_update_time(
+                        task_definition_name, time.time() - update_start, status="FAILURE"
+                    )
                     self.metrics_collector.increment_task_update_error(
                         task_definition_name, type(e)
                     )
@@ -917,6 +933,9 @@ class AsyncTaskRunner:
             except Exception as e:
                 last_exception = e
                 if self.metrics_collector is not None:
+                    self.metrics_collector.record_task_update_time(
+                        task_definition_name, time.time() - update_start, status="FAILURE"
+                    )
                     self.metrics_collector.increment_task_update_error(
                         task_definition_name, type(e)
                     )

{conductor_python-1.3.11 → conductor_python-1.4.0}/src/conductor/client/automator/task_handler.py

@@ -18,7 +18,7 @@ from conductor.client.configuration.settings.metrics_settings import MetricsSett
 from conductor.client.event.task_runner_events import TaskRunnerEvent
 from conductor.client.event.sync_event_dispatcher import SyncEventDispatcher
 from conductor.client.event.sync_listener_register import register_task_runner_listener
-from conductor.client.telemetry.metrics_collector import MetricsCollector
+from conductor.client.telemetry.metrics_collector_base import MetricsCollectorBase
 from conductor.client.telemetry.model.metric_documentation import MetricDocumentation
 from conductor.client.telemetry.model.metric_label import MetricLabel
 from conductor.client.telemetry.model.metric_name import MetricName
@@ -33,13 +33,24 @@ logger = logging.getLogger(
 )
 
 _decorated_functions = {}
+_VALID_MP_START_METHODS = {"spawn", "fork", "forkserver"}
 _mp_fork_set = False
 if not _mp_fork_set:
     try:
-        if platform == "win32":
-            set_start_method("spawn")
-        else:
-            set_start_method("fork")
+        # The prometheus_client library holds a module-level threading lock;
+        # forking while that lock is held causes a deadlock in child processes.
+        # Set CONDUCTOR_MP_START_METHOD=spawn to avoid this if you hit the
+        # deadlock.  Default is fork for backward compatibility (spawn requires
+        # all Process arguments to be picklable).
+        _default_method = "spawn" if platform == "win32" else "fork"
+        _method = os.environ.get("CONDUCTOR_MP_START_METHOD", "").strip().lower() or _default_method
+        if _method not in _VALID_MP_START_METHODS:
+            logger.warning(
+                "Ignoring invalid CONDUCTOR_MP_START_METHOD=%r; falling back to %r",
+                _method, _default_method,
+            )
+            _method = _default_method
+        set_start_method(_method)
         _mp_fork_set = True
     except Exception as e:
         logger.info("error when setting multiprocessing.set_start_method - maybe the context is set %s", e.args)
@@ -221,11 +232,11 @@ class TaskHandler:
         self._configuration = configuration
         self._metrics_settings = metrics_settings
 
-        # Set prometheus multiprocess directory BEFORE any worker processes start
-        # This must be done before prometheus_client is imported in worker processes
+        # Set PROMETHEUS_MULTIPROC_DIR BEFORE any worker processes start.
+        # MetricsSettings resolves the subdirectory eagerly at construction.
         if metrics_settings is not None:
-            os.environ["PROMETHEUS_MULTIPROC_DIR"] = metrics_settings.directory
-            logger.info(f"Set PROMETHEUS_MULTIPROC_DIR={metrics_settings.directory}")
+            os.environ["PROMETHEUS_MULTIPROC_DIR"] = metrics_settings.metrics_directory
+            logger.info(f"Set PROMETHEUS_MULTIPROC_DIR={metrics_settings.metrics_directory}")
 
         # Store event listeners to pass to each worker process
         self.event_listeners = event_listeners or []
@@ -345,7 +356,7 @@ class TaskHandler:
             self.metrics_provider_process = None
             return
         self.metrics_provider_process = Process(
-            target=MetricsCollector.provide_metrics,
+            target=MetricsCollectorBase.provide_metrics,
             args=(metrics_settings,)
         )
         logger.info("Created MetricsProvider process")

{conductor_python-1.3.11 → conductor_python-1.4.0}/src/conductor/client/automator/task_runner.py

@@ -30,7 +30,7 @@ from conductor.client.http.models.schema_def import SchemaDef, SchemaType
 from conductor.client.http.rest import AuthorizationException, ApiException
 from conductor.client.orkes.orkes_metadata_client import OrkesMetadataClient
 from conductor.client.orkes.orkes_schema_client import OrkesSchemaClient
-from conductor.client.telemetry.metrics_collector import MetricsCollector
+from conductor.client.telemetry.metrics_factory import create_metrics_collector
 from conductor.client.worker.worker import ASYNC_TASK_RUNNING
 from conductor.client.worker.worker_interface import WorkerInterface
 from conductor.client.worker.worker_config import resolve_worker_config, get_worker_config_oneline
@@ -69,7 +69,7 @@ class TaskRunner:
 
         self.metrics_collector = None
         if metrics_settings is not None:
-            self.metrics_collector = MetricsCollector(
+            self.metrics_collector = create_metrics_collector(
                 metrics_settings
             )
             # Register metrics collector as event listener
@@ -972,6 +972,7 @@ class TaskRunner:
             if attempt > 0:
                 # Exponential backoff: [10s, 20s, 30s] before retry
                 time.sleep(attempt * 10)
+            update_start = time.time()
             try:
                 if self._use_update_v2:
                     next_task = self.task_client.update_task_v2(body=task_result)
@@ -982,6 +983,10 @@ class TaskRunner:
                         task_definition_name,
                         next_task.task_id if next_task else None
                     )
+                    if self.metrics_collector is not None:
+                        self.metrics_collector.record_task_update_time(
+                            task_definition_name, time.time() - update_start, status="SUCCESS"
+                        )
                     return next_task
                 else:
                     self.task_client.update_task(body=task_result)
@@ -991,6 +996,10 @@ class TaskRunner:
                         task_result.workflow_instance_id,
                         task_definition_name,
                     )
+                    if self.metrics_collector is not None:
+                        self.metrics_collector.record_task_update_time(
+                            task_definition_name, time.time() - update_start, status="SUCCESS"
+                        )
                     return None
             except ApiException as e:
                 if e.status in (404, 405) and self._use_update_v2:
@@ -1004,12 +1013,19 @@ class TaskRunner:
                     # Retry immediately with v1
                     try:
                         self.task_client.update_task(body=task_result)
+                        if self.metrics_collector is not None:
+                            self.metrics_collector.record_task_update_time(
+                                task_definition_name, time.time() - update_start, status="SUCCESS"
+                            )
                         return None
                     except Exception as fallback_e:
                         last_exception = fallback_e
                         continue
                 last_exception = e
                 if self.metrics_collector is not None:
+                    self.metrics_collector.record_task_update_time(
+                        task_definition_name, time.time() - update_start, status="FAILURE"
+                    )
                     self.metrics_collector.increment_task_update_error(
                         task_definition_name, type(e)
                     )
@@ -1044,6 +1060,9 @@ class TaskRunner:
             except Exception as e:
                 last_exception = e
                 if self.metrics_collector is not None:
+                    self.metrics_collector.record_task_update_time(
+                        task_definition_name, time.time() - update_start, status="FAILURE"
+                    )
                     self.metrics_collector.increment_task_update_error(
                         task_definition_name, type(e)
                     )

conductor_python-1.4.0/src/conductor/client/configuration/settings/metrics_settings.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+import logging
+import os
+from pathlib import Path
+
+from typing import Optional
+
+from conductor.client.configuration.configuration import Configuration
+
+logger = logging.getLogger(
+    Configuration.get_logging_formatted_name(
+        __name__
+    )
+)
+
+
+CANONICAL_SUBDIR = "canonical"
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name, "")
+    if not value:
+        return default
+    return value.strip().lower() in ("true", "1", "yes")
+
+
+def get_default_temporary_folder() -> str:
+    return f"{Path.home()!s}/tmp/"
+
+
+class MetricsSettings:
+    def __init__(
+            self,
+            directory: Optional[str] = None,
+            file_name: str = "metrics.log",
+            update_interval: float = 0.1,
+            http_port: Optional[int] = None,
+            clean_directory: bool = False,
+            clean_dead_pids: bool = False):
+        """
+        Configure metrics collection settings.
+
+        The ``WORKER_CANONICAL_METRICS`` env var is read at construction time
+        to decide whether ``.db`` files go in *directory* (legacy) or in a
+        ``canonical/`` subdirectory (canonical mode).  Set the env var before
+        creating this object.
+
+        Args:
+            directory: Base directory for storing multiprocess metrics .db files.
+                      Legacy metrics use this directory directly (unchanged from
+                      prior releases).  Canonical metrics use a ``canonical/``
+                      subdirectory so that switching implementations never
+                      produces stale metric names.
+            file_name: Name of the metrics output file (only used when http_port is None)
+            update_interval: How often to update metrics (in seconds)
+            http_port: Optional HTTP port to expose metrics endpoint for Prometheus scraping.
+                      If specified:
+                      - An HTTP server will be started on this port
+                      - Metrics served from memory at http://localhost:{port}/metrics
+                      - No file will be written (metrics kept in memory only)
+                      If None:
+                      - Metrics will be written to file at {directory}/{file_name}
+                      - No HTTP server will be started
+            clean_directory: If True, remove all prometheus_client .db files from
+                      the metrics directory when the collector is created.  Only
+                      safe when no other live process shares the same directory.
+                      Defaults to False.
+            clean_dead_pids: If True, remove .db files whose owning PID no
+                      longer exists.  Safer than ``clean_directory`` in shared
+                      environments.  Defaults to False.
+        """
+        if directory is None:
+            directory = get_default_temporary_folder()
+        self.__set_dir(directory)
+        self.file_name = file_name
+        self.update_interval = update_interval
+        self.http_port = http_port
+        self.clean_directory = clean_directory
+        self.clean_dead_pids = clean_dead_pids
+        self._subdir: str = (
+            CANONICAL_SUBDIR
+            if _env_bool("WORKER_CANONICAL_METRICS", False)
+            else ""
+        )
+
+    @property
+    def is_canonical(self) -> bool:
+        return self._subdir == CANONICAL_SUBDIR
+
+    @property
+    def metrics_directory(self) -> str:
+        """Full path where .db files live (base directory + optional subdir).
+
+        Legacy leaves the subdirectory empty (base directory unchanged from
+        prior releases); canonical sets it to ``"canonical"`` to avoid stale
+        metric-name collisions.  Resolved eagerly at construction time from
+        the ``WORKER_CANONICAL_METRICS`` env var.
+        """
+        if self._subdir:
+            return os.path.join(self.directory, self._subdir)
+        return self.directory
+
+    def __set_dir(self, dir: str) -> None:
+        if not os.path.isdir(dir):
+            try:
+                os.mkdir(dir)
+            except Exception as e:
+                logger.warning(
+                    "Failed to create metrics temporary folder, reason: %s", e)
+
+        self.directory = dir
+
+    def _clean_stale_db_files(self) -> None:
+        """Remove all prometheus_client multiprocess .db files."""
+        import glob
+        pattern = os.path.join(self.metrics_directory, "*.db")
+        for path in glob.glob(pattern):
+            try:
+                os.remove(path)
+            except Exception as e:
+                logger.debug("Could not remove stale metrics db file %s: %s", path, e)
+
+    def _clean_dead_pid_files(self) -> None:
+        """Remove .db files whose owning PID no longer exists."""
+        import glob
+        import re
+        pattern = os.path.join(self.metrics_directory, "*.db")
+        for path in glob.glob(pattern):
+            match = re.search(r'_(\d+)\.db$', os.path.basename(path))
+            if not match:
+                continue
+            pid = int(match.group(1))
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                # ESRCH: no process owns this PID -> safe to remove its db file.
+                try:
+                    os.remove(path)
+                    logger.debug("Removed dead-pid metrics file %s (pid %d)", path, pid)
+                except OSError as e:
+                    logger.debug("Could not remove dead-pid metrics db file %s: %s", path, e)
+            except OSError as e:
+                # Any non-ESRCH probe failure (commonly EPERM: the process is
+                # alive but owned by another user) -> keep the file; deleting it
+                # could corrupt a live worker's metrics in a shared directory.
+                logger.debug(
+                    "Keeping metrics db file %s; pid %d probe returned a "
+                    "non-ProcessLookupError OSError (process likely alive): %s",
+                    path, pid, e,
+                )
+                continue