opentelemetry-instrumentation-taskflow 0.0.1__tar.gz

opentelemetry_instrumentation_taskflow-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.tox/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.idea/
+.claude/
+.codegraph/
+uv.lock

opentelemetry_instrumentation_taskflow-0.0.1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: opentelemetry-instrumentation-taskflow
+Version: 0.0.1
+Summary: OpenStack taskflow instrumentation for OpenTelemetry
+Author-email: Pham Le Gia Dai <daipham3213@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-instrumentation
+Requires-Dist: opentelemetry-semantic-conventions
+Requires-Dist: opentelemetry-util-http
+Provides-Extra: instruments
+Requires-Dist: taskflow; extra == 'instruments'
+Description-Content-Type: text/markdown
+
+# OpenTelemetry TaskFlow Instrumentation
+
+OpenStack TaskFlow instrumentation for OpenTelemetry.
+
+It records every `execute`/`revert` call on a `taskflow.task.Task` as a span
+named `taskflow.task.<method>`, annotated with the task's class, method and
+name. Because concrete tasks override `execute`/`revert`, the instrumentor wraps
+`Task.__getattribute__` so those overrides are traced wherever they are defined.
+
+## Usage
+
+```python
+from opentelemetry.instrumentation.taskflow import TaskflowInstrumentor
+
+TaskflowInstrumentor().instrument()
+```

opentelemetry_instrumentation_taskflow-0.0.1/README.md

@@ -0,0 +1,16 @@
+# OpenTelemetry TaskFlow Instrumentation
+
+OpenStack TaskFlow instrumentation for OpenTelemetry.
+
+It records every `execute`/`revert` call on a `taskflow.task.Task` as a span
+named `taskflow.task.<method>`, annotated with the task's class, method and
+name. Because concrete tasks override `execute`/`revert`, the instrumentor wraps
+`Task.__getattribute__` so those overrides are traced wherever they are defined.
+
+## Usage
+
+```python
+from opentelemetry.instrumentation.taskflow import TaskflowInstrumentor
+
+TaskflowInstrumentor().instrument()
+```

