taskflow-meter 1.0.0__py3-none-any.whl

taskflow_meter/collect/attachment.py

@@ -0,0 +1,208 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Attach to a running engine: the whole in-process path in one call.
+
+Named ``attachment`` rather than ``attach`` because the package
+re-exports the :func:`attach` function, and a module of the same name
+would be shadowed by it -- leaving ``taskflow_meter.collect.attach``
+meaning one thing to an importer and another to anything that resolves
+attributes.
+
+    with attach(engine) as watched:
+        engine.run()
+        meter = Meter(watched.store, poll=False)
+
+What that gets you over reading persistence is latency and shape: state
+changes arrive as the engine makes them rather than a poll interval
+later, per-task progress arrives the moment a task reports it, and the
+flow's graph -- which taskflow never persists -- is emitted once up
+front so a UI can draw the thing instead of tailing a list.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import time
+from collections.abc import Callable
+from collections.abc import Iterator
+from collections.abc import Sequence
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+
+from taskflow.engines.action_engine import compiler as tf_compiler
+
+from taskflow_meter.collect.listener import MeterListener
+from taskflow_meter.collect.pipeline import EventPipeline
+from taskflow_meter.collect.progress import ProgressTap
+from taskflow_meter.datasource.base import WritableDataSource
+from taskflow_meter.datasource.memory import MemoryDataSource
+from taskflow_meter.events import Event
+from taskflow_meter.events import EventKind
+from taskflow_meter.events import SequenceAllocator
+from taskflow_meter.transports.base import Publisher
+from taskflow_meter.transports.memory import DataSourcePublisher
+
+LOG = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class Attachment:
+    """What is watching one engine, and where its events landed."""
+
+    engine: Any
+    store: WritableDataSource | None
+    pipeline: EventPipeline
+    listener: MeterListener
+    tap: ProgressTap
+    allocator: SequenceAllocator = field(default_factory=SequenceAllocator)
+
+    @property
+    def run_id(self) -> str:
+        return self.listener.run_id
+
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Wait for queued events to be delivered."""
+        return self.pipeline.flush(timeout)
+
+
+@contextlib.contextmanager
+def attach(
+    engine: Any,
+    *,
+    store: WritableDataSource | None = None,
+    publishers: Sequence[Publisher] = (),
+    book_id: str | None = None,
+    emit_structure: bool = True,
+    max_queue: int = 1000,
+    clock: Callable[[], float] = time.time,
+) -> Iterator[Attachment]:
+    """Watch ``engine`` for as long as the block runs.
+
+    An in-memory store is created unless one is given, so the simple
+    case needs no arguments.  Everything is torn down on the way out,
+    including when the flow raises -- a callback left registered on
+    somebody's task object outlives the monitoring that wanted it.
+    """
+    resolved_store = MemoryDataSource() if store is None else store
+    sinks: list[Publisher] = [DataSourcePublisher(resolved_store)]
+    sinks.extend(publishers)
+
+    pipeline = EventPipeline(sinks, max_queue=max_queue)
+    allocator = SequenceAllocator()
+    listener = MeterListener(
+        engine,
+        pipeline.submit,
+        allocator=allocator,
+        clock=clock,
+        book_id=book_id,
+    )
+    tap = ProgressTap(
+        engine,
+        pipeline.submit,
+        allocator=allocator,
+        clock=clock,
+        book_id=book_id,
+    )
+
+    pipeline.start()
+    try:
+        with listener:
+            tap.register()
+            try:
+                if emit_structure:
+                    _emit_structure(
+                        engine, pipeline.submit, allocator, clock, book_id
+                    )
+                yield Attachment(
+                    engine=engine,
+                    store=resolved_store,
+                    pipeline=pipeline,
+                    listener=listener,
+                    tap=tap,
+                    allocator=allocator,
+                )
+            finally:
+                tap.deregister()
+    finally:
+        pipeline.stop()
+
+
+def _emit_structure(
+    engine: Any,
+    emit: Callable[[Event], Any],
+    allocator: SequenceAllocator,
+    clock: Callable[[], float],
+    book_id: str | None,
+) -> None:
+    """Emit the flow's graph, once, before anything runs."""
+    try:
+        graph = describe_graph(engine)
+    except Exception:
+        # Topology is a bonus; failing to read it must not stop the
+        # states and progress that are the point.
+        LOG.exception("could not describe the flow's graph")
+        return
+
+    run_id = str(engine.storage.flow_uuid)
+    emit(
+        Event(
+            run_id=run_id,
+            seq=allocator.allocate(run_id),
+            ts=clock(),
+            kind=EventKind.FLOW_STRUCTURE,
+            book_id=book_id,
+            details=graph,
+        )
+    )
+
+
+def describe_graph(engine: Any) -> dict[str, Any]:
+    """Render the compiled execution graph as plain data.
+
+    This is the thing the persistence datasource can never provide:
+    taskflow stores atoms but not the edges between them, so the shape
+    of a flow only exists in the process that compiled it.
+    """
+    engine.compile()
+    compilation = engine.compilation
+    graph = compilation.execution_graph
+
+    nodes = [
+        {"name": _name(node), "kind": str(data.get("kind", ""))}
+        for node, data in graph.nodes(data=True)
+    ]
+    edges = [
+        {"from": _name(source), "to": _name(target)}
+        for source, target in graph.edges()
+    ]
+    return {
+        "nodes": sorted(nodes, key=lambda item: (item["kind"], item["name"])),
+        "edges": sorted(edges, key=lambda item: (item["from"], item["to"])),
+        "atom_count": sum(
+            1
+            for _, data in graph.nodes(data=True)
+            if data.get("kind") in tf_compiler.ATOMS
+        ),
+    }
+
+
+def _name(node: Any) -> str:
+    """The name of a graph node.
+
+    Not ``str(node)``: an atom's repr is its decorated form, so a task
+    called "first" renders as '"first==1.0"' and matches nothing a
+    client knows it by.
+    """
+    return str(getattr(node, "name", None) or node)

