flowsense-engine 0.3.0__tar.gz → 0.5.0__tar.gz

flowsense_engine-0.5.0/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to FlowSense are documented in this file. The project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [0.5.0] - 2026-09-23
+
+### Added
+
+- Added a production quickstart and executable bounded batch-analysis example.
+- Added `flowsense doctor` for safe configuration, Airflow API, authentication,
+  and DAG-visibility diagnostics.
+- Added `flowsense dags` for read-only DAG discovery with table and JSON output.
+- Added `flowsense analyze-batch` for bounded multi-DAG CLI analysis with the
+  versioned batch JSON contract.
+- Added severity-based CI exit thresholds to batch analysis.
+- Added full analysis-policy configuration to the batch CLI.
+- Added bounded DAG discovery to batch analysis with `--all-dags`,
+  `--dag-limit`, and optional paused-DAG inclusion.
+- Added CLI access to the versioned batch output JSON Schema through
+  `flowsense schema --document batch`.
+- Added reliable versioned JSON file output to single-DAG analysis through
+  `flowsense analyze --output-file`.
+- Added reusable, versioned JSON analysis policies for single and batch CLI
+  commands, with explicit command-line overrides and JSON Schema export.
+- Added versioned analysis-policy support to the optional Prometheus metrics
+  command and propagated the selected policy through every collection cycle.
+- Added a validated per-cycle history limit to the Prometheus metrics command
+  so Airflow collection remains explicitly bounded.
+- Added expanded Ruff quality rules, a 90% CI coverage gate, and graceful MCP
+  test skipping when the optional dependency is not installed.
+- Reduced Airflow collection overhead with bounded server-side DAG run filters
+  and batched task-instance retrieval, including compatibility fallbacks for
+  deployments that do not support the optimized endpoints.
+- Added explicit drift direction and effective MAD fields to analysis results,
+  plus configurable relative and absolute dispersion floors.
+
+### Changed
+
+- Airflow login tokens are now refreshed once after an unauthorized API
+  response, while static bearer, Basic, and custom authentication lifecycles
+  remain application-owned.
+- Advanced the analysis output schema to version `1.2` for the new drift and
+  policy fields.
+
+### Fixed
+
+- Constant and near-constant baselines no longer classify negligible timing
+  noise as an automatic critical anomaly when raw MAD is zero or extremely
+  small.
+
+## [0.4.0] - 2026-09-20
+
+### Added
+
+- Added paginated Airflow 2 and 3 DAG discovery with optional paused-DAG
+  inclusion.
+- Added an immutable multi-DAG analysis result and bounded, opt-in concurrency
+  through `FlowSenseClient.analyze_many()`.
+- Added a versioned, typed batch output document with serialization and JSON
+  Schema helpers.
+- Added the `FlowSenseClient` facade for concise embedded Python usage and an
+  explicit Airflow data-source factory for application-owned configuration.
+- Added pluggable Airflow authentication providers for Basic Auth, login-token
+  exchange, static or rotating bearer tokens, and deployment-specific headers.
+- Added a bounded Prometheus metrics exporter and the optional
+  `flowsense serve-metrics` command for continuous DAG analysis.
+- Added a provisioned Grafana dashboard and local Docker Compose example for
+  inspecting analysis health, coverage, severity, task drift, and handoffs.
+- Added Prometheus alert rules, Alertmanager configuration, synthetic rule
+  tests, and CI validation for FlowSense analysis failures and anomalies.
+
+### Changed
+
+- Kept observability integrations as optional delivery adapters so the core
+  analysis package remains independent from Prometheus, Grafana, and hosted
+  service infrastructure.
+
+## [0.3.0] - 2026-09-20
+
+### Added
+
+- Added `AnalyzeDAG` as the shared application use-case boundary for CLI, MCP,
+  and library integrations.
+- Added the `DAGAnalysisEngine` extension port and injectable default analysis
+  engine.
+- Added versioned golden regression coverage for the complete analysis output.
+- Added deterministic performance benchmarks with machine-readable results and
+  a manually triggered GitHub Actions workflow.
+- Added an Airflow 2 and Airflow 3 REST contract test matrix covering
+  authentication, routing, validation, mapping, and end-to-end analysis.
+
+### Changed
+
+- Separated environment loading and Airflow client construction through explicit
+  `AirflowConfig` and infrastructure factories.
+- Made the `TaskRun` domain entity immutable and framework-independent while
+  keeping Pydantic at external DTO and output-contract boundaries.
+- Added automated enforcement preventing the domain layer from importing
+  Pydantic.
+- Added architecture dependency guardrails and documented supported extension
+  points and compatibility boundaries.
+
+### Fixed
+
+- Rejected non-finite and negative analysis inputs at the domain boundary.
+- Made root-cause selection deterministic when candidates have equal scores.
+
+## [0.2.1] - 2026-09-10
+
+### Changed
+
+- Renamed the Python distribution to `flowsense-engine` while preserving the
+  `flowsense` import package and CLI command.
+- Added tokenless PyPI publishing through GitHub Actions Trusted Publishing.
+
+## [0.2.0] - 2026-09-10
+
+### Added
+
+- Task handoff drift, impact classification, propagation, and root-cause analysis.
+- Configurable drift, mapped-task aggregation, change-point, and trend policies.
+- Apache Airflow 2 and 3 API compatibility with pagination and bounded history.
+- Retry, timeout, backoff, and `Retry-After` handling for Airflow requests.
+- Historical DAG run analysis with preceding-history isolation.
+- Rich CLI reports, JSON output, severity-based exit thresholds, and schema output.
+- MCP analysis tool with the same policy and versioned response contract as the CLI.
+- Typed `AnalysisRequest` and `AnalysisDocument` contracts with JSON Schema support.
+- Supported top-level library API, typed package marker, and Python 3.12/3.13 CI.
+
+### Changed
+
+- Split the analysis workflow into domain, application, infrastructure, and adapter
+  boundaries.
+- Analysis output schema advanced to version `1.1` with `current_dag_run_id`.
+- Expected configuration, Airflow API, and payload failures now use a unified error
+  hierarchy.
+
+### Fixed
+
+- Preserved anomaly origins across normal dependency gaps.
+- Detected drift when the historical median absolute deviation is zero.
+- Aggregated dynamically mapped task instances before analysis.
+- Reported insufficient history and invalid handoff timing as diagnostics.
+
+## [0.1.0] - 2026-08-18
+
+### Added
+
+- Initial FlowSense prototype with Airflow task-duration collection and robust
+  median/MAD drift detection.