opentelemetry_instrumentation_taskflow-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "opentelemetry-instrumentation-taskflow"
+description = "OpenStack taskflow instrumentation for OpenTelemetry"
+readme = "README.md"
+authors = [
+    { name = "Pham Le Gia Dai", email = "daipham3213@gmail.com" }
+]
+requires-python = ">=3.10"
+dynamic = ["version"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "opentelemetry-api",
+    "opentelemetry-instrumentation",
+    "opentelemetry-semantic-conventions",
+    "opentelemetry-util-http",
+]
+
+[project.optional-dependencies]
+instruments = [
+    "taskflow"
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+taskflow = "opentelemetry.instrumentation.taskflow:TaskflowInstrumentor"
+
+[tool.hatch.version]
+path = "src/opentelemetry/instrumentation/taskflow/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

opentelemetry_instrumentation_taskflow-0.0.1/src/opentelemetry/instrumentation/taskflow/__init__.py

@@ -0,0 +1,122 @@
+"""OpenTelemetry instrumentation for TaskFlow.
+
+`TaskFlow <https://docs.openstack.org/taskflow/>`_ models work as *atoms* — most
+commonly :class:`~taskflow.task.Task` objects that implement an ``execute``
+method (to perform work) and an optional ``revert`` method (to roll it back when
+a flow fails). This instrumentor records every ``execute``/``revert`` call as a
+span named ``taskflow.task.<method>``, annotated with the task's class, method
+and name.
+
+Concrete tasks override ``execute``/``revert``, so patching the methods on
+:class:`~taskflow.task.Task` itself would never see those overrides. Instead the
+instrumentor wraps ``Task.__getattribute__`` so that accessing either method on
+*any* Task instance returns a traced wrapper, regardless of where the method is
+defined.
+
+Usage::
+
+    from opentelemetry.instrumentation.taskflow import TaskflowInstrumentor
+
+    TaskflowInstrumentor().instrument()
+"""
+
+from functools import wraps
+from typing import Collection
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.taskflow.version import __version__
+
+try:
+    from taskflow.task import Task
+except ImportError:
+    Task = None
+
+_instruments = ("taskflow",)
+_TRACED_METHODS = frozenset(("execute", "revert"))
+
+
+def _task_attributes(task, method):
+    """Build the span attributes describing ``task`` and the called ``method``."""
+    task_type = type(task)
+    attributes = {
+        "taskflow.task.class": f"{task_type.__module__}.{task_type.__qualname__}",
+        "taskflow.task.method": method,
+    }
+
+    task_name = getattr(task, "name", None)
+    if task_name is not None:
+        attributes["taskflow.task.name"] = task_name
+
+    return attributes
+
+
+def _wrap_task_method(task, method_name, method, tracer):
+    """Wrap a bound task method so each call is recorded as a span."""
+
+    @wraps(method)
+    def traced_method(*args, **kwargs):
+        with tracer.start_as_current_span(
+            f"taskflow.task.{method_name}",
+            attributes=_task_attributes(task, method_name),
+            record_exception=True,
+            set_status_on_exception=True,
+        ):
+            return method(*args, **kwargs)
+
+    return traced_method
+
+
+def _wrap_getattribute(getattribute, tracer):
+    """Wrap ``Task.__getattribute__`` to trace traced-method lookups."""
+
+    def traced_getattribute(self, name):
+        attribute = getattribute(self, name)
+        if name in _TRACED_METHODS and callable(attribute):
+            return _wrap_task_method(self, name, attribute, tracer)
+        return attribute
+
+    return traced_getattribute
+
+
+class TaskflowInstrumentor(BaseInstrumentor):
+    """An instrumentor for TaskFlow task atoms.
+
+    Args:
+        tracer_provider: ``TracerProvider`` used to obtain the tracer. Defaults
+            to the global provider.
+    """
+
+    _original_getattribute = None
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        if Task is None:
+            return  # taskflow is not available
+
+        if TaskflowInstrumentor._original_getattribute is not None:
+            return  # already instrumented
+
+        tracer = trace.get_tracer(
+            __name__,
+            __version__,
+            tracer_provider=kwargs.get("tracer_provider"),
+        )
+
+        TaskflowInstrumentor._original_getattribute = Task.__getattribute__
+        Task.__getattribute__ = _wrap_getattribute(
+            TaskflowInstrumentor._original_getattribute,
+            tracer,
+        )
+
+    def _uninstrument(self, **kwargs):
+        if TaskflowInstrumentor._original_getattribute is None:
+            return
+
+        Task.__getattribute__ = TaskflowInstrumentor._original_getattribute
+        TaskflowInstrumentor._original_getattribute = None
+
+
+__all__ = ["TaskflowInstrumentor", "__version__"]

opentelemetry_instrumentation_taskflow-0.0.1/src/opentelemetry/instrumentation/taskflow/version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

opentelemetry_instrumentation_taskflow-0.0.1/tests/test_taskflow.py

@@ -0,0 +1,134 @@
+import pytest
+from taskflow import task
+
+from opentelemetry.instrumentation.taskflow import TaskflowInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+    InMemorySpanExporter,
+)
+from opentelemetry.trace import StatusCode
+
+
+class DemoTask(task.Task):
+    def execute(self, **kwargs):
+        return kwargs.get("value", "ok")
+
+    def revert(self, *args, **kwargs):
+        return kwargs.get("result", "reverted")
+
+
+class FailingTask(task.Task):
+    def execute(self, **kwargs):
+        raise ValueError(kwargs.get("message", "boom"))
+
+
+@pytest.fixture(autouse=True)
+def uninstrument_taskflow():
+    TaskflowInstrumentor().uninstrument()
+    yield
+    TaskflowInstrumentor().uninstrument()
+
+
+@pytest.fixture
+def span_exporter():
+    return InMemorySpanExporter()
+
+
+@pytest.fixture
+def instrumentor(span_exporter):
+    tracer_provider = TracerProvider()
+    tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
+
+    instrumentor = TaskflowInstrumentor()
+    instrumentor.instrument(tracer_provider=tracer_provider)
+
+    yield instrumentor
+
+    instrumentor.uninstrument()
+
+
+def assert_task_span(span, *, method, task_name, task_class="DemoTask"):
+    assert span.name == f"taskflow.task.{method}"
+    assert span.attributes["taskflow.task.class"].endswith(f".{task_class}")
+    assert span.attributes["taskflow.task.method"] == method
+    assert span.attributes["taskflow.task.name"] == task_name
+
+
+def test_instrumentation_dependencies():
+    assert TaskflowInstrumentor().instrumentation_dependencies() == (
+        "taskflow",
+    )
+
+
+@pytest.mark.parametrize(
+    ("method", "kwargs", "expected"),
+    (
+        ("execute", {"value": "done"}, "done"),
+        ("revert", {"result": "rolled-back"}, "rolled-back"),
+    ),
+)
+def test_task_lifecycle_methods_create_spans(
+    instrumentor,
+    span_exporter,
+    method,
+    kwargs,
+    expected,
+):
+    result = getattr(DemoTask(name="demo-task"), method)(**kwargs)
+
+    spans = span_exporter.get_finished_spans()
+    assert result == expected
+    assert len(spans) == 1
+    assert_task_span(spans[0], method=method, task_name="demo-task")
+
+
+def test_subclass_overrides_are_wrapped(instrumentor, span_exporter):
+    # ``execute`` is defined on the subclass, not on ``Task`` — wrapping
+    # ``__getattribute__`` is what lets the instrumentor see it.
+    assert DemoTask(name="subclass-task").execute(value="done") == "done"
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1
+    assert_task_span(spans[0], method="execute", task_name="subclass-task")
+
+
+def test_instrument_twice_does_not_create_nested_duplicate_spans(
+    instrumentor,
+    span_exporter,
+):
+    instrumentor.instrument()
+
+    assert DemoTask(name="demo-task").execute(value="done") == "done"
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1
+    assert_task_span(spans[0], method="execute", task_name="demo-task")
+
+
+def test_uninstrument_restores_task_without_creating_spans(
+    instrumentor,
+    span_exporter,
+):
+    instrumentor.uninstrument()
+
+    result = DemoTask(name="demo-task").execute(value="done")
+
+    assert result == "done"
+    assert span_exporter.get_finished_spans() == ()
+
+
+def test_exception_is_recorded_on_span(instrumentor, span_exporter):
+    with pytest.raises(ValueError, match="boom"):
+        FailingTask(name="failing-task").execute(message="boom")
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1
+    assert_task_span(
+        spans[0],
+        method="execute",
+        task_name="failing-task",
+        task_class="FailingTask",
+    )
+    assert spans[0].status.status_code == StatusCode.ERROR
+    assert any(event.name == "exception" for event in spans[0].events)