taskflow_meter/collect/listener.py

@@ -0,0 +1,161 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Watch an engine's notifiers for flow and atom state changes.
+
+The half of the in-process path taskflow makes easy: a listener sees
+every state transition, with the engine reporting them as they happen
+rather than a poll interval later.
+
+It is only half.  taskflow never re-emits intra-task progress on the
+atom notifier, so the numbers a task reports about itself arrive
+through :mod:`taskflow_meter.collect.progress` instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from taskflow.listeners import base as tf_listeners
+
+from taskflow_meter.events import Event
+from taskflow_meter.events import EventKind
+from taskflow_meter.events import SequenceAllocator
+from taskflow_meter.models import RETRY
+from taskflow_meter.models import TASK
+
+LOG = logging.getLogger(__name__)
+
+Emit = Callable[[Event], Any]
+
+
+class MeterListener(tf_listeners.Listener):
+    """Turns an engine's notifications into events."""
+
+    def __init__(
+        self,
+        engine: Any,
+        emit: Emit,
+        *,
+        allocator: SequenceAllocator | None = None,
+        clock: Callable[[], float] = time.time,
+        book_id: str | None = None,
+    ) -> None:
+        """Watch ``engine``, handing each event to ``emit``.
+
+        ``book_id`` has to be supplied because nothing on the engine
+        knows it: storage holds a flow detail and a backend, and a flow
+        detail carries no reference back to the logbook that owns it.
+        Whoever created the book has it; we would only be guessing.
+        """
+        super().__init__(engine)
+        self._emit = emit
+        self._allocator = allocator or SequenceAllocator()
+        self._clock = clock
+        self._book_id = book_id
+
+    @property
+    def allocator(self) -> SequenceAllocator:
+        return self._allocator
+
+    @property
+    def run_id(self) -> str:
+        """The flow detail uuid, which is how a run is identified."""
+        return str(self._engine.storage.flow_uuid)
+
+    # -- receivers -------------------------------------------------------
+
+    def _flow_receiver(self, state: str, details: dict[str, Any]) -> None:
+        self._safely(
+            EventKind.FLOW_STATE,
+            state=state,
+            old_state=details.get("old_state"),
+            extra={"flow_name": details.get("flow_name")},
+        )
+
+    def _task_receiver(self, state: str, details: dict[str, Any]) -> None:
+        self._atom_event(state, details, TASK, "task")
+
+    def _retry_receiver(self, state: str, details: dict[str, Any]) -> None:
+        self._atom_event(state, details, RETRY, "retry")
+
+    def _atom_event(
+        self,
+        state: str,
+        details: dict[str, Any],
+        atom_type: str,
+        prefix: str,
+    ) -> None:
+        extra: dict[str, Any] = {}
+        if "result" in details:
+            # Results are arbitrary application objects and are not
+            # ours to copy around; their presence is the useful part.
+            extra["has_result"] = details["result"] is not None
+        self._safely(
+            EventKind.ATOM_STATE,
+            state=state,
+            old_state=details.get("old_state"),
+            atom_name=details.get(f"{prefix}_name"),
+            atom_uuid=details.get(f"{prefix}_uuid"),
+            atom_type=atom_type,
+            extra=extra,
+        )
+
+    # -- emitting --------------------------------------------------------
+
+    def _safely(self, kind: EventKind, **fields: Any) -> None:
+        """Build and emit one event, swallowing anything that goes wrong.
+
+        This runs on the engine's thread -- an executor thread under the
+        parallel engine.  An exception escaping here would surface
+        inside somebody's flow as a monitoring bug they did not ask for.
+        """
+        try:
+            self._emit(self._build(kind, **fields))
+        except Exception:
+            LOG.exception("could not emit a %s event", kind)
+
+    def _build(
+        self,
+        kind: EventKind,
+        *,
+        state: str | None = None,
+        old_state: str | None = None,
+        atom_name: str | None = None,
+        atom_uuid: str | None = None,
+        atom_type: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> Event:
+        run_id = self.run_id
+        details = {
+            key: value
+            for key, value in (extra or {}).items()
+            if value is not None
+        }
+        return Event(
+            run_id=run_id,
+            seq=self._allocator.allocate(run_id),
+            # Unlike the poller's, this timestamp really is when it
+            # happened: the engine is telling us as it does it.
+            ts=self._clock(),
+            kind=kind,
+            book_id=self._book_id,
+            atom_name=atom_name,
+            atom_uuid=atom_uuid,
+            atom_type=atom_type,
+            state=state,
+            old_state=old_state,
+            details=details,
+        )

taskflow_meter/collect/pipeline.py

@@ -0,0 +1,229 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""The barrier between a running flow and everything downstream.
+
+We are inside somebody else's task.  A slow webhook, a full disk or a
+bug in a publisher must cost that task nothing, so the rules here are
+absolute:
+
+* :meth:`EventPipeline.submit` never raises and never blocks.  It puts
+  the event on a bounded queue and returns.
+* All delivery happens on a sender thread.  Nothing downstream runs on
+  the thread executing the task.
+* A full queue drops, counts and logs.  Blocking would stall the flow;
+  growing without limit would take the process down later, for reasons
+  nobody would connect back to monitoring.
+* A publisher that raises is logged and counted.  The next batch is
+  still attempted, because one bad delivery is not a reason to stop
+  watching.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+from collections.abc import Callable
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from taskflow_meter.events import Event
+from taskflow_meter.transports.base import Publisher
+
+LOG = logging.getLogger(__name__)
+
+DEFAULT_MAX_QUEUE = 1000
+DEFAULT_BATCH = 100
+
+#: Pushed on the queue to wake the sender for shutdown.
+_STOP = object()
+
+
+@dataclass(slots=True)
+class PipelineStats:
+    """Counters worth exposing on a health endpoint."""
+
+    submitted: int = 0
+    delivered: int = 0
+    dropped: int = 0
+    errors: int = 0
+    last_error: str | None = None
+
+
+class EventPipeline:
+    """Queues events and delivers them to publishers off-thread."""
+
+    def __init__(
+        self,
+        publishers: Sequence[Publisher],
+        *,
+        max_queue: int = DEFAULT_MAX_QUEUE,
+        batch_size: int = DEFAULT_BATCH,
+        on_drop: Callable[[Event], None] | None = None,
+    ) -> None:
+        if max_queue < 1:
+            msg = "max_queue must be at least 1"
+            raise ValueError(msg)
+        if batch_size < 1:
+            msg = "batch_size must be at least 1"
+            raise ValueError(msg)
+
+        self.publishers = tuple(publishers)
+        self.batch_size = batch_size
+        self.stats = PipelineStats()
+        self._on_drop = on_drop
+        self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
+        self._lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+        self._idle = threading.Event()
+        self._idle.set()
+
+    @property
+    def running(self) -> bool:
+        with self._lock:
+            return self._thread is not None and self._thread.is_alive()
+
+    # -- the flow's side -------------------------------------------------
+
+    def submit(self, event: Event) -> bool:
+        """Queue an event.  Returns whether *this* event was queued.
+
+        A full queue makes room by discarding the oldest, so a true
+        return does not mean nothing was lost -- ``stats.dropped`` is
+        what says that.
+
+        Called from task and executor threads.  It cannot raise: a
+        monitoring bug must never fail somebody's task.
+        """
+        self.stats.submitted += 1
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            return self._make_room_for(event)
+        except Exception:  # pragma: no cover - defensive
+            LOG.exception("could not queue an event")
+            return False
+        else:
+            self._idle.clear()
+            return True
+
+    def _make_room_for(self, event: Event) -> bool:
+        """Discard the oldest to fit ``event`` in, and say so."""
+        try:
+            self._queue.get_nowait()
+            self._queue.task_done()
+        except queue.Empty:  # pragma: no cover - racing a fast drain
+            pass
+        self.stats.dropped += 1
+        LOG.warning(
+            "event queue is full at %d; dropped the oldest (%d so far)",
+            self._queue.maxsize,
+            self.stats.dropped,
+        )
+        if self._on_drop is not None:
+            try:
+                self._on_drop(event)
+            except Exception:
+                LOG.exception("drop handler failed")
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:  # pragma: no cover - racing another producer
+            self.stats.dropped += 1
+            return False
+        self._idle.clear()
+        return True
+
+    # -- lifecycle -------------------------------------------------------
+
+    def start(self) -> None:
+        """Begin delivering on a daemon thread.  Idempotent."""
+        with self._lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            for publisher in self.publishers:
+                publisher.start()
+            self._thread = threading.Thread(
+                target=self._run,
+                name="taskflow-meter-pipeline",
+                daemon=True,
+            )
+            self._thread.start()
+
+    def stop(self, *, drain: bool = True, timeout: float = 5.0) -> None:
+        """Finish delivering and shut the sender down.  Idempotent."""
+        with self._lock:
+            thread = self._thread
+            self._thread = None
+        if thread is not None and thread.is_alive():
+            if drain:
+                self.flush(timeout)
+            self._queue.put(_STOP)
+            thread.join(timeout)
+            if thread.is_alive():
+                LOG.warning(
+                    "pipeline thread did not stop within %.1fs", timeout
+                )
+        for publisher in self.publishers:
+            try:
+                publisher.stop()
+            except Exception:
+                LOG.exception("failed stopping %r", publisher)
+
+    def flush(self, timeout: float = 5.0) -> bool:
+        """Wait for the queue to empty.  Returns whether it did."""
+        return self._idle.wait(timeout)
+
+    # -- the sender's side -----------------------------------------------
+
+    def _run(self) -> None:
+        while True:
+            taken = [self._queue.get()]
+            taken.extend(self._take_more())
+            # The sentinel can be picked up mid-batch, not just on its
+            # own: a producer racing shutdown puts events behind it.
+            # Missing it here would leave the sender running forever.
+            stopping = any(entry is _STOP for entry in taken)
+
+            self._deliver(
+                [entry for entry in taken if isinstance(entry, Event)]
+            )
+            for _ in taken:
+                self._queue.task_done()
+            if self._queue.empty():
+                self._idle.set()
+            if stopping:
+                return
+
+    def _take_more(self) -> list[object]:
+        """Drain what is already waiting, up to a batch."""
+        more: list[object] = []
+        while len(more) + 1 < self.batch_size:
+            try:
+                more.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        return more
+
+    def _deliver(self, events: list[Event]) -> None:
+        if not events:
+            return
+        for publisher in self.publishers:
+            try:
+                publisher.publish(events)
+            except Exception as exc:
+                # One bad delivery is not a reason to stop watching.
+                self.stats.errors += 1
+                self.stats.last_error = repr(exc)
+                LOG.exception("publisher %r failed", publisher)
+            else:
+                self.stats.delivered += len(events)