Metadata-Version: 2.5
Name: alytricality-airflow
Version: 0.1.0
Summary: Airflow task-instance tracing plugin for alytricality
Project-URL: Repository, https://github.com/seismiq-ai/alytricality
Project-URL: Issues, https://github.com/seismiq-ai/alytricality/issues
Author: Seismiq AI
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Apache Airflow
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: alytricality==0.1.0
Description-Content-Type: text/markdown

# alytricality-airflow

Airflow task-instance tracing for [`alytricality`](https://pypi.org/project/alytricality/),
the opinionated OpenTelemetry tracing distro for data pipelines. It registers an
Airflow listener that opens one span per task instance and links it to the trace
that triggered the DAG run, so a pipeline reads as a single trace from its
upstream trigger through every task.

> **Pre-launch naming.** `alytricality-airflow` is a placeholder distribution
> name. The project will be republished under its real brand at launch; the
> import package and the plugin entry-point name change with it.

## Install

```sh
pip install alytricality-airflow
```

There is nothing to import and no file to copy into `plugins/`. The package
ships an `airflow.plugins` entry point, so installing it next to Airflow — in
the same environment as the scheduler and workers — is the entire installation.
On Composer, add `alytricality[gcp]` and `alytricality-airflow` to
`pypi_packages`; in a custom image, install the same two lines.

`apache-airflow` is a peer dependency supplied by the runtime and is
deliberately not pinned here. `alytricality` is pinned exactly: the two
distributions release in lockstep.

## Configure

Configuration is the core package's standard `OTEL_*` environment, set on the
scheduler and workers:

```sh
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
OTEL_SERVICE_NAME=airflow
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod
```

The listener applies two `setdefault`s of its own before its first hook —
`OTEL_SERVICE_NAME=airflow` and `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=flask`
(the Airflow webserver is Flask; its health-check spans are noise). A value you
set always wins.

## Behavior

- One span per task instance, keyed by `(dag_id, run_id, task_id, map_index)`,
  named after the bare `task_id` so mapped instances aggregate.
- Trace linkage from `ti.context_carrier` (native AIP-49) or a `traceparent` in
  the DAG run's `conf` — a link, not a remote parent, since the trigger and the
  DAG run are independently rooted.
- Task attributes under `airflow.task.*`; terminal state set at span end.
- Failures captured on the span *and* written to stderr, so a traceback survives
  pod teardown under the KubernetesExecutor.
- Defers entirely to an existing tracer provider (e.g. Airflow-native
  `otel_on=True`) — never fights another owner for the global provider.
- Bounded flush per task; a telemetry failure never fails the task.

## Supported window

Python 3.10–3.13, Airflow 2.9+ and 3.x (2.9, 2.11, 3.1, and 3.2 covered in CI),
OpenTelemetry SDK 1.27–1.44.

## License

Apache-2.0.