{flowsense_engine-0.3.0 → flowsense_engine-0.5.0}/MANIFEST.in

@@ -1,2 +1,3 @@
 include CHANGELOG.md
 recursive-include docs *.md
+recursive-include examples *.py

{flowsense_engine-0.3.0/src/flowsense_engine.egg-info → flowsense_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowsense-engine
-Version: 0.3.0
+Version: 0.5.0
 Summary: Temporal drift and anomaly detection for Apache Airflow
 Author: Omer Cengiz
 License-Expression: Apache-2.0
@@ -28,6 +28,7 @@ Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: pyright>=1.1.400; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
 Provides-Extra: mcp
 Requires-Dist: mcp[cli]>=2.0; extra == "mcp"
@@ -37,10 +38,12 @@ Dynamic: license-file
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+Current package release: `0.5.0`. See [CHANGELOG.md](CHANGELOG.md) for release
 notes, [docs/architecture.md](docs/architecture.md) for the system architecture,
 [docs/benchmarks.md](docs/benchmarks.md) for performance measurement, and
-[docs/migrating-to-0.3.md](docs/migrating-to-0.3.md) for migration guidance.
+[docs/production-quickstart.md](docs/production-quickstart.md) for a production
+walkthrough. See [docs/migrating-to-0.5.md](docs/migrating-to-0.5.md) for the
+current migration guidance.
 Maintainers can use [docs/releasing.md](docs/releasing.md) as the release checklist.
 
 FlowSense analyzes historical DAG executions to identify abnormal task behavior and trace how anomalies propagate through downstream dependencies.
@@ -153,6 +156,9 @@ Once published on PyPI, install the distribution with:
 pip install flowsense-engine
 ```
 
+For an end-to-end Airflow setup, follow the
+[production quickstart](docs/production-quickstart.md).
+
 The distribution name is `flowsense-engine`; Python imports and CLI commands
 remain `flowsense`.
 
@@ -180,6 +186,7 @@ AIRFLOW_USERNAME=your_username
 AIRFLOW_PASSWORD=your_password
 AIRFLOW_API_VERSION=v2
 AIRFLOW_AUTH_MODE=token
+# AIRFLOW_BEARER_TOKEN=your_static_token
 AIRFLOW_CONNECT_TIMEOUT=10
 AIRFLOW_READ_TIMEOUT=10
 AIRFLOW_MAX_RETRIES=2
@@ -192,6 +199,12 @@ Stable REST API deployments. Airflow 3.x uses the `v2` API and typically uses
 token authentication. Authentication still depends on the API auth backend
 configured in the Airflow deployment.
 
+Static bearer tokens can use `AIRFLOW_AUTH_MODE=bearer` with
+`AIRFLOW_BEARER_TOKEN`; username and password are not required in that mode.
+Library integrations may inject a custom `AirflowAuthProvider` for rotating
+tokens, identity-aware proxies, or deployment-specific headers. See
+[docs/authentication.md](docs/authentication.md) for the complete contract.
+
 CI verifies both integrations through versioned Airflow 2 and Airflow 3 REST
 contract fixtures. These boundary tests cover authentication, endpoint routing,
 response validation, domain mapping, and the complete analysis use case.
@@ -211,9 +224,15 @@ export $(grep -v '^#' .env | xargs)
 Then run:
 
 ```bash
+flowsense doctor
+flowsense dags
 flowsense analyze <dag_id>
+flowsense analyze-batch <dag_id> [<dag_id> ...]
 ```
 
+Both single and batch analysis commands support `--fail-on` for CI severity
+gates.
+
 The CLI report includes a DAG summary and separate tables for task drift,
 handoff drift, change points, trends, propagation paths, and diagnostics.
 Results are ordered by severity or subject so repeated analyses remain easy to
@@ -223,14 +242,30 @@ For automation and CI/CD integrations, request the versioned JSON document:
 
 ```bash
 flowsense analyze <dag_id> --output json
+flowsense analyze <dag_id> --output-file flowsense-analysis.json
 ```
 
+`--output-file` always writes the versioned JSON contract and avoids relying on
+shell redirection in CI jobs.
+
 CI jobs can also fail when the analysis reaches a selected severity:
 
 ```bash
 flowsense analyze <dag_id> --output json --fail-on high
 ```
 
+Store reusable analysis settings in a versioned JSON policy file and share it
+between single and batch analysis:
+
+```bash
+flowsense analyze <dag_id> --policy-file flowsense-policy.json
+flowsense analyze-batch --all-dags --dag-limit 10 \
+  --policy-file flowsense-policy.json
+```
+
+Explicit policy options override values loaded from the file. Generate its JSON
+Schema with `flowsense schema --document policy`.
+
 `--fail-on` accepts `medium`, `high`, or `critical`. The report is always
 written before FlowSense exits: code `0` means the severity is below the
 threshold, code `2` means the threshold was reached, and code `1` remains
@@ -258,6 +293,8 @@ flowsense analyze <dag_id> --dag-run-id <dag_run_id>
 
 The MCP tool exposes the same option as `dag_run_id`. Analysis output includes
 `current_dag_run_id`; this field was introduced in output schema version `1.1`.
+Output schema version `1.2` adds drift `direction`, the regularized
+`effective_mad`, and the dispersion-floor policy values.
 
 The JSON document and MCP tool response share the same serialization contract
 and include a `schema_version` field. The serializer is also available from the
@@ -272,28 +309,53 @@ The same schema can be emitted without connecting to Airflow:
 
 ```bash
 flowsense schema > flowsense-analysis.schema.json
+flowsense schema --document batch > flowsense-batch.schema.json
 ```
 
+The default remains the single-DAG analysis schema. Use `--document batch` to
+emit the versioned batch envelope schema, including successful analyses and
+per-DAG failure records.
+
 This output is deterministic and can be used in CI contract checks, editor
 tooling, or client code generation.
 
 ## Library API
 
-FlowSense can also be used as a Python library through its supported top-level
-API:
+`FlowSenseClient` is the recommended in-process Python API. The environment
+configured Airflow factory keeps the basic setup concise:
 
 ```python
-from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense import FlowSenseClient
 from flowsense.infrastructure.airflow import create_airflow_data_source
 
-analysis = AnalyzeDAG(create_airflow_data_source).execute(
-    AnalysisRequest(dag_id="flowsense_demo")
-)
+client = FlowSenseClient(create_airflow_data_source)
+analysis = client.analyze("flowsense_demo")
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)
 ```
 
+Applications that own configuration can combine `AirflowConfig` with
+`create_airflow_data_source_factory`. Typed integrations may continue to call
+`client.execute(AnalysisRequest(...))`. See the complete
+[Python API guide](docs/python-api.md).
+
+Multiple DAGs can be analyzed with bounded, opt-in concurrency. Expected
+FlowSense failures are isolated per DAG:
+
+```python
+result = client.analyze_many(
+    ["orders", "payments", "inventory"],
+    max_concurrency=3,
+)
+```
+
+`AirflowClient.list_dag_ids()` provides paginated DAG discovery and excludes
+paused DAGs by default.
+
+`serialize_batch_analysis(result)` converts the result into the stable batch
+output contract without exposing raw exception objects.
+
 Analysis behavior can be customized with an immutable policy:
 
 ```python
@@ -305,6 +367,8 @@ policy = AnalysisPolicy(
     medium_threshold=2.5,
     high_threshold=4.0,
     critical_threshold=6.0,
+    minimum_relative_dispersion=0.01,
+    minimum_absolute_dispersion=0.001,
     mapped_task_aggregation=MappedTaskAggregation.MAX,
     change_point_minimum_segment_size=4,
     change_point_score_threshold=4.0,
@@ -317,6 +381,8 @@ policy = AnalysisPolicy(
 `baseline_window` limits the number of historical values used before the current
 run. Mapped task durations can be aggregated with `MAX`, `MEAN`, or `SUM`. The
 same policy options are available through the CLI and MCP tool.
+The dispersion floors prevent constant or nearly constant baselines from
+turning negligible timing noise into an automatic critical anomaly.
 Change-point and trend detection can also be disabled independently with
 `change_point_detection_enabled=False` or `trend_detection_enabled=False`.
 
@@ -351,6 +417,27 @@ The server exposes the `analyze_airflow_dag` tool, which returns task drift,
 handoff drift, impact classification, propagation paths, and primary root-cause
 information for a DAG.
 
+## Prometheus
+
+Run continuous analysis and expose the latest DAG and bounded task-level metrics:
+
+```bash
+flowsense serve-metrics example_dag \
+  --host 0.0.0.0 \
+  --port 9108 \
+  --history-run-limit 50 \
+  --policy-file flowsense-policy.json
+```
+
+See [docs/prometheus.md](docs/prometheus.md) for the metric contract,
+cardinality policy, and Prometheus scrape configuration.
+
+A provisioned Prometheus and Grafana development stack, including the
+`FlowSense Overview` dashboard, is documented in
+[docs/grafana.md](docs/grafana.md).
+Default operational alerts and Alertmanager routing are documented in
+[docs/alerting.md](docs/alerting.md).
+
 ## Development
 
 Run unit tests:

{flowsense_engine-0.3.0 → flowsense_engine-0.5.0}/README.md

@@ -2,10 +2,12 @@
 
 Temporal drift, anomaly detection, and dependency-aware propagation analysis for Apache Airflow.
 
-Current package release: `0.3.0`. See [CHANGELOG.md](CHANGELOG.md) for release
+Current package release: `0.5.0`. See [CHANGELOG.md](CHANGELOG.md) for release
 notes, [docs/architecture.md](docs/architecture.md) for the system architecture,
 [docs/benchmarks.md](docs/benchmarks.md) for performance measurement, and
-[docs/migrating-to-0.3.md](docs/migrating-to-0.3.md) for migration guidance.
+[docs/production-quickstart.md](docs/production-quickstart.md) for a production
+walkthrough. See [docs/migrating-to-0.5.md](docs/migrating-to-0.5.md) for the
+current migration guidance.
 Maintainers can use [docs/releasing.md](docs/releasing.md) as the release checklist.
 
 FlowSense analyzes historical DAG executions to identify abnormal task behavior and trace how anomalies propagate through downstream dependencies.
@@ -118,6 +120,9 @@ Once published on PyPI, install the distribution with:
 pip install flowsense-engine
 ```
 
+For an end-to-end Airflow setup, follow the
+[production quickstart](docs/production-quickstart.md).
+
 The distribution name is `flowsense-engine`; Python imports and CLI commands
 remain `flowsense`.
 
@@ -145,6 +150,7 @@ AIRFLOW_USERNAME=your_username
 AIRFLOW_PASSWORD=your_password
 AIRFLOW_API_VERSION=v2
 AIRFLOW_AUTH_MODE=token
+# AIRFLOW_BEARER_TOKEN=your_static_token
 AIRFLOW_CONNECT_TIMEOUT=10
 AIRFLOW_READ_TIMEOUT=10
 AIRFLOW_MAX_RETRIES=2
@@ -157,6 +163,12 @@ Stable REST API deployments. Airflow 3.x uses the `v2` API and typically uses
 token authentication. Authentication still depends on the API auth backend
 configured in the Airflow deployment.
 
+Static bearer tokens can use `AIRFLOW_AUTH_MODE=bearer` with
+`AIRFLOW_BEARER_TOKEN`; username and password are not required in that mode.
+Library integrations may inject a custom `AirflowAuthProvider` for rotating
+tokens, identity-aware proxies, or deployment-specific headers. See
+[docs/authentication.md](docs/authentication.md) for the complete contract.
+
 CI verifies both integrations through versioned Airflow 2 and Airflow 3 REST
 contract fixtures. These boundary tests cover authentication, endpoint routing,
 response validation, domain mapping, and the complete analysis use case.
@@ -176,9 +188,15 @@ export $(grep -v '^#' .env | xargs)
 Then run:
 
 ```bash
+flowsense doctor
+flowsense dags
 flowsense analyze <dag_id>
+flowsense analyze-batch <dag_id> [<dag_id> ...]
 ```
 
+Both single and batch analysis commands support `--fail-on` for CI severity
+gates.
+
 The CLI report includes a DAG summary and separate tables for task drift,
 handoff drift, change points, trends, propagation paths, and diagnostics.
 Results are ordered by severity or subject so repeated analyses remain easy to
@@ -188,14 +206,30 @@ For automation and CI/CD integrations, request the versioned JSON document:
 
 ```bash
 flowsense analyze <dag_id> --output json
+flowsense analyze <dag_id> --output-file flowsense-analysis.json
 ```
 
+`--output-file` always writes the versioned JSON contract and avoids relying on
+shell redirection in CI jobs.
+
 CI jobs can also fail when the analysis reaches a selected severity:
 
 ```bash
 flowsense analyze <dag_id> --output json --fail-on high
 ```
 
+Store reusable analysis settings in a versioned JSON policy file and share it
+between single and batch analysis:
+
+```bash
+flowsense analyze <dag_id> --policy-file flowsense-policy.json
+flowsense analyze-batch --all-dags --dag-limit 10 \
+  --policy-file flowsense-policy.json
+```
+
+Explicit policy options override values loaded from the file. Generate its JSON
+Schema with `flowsense schema --document policy`.
+
 `--fail-on` accepts `medium`, `high`, or `critical`. The report is always
 written before FlowSense exits: code `0` means the severity is below the
 threshold, code `2` means the threshold was reached, and code `1` remains
@@ -223,6 +257,8 @@ flowsense analyze <dag_id> --dag-run-id <dag_run_id>
 
 The MCP tool exposes the same option as `dag_run_id`. Analysis output includes
 `current_dag_run_id`; this field was introduced in output schema version `1.1`.
+Output schema version `1.2` adds drift `direction`, the regularized
+`effective_mad`, and the dispersion-floor policy values.
 
 The JSON document and MCP tool response share the same serialization contract
 and include a `schema_version` field. The serializer is also available from the
@@ -237,28 +273,53 @@ The same schema can be emitted without connecting to Airflow:
 
 ```bash
 flowsense schema > flowsense-analysis.schema.json
+flowsense schema --document batch > flowsense-batch.schema.json
 ```
 
+The default remains the single-DAG analysis schema. Use `--document batch` to
+emit the versioned batch envelope schema, including successful analyses and
+per-DAG failure records.
+
 This output is deterministic and can be used in CI contract checks, editor
 tooling, or client code generation.
 
 ## Library API
 
-FlowSense can also be used as a Python library through its supported top-level
-API:
+`FlowSenseClient` is the recommended in-process Python API. The environment
+configured Airflow factory keeps the basic setup concise:
 
 ```python
-from flowsense import AnalysisRequest, AnalyzeDAG
+from flowsense import FlowSenseClient
 from flowsense.infrastructure.airflow import create_airflow_data_source
 
-analysis = AnalyzeDAG(create_airflow_data_source).execute(
-    AnalysisRequest(dag_id="flowsense_demo")
-)
+client = FlowSenseClient(create_airflow_data_source)
+analysis = client.analyze("flowsense_demo")
 
 print(analysis.overall_severity)
 print(analysis.primary_origin)
 ```
 
+Applications that own configuration can combine `AirflowConfig` with
+`create_airflow_data_source_factory`. Typed integrations may continue to call
+`client.execute(AnalysisRequest(...))`. See the complete
+[Python API guide](docs/python-api.md).
+
+Multiple DAGs can be analyzed with bounded, opt-in concurrency. Expected
+FlowSense failures are isolated per DAG:
+
+```python
+result = client.analyze_many(
+    ["orders", "payments", "inventory"],
+    max_concurrency=3,
+)
+```
+
+`AirflowClient.list_dag_ids()` provides paginated DAG discovery and excludes
+paused DAGs by default.
+
+`serialize_batch_analysis(result)` converts the result into the stable batch
+output contract without exposing raw exception objects.
+
 Analysis behavior can be customized with an immutable policy:
 
 ```python
@@ -270,6 +331,8 @@ policy = AnalysisPolicy(
     medium_threshold=2.5,
     high_threshold=4.0,
     critical_threshold=6.0,
+    minimum_relative_dispersion=0.01,
+    minimum_absolute_dispersion=0.001,
     mapped_task_aggregation=MappedTaskAggregation.MAX,
     change_point_minimum_segment_size=4,
     change_point_score_threshold=4.0,
@@ -282,6 +345,8 @@ policy = AnalysisPolicy(
 `baseline_window` limits the number of historical values used before the current
 run. Mapped task durations can be aggregated with `MAX`, `MEAN`, or `SUM`. The
 same policy options are available through the CLI and MCP tool.
+The dispersion floors prevent constant or nearly constant baselines from
+turning negligible timing noise into an automatic critical anomaly.
 Change-point and trend detection can also be disabled independently with
 `change_point_detection_enabled=False` or `trend_detection_enabled=False`.
 
@@ -316,6 +381,27 @@ The server exposes the `analyze_airflow_dag` tool, which returns task drift,
 handoff drift, impact classification, propagation paths, and primary root-cause
 information for a DAG.
 
+## Prometheus
+
+Run continuous analysis and expose the latest DAG and bounded task-level metrics:
+
+```bash
+flowsense serve-metrics example_dag \
+  --host 0.0.0.0 \
+  --port 9108 \
+  --history-run-limit 50 \
+  --policy-file flowsense-policy.json
+```
+
+See [docs/prometheus.md](docs/prometheus.md) for the metric contract,
+cardinality policy, and Prometheus scrape configuration.
+
+A provisioned Prometheus and Grafana development stack, including the
+`FlowSense Overview` dashboard, is documented in
+[docs/grafana.md](docs/grafana.md).
+Default operational alerts and Alertmanager routing are documented in
+[docs/alerting.md](docs/alerting.md).
+
 ## Development
 
 Run unit tests:

flowsense_engine-0.5.0/docs/alerting.md

@@ -0,0 +1,57 @@
+# Prometheus alerting
+
+The local observability stack loads a tested set of FlowSense alert rules and
+routes firing alerts to Alertmanager.
+
+## Included alerts
+
+| Alert | Default condition | Severity |
+| --- | --- | --- |
+| `FlowSenseExporterDown` | Metrics endpoint unavailable for 2 minutes | Critical |
+| `FlowSenseAnalysisFailed` | Latest analysis failed for 2 minutes | Warning |
+| `FlowSenseAnalysisStale` | No successful analysis for 10 minutes in total | Warning |
+| `FlowSenseCriticalDAG` | DAG severity remains critical for 2 minutes | Critical |
+| `FlowSenseCriticalTask` | Task severity remains critical for 2 minutes | Critical |
+| `FlowSenseTaskMetricsDropped` | Cardinality limit omits tasks for 5 minutes | Warning |
+| `FlowSenseAnalysisSlow` | Analysis remains above 30 seconds for 5 minutes | Warning |
+
+The stale rule expression becomes true after five minutes without a successful
+analysis and must remain true for another five minutes before firing. Adjust
+thresholds in `deploy/observability/alerts.yml` to match the configured analysis
+interval and operational expectations.
+
+## Validate rules
+
+Run syntax and unit checks with the Prometheus image pinned by the Compose file:
+
+```bash
+docker run --rm \
+  --entrypoint promtool \
+  -v "$PWD/deploy/observability:/workspace:ro" \
+  -w /workspace \
+  prom/prometheus:v3.14.0 \
+  check rules alerts.yml
+
+docker run --rm \
+  --entrypoint promtool \
+  -v "$PWD/deploy/observability:/workspace:ro" \
+  -w /workspace \
+  prom/prometheus:v3.14.0 \
+  test rules alerts.test.yml
+```
+
+## Configure notifications
+
+The committed Alertmanager configuration intentionally uses an empty local
+receiver. Firing alerts are visible in the Alertmanager UI and the Grafana
+dashboard, but no external notification is sent by default.
+
+For production, replace the receiver in
+`deploy/observability/alertmanager.yml` with the organization's managed email,
+Slack, PagerDuty, webhook, or other supported integration. Keep credentials out
+of Git and inject them through the deployment platform's secret management
+mechanism.
+
+Alertmanager is available locally at `http://localhost:9093`. Verify routing and
+notification delivery in a non-production environment before enabling it for
+operational incidents.