📌 ISSUE-#173: Resolve merge conflict with develop — keep Providers removed from How-to

Author: FernandoCelmer

docs/nav/integrations/index.md

@@ -86,6 +86,28 @@
 
 </div>
 
+## Sentry
+
+<div class="grid cards dotflow-integration-grid" markdown>
+
+- :material-bug-outline: __Error Monitoring__
+
+    ---
+
+    Send task errors to **Sentry** for real-time error tracking in production workflows.
+
+    [:octicons-arrow-right-24: How-to](../tutorial/log-sentry.md)
+
+- :material-speedometer: __Performance Monitoring__
+
+    ---
+
+    Track workflow transactions and task spans with **Sentry Performance** — durations, waterfalls, and bottlenecks.
+
+    [:octicons-arrow-right-24: How-to](../tutorial/tracer-sentry.md)
+
+</div>
+
 ## Built-in
 
 <div class="grid cards dotflow-integration-grid" markdown>

docs/nav/reference/log-sentry.md

@@ -0,0 +1,3 @@
+# LogSentry
+
+::: dotflow.providers.log_sentry.LogSentry

docs/nav/reference/tracer-sentry.md

@@ -0,0 +1,3 @@
+# TracerSentry
+
+::: dotflow.providers.tracer_sentry.TracerSentry

docs/nav/tutorial/log-sentry.md

@@ -0,0 +1,70 @@
+# Log Sentry
+
+`LogSentry` sends task errors to [Sentry](https://sentry.io) for real-time error monitoring. Status changes are recorded as breadcrumbs for context.
+
+Use this when your workflows run in production (Lambda, Cloud Run, servers) and you need error tracking beyond local logs.
+
+/// note
+Requires `pip install dotflow[sentry]`
+///
+
+## Setup
+
+```bash
+pip install dotflow[sentry]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `dsn` | `str` | — | Sentry DSN for the project (required) |
+| `environment` | `str \| None` | `None` | Environment tag sent to Sentry |
+| `traces_sample_rate` | `float` | `0.0` | Sample rate for performance traces (0.0 to 1.0) |
+
+## Basic example
+
+{* ./docs_src/config/log_sentry.py hl[2,16:20] *}
+
+## What gets captured
+
+| Event | Sentry action |
+|-------|---------------|
+| Task status changes (info) | Breadcrumb |
+| Task retries (warning) | Breadcrumb |
+| Task failures (error) | `capture_message` with extras |
+| Debug events | Ignored |
+
+Each error capture includes:
+
+- `workflow_id` — which workflow failed
+- `task_id` — which task failed
+- `exception` — exception type
+- `attempt` — retry attempt number
+- `traceback` — full traceback
+
+## Combining with other log providers
+
+Sentry is for error monitoring, not general logging. Use it alongside `LogDefault` or `LogOpenTelemetry` by choosing one per workflow:
+
+```python
+from dotflow import Config, DotFlow
+from dotflow.providers import LogSentry
+
+# Production: errors go to Sentry
+prod_config = Config(
+    log=LogSentry(dsn="https://xxx@sentry.io/123", environment="production"),
+)
+
+# Development: logs go to console
+from dotflow.providers import LogDefault
+dev_config = Config(
+    log=LogDefault(output="console", format="json"),
+)
+```
+
+## References
+
+- [LogSentry](https://dotflow-io.github.io/dotflow/nav/reference/log-sentry/)
+- [Log Default](https://dotflow-io.github.io/dotflow/nav/tutorial/log-default/)
+- [Log OpenTelemetry](https://dotflow-io.github.io/dotflow/nav/tutorial/log-opentelemetry/)

docs/nav/tutorial/tracer-sentry.md

@@ -0,0 +1,52 @@
+# Tracer Sentry
+
+`TracerSentry` uses [Sentry Performance Monitoring](https://docs.sentry.io/product/performance/) to create transactions per workflow and spans per task.
+
+Use this when you want to track task durations, identify slow tasks, and see the full workflow waterfall in the Sentry dashboard.
+
+/// note
+Requires `pip install dotflow[sentry]`
+///
+
+## Setup
+
+```bash
+pip install dotflow[sentry]
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `dsn` | `str \| None` | `None` | Sentry DSN. If None, reuses the SDK already initialized (e.g. by LogSentry) |
+| `environment` | `str \| None` | `None` | Environment tag sent to Sentry |
+| `traces_sample_rate` | `float` | `1.0` | Sample rate for performance traces (0.0 to 1.0) |
+
+## Basic example
+
+{* ./docs_src/config/tracer_sentry.py hl[2,17:22] *}
+
+## What gets captured
+
+| Event | Sentry action |
+|-------|---------------|
+| Workflow starts | Transaction created (`op="workflow"`) |
+| Workflow ends | Transaction finished with status `ok` or `internal_error` |
+| Task starts | Child span created (`op="task"`) |
+| Task ends | Span finished with duration, retry count, and error details |
+
+## Full Sentry stack
+
+Use both `LogSentry` and `TracerSentry` together for error tracking + performance monitoring:
+
+{* ./docs_src/config/sentry_full.py hl[2,17:24] *}
+
+/// tip
+When using both providers, pass the `dsn` only to `LogSentry`. `TracerSentry` reuses the already initialized SDK — no need to pass `dsn` again.
+///
+
+## References
+
+- [TracerSentry](https://dotflow-io.github.io/dotflow/nav/reference/tracer-sentry/)
+- [LogSentry](https://dotflow-io.github.io/dotflow/nav/tutorial/log-sentry/)
+- [Tracer OpenTelemetry](https://dotflow-io.github.io/dotflow/nav/tutorial/tracer-opentelemetry/)

docs_src/config/log_sentry.py

@@ -0,0 +1,32 @@
+from dotflow import Config, DotFlow, action
+from dotflow.providers import LogSentry
+
+
+@action
+def extract():
+    return {"data": "fetched"}
+
+
+@action
+def transform(previous_context):
+    return {"result": previous_context.storage}
+
+
+def main():
+    config = Config(
+        log=LogSentry(
+            dsn="https://xxx@sentry.io/123",
+            environment="production",
+        ),
+    )
+
+    workflow = DotFlow(config=config)
+    workflow.task.add(step=extract)
+    workflow.task.add(step=transform)
+    workflow.start()
+
+    return workflow
+
+
+if __name__ == "__main__":
+    main()

docs_src/config/sentry_full.py

@@ -0,0 +1,35 @@
+from dotflow import Config, DotFlow, action
+from dotflow.providers import LogSentry, TracerSentry
+
+
+@action
+def extract():
+    return {"data": "fetched"}
+
+
+@action
+def transform(previous_context):
+    return {"result": previous_context.storage}
+
+
+def main():
+    config = Config(
+        log=LogSentry(
+            dsn="https://xxx@sentry.io/123",
+            environment="production",
+        ),
+        tracer=TracerSentry(
+            traces_sample_rate=1.0,
+        ),
+    )
+
+    workflow = DotFlow(config=config)
+    workflow.task.add(step=extract)
+    workflow.task.add(step=transform)
+    workflow.start()
+
+    return workflow
+
+
+if __name__ == "__main__":
+    main()

docs_src/config/tracer_sentry.py

@@ -0,0 +1,33 @@
+from dotflow import Config, DotFlow, action
+from dotflow.providers import TracerSentry
+
+
+@action
+def extract():
+    return {"data": "fetched"}
+
+
+@action
+def transform(previous_context):
+    return {"result": previous_context.storage}
+
+
+def main():
+    config = Config(
+        tracer=TracerSentry(
+            dsn="https://xxx@sentry.io/123",
+            environment="production",
+            traces_sample_rate=1.0,
+        ),
+    )
+
+    workflow = DotFlow(config=config)
+    workflow.task.add(step=extract)
+    workflow.task.add(step=transform)
+    workflow.start()
+
+    return workflow
+
+
+if __name__ == "__main__":
+    main()

dotflow/providers/__init__.py

@@ -13,6 +13,7 @@
 __all__ = [
     "LogDefault",
     "LogOpenTelemetry",
+    "LogSentry",
     "NotifyDefault",
     "NotifyDiscord",
     "NotifyTelegram",
@@ -26,6 +27,7 @@
     "MetricsOpenTelemetry",
     "TracerDefault",
     "TracerOpenTelemetry",
+    "TracerSentry",
 ]
 
 
@@ -62,4 +64,14 @@ def __getattr__(name):
 
         return LogOpenTelemetry
 
+    if name == "LogSentry":
+        from dotflow.providers.log_sentry import LogSentry
+
+        return LogSentry
+
+    if name == "TracerSentry":
+        from dotflow.providers.tracer_sentry import TracerSentry
+
+        return TracerSentry
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

dotflow/providers/log_sentry.py

@@ -0,0 +1,96 @@
+"""Log Sentry"""
+
+from __future__ import annotations
+
+from dotflow.abc.log import Log
+from dotflow.core.exception import ModuleNotFound
+
+
+class LogSentry(Log):
+    """
+    Import:
+        You can import the **LogSentry** class with:
+
+            from dotflow.providers import LogSentry
+
+    Example:
+        `class` dotflow.providers.log_sentry.LogSentry
+
+            from dotflow import Config, DotFlow
+            from dotflow.providers import LogSentry
+
+            config = Config(
+                log=LogSentry(
+                    dsn="https://xxx@sentry.io/123",
+                    environment="production",
+                ),
+            )
+
+            workflow = DotFlow(config=config)
+
+    Args:
+        dsn (str): Sentry DSN for the project.
+        environment (str): Environment tag sent to Sentry.
+            Defaults to None.
+        traces_sample_rate (float): Sample rate for performance traces (0.0 to 1.0).
+            Defaults to 0.0.
+    """
+
+    def __init__(
+        self,
+        dsn: str,
+        environment: str | None = None,
+        traces_sample_rate: float = 0.0,
+    ) -> None:
+        try:
+            import sentry_sdk
+        except ImportError as err:
+            raise ModuleNotFound(
+                module="sentry-sdk", library="dotflow[sentry]"
+            ) from err
+
+        sentry_sdk.init(
+            dsn=dsn,
+            environment=environment,
+            traces_sample_rate=traces_sample_rate,
+        )
+        self._sentry = sentry_sdk
+
+    def info(self, **kwargs) -> None:
+        task = kwargs.get("task")
+        if task:
+            self._sentry.add_breadcrumb(
+                category="dotflow",
+                message=f"task:{task.task_id} {task.status}",
+                level="info",
+            )
+
+    def error(self, **kwargs) -> None:
+        task = kwargs.get("task")
+        if not task or not task.errors:
+            return
+
+        last_error = task.errors[-1]
+        self._sentry.capture_message(
+            f"Task {task.task_id} failed: {last_error.message}",
+            level="error",
+            extras={
+                "workflow_id": str(task.workflow_id),
+                "task_id": str(task.task_id),
+                "exception": str(last_error.exception),
+                "attempt": last_error.attempt,
+                "traceback": last_error.traceback,
+            },
+        )
+
+    def warning(self, **kwargs) -> None:
+        task = kwargs.get("task")
+        if task:
+            self._sentry.add_breadcrumb(
+                category="dotflow",
+                message=f"task:{task.task_id} {task.status}",
+                level="warning",
+            )
+
+    def debug(self, **kwargs) -> None:
+        pass