Metadata-Version: 2.5
Name: alytricality
Version: 0.1.0
Summary: Opinionated OpenTelemetry tracing distro for data pipelines
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: 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: opentelemetry-api<2,>=1.27
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27
Requires-Dist: opentelemetry-instrumentation-grpc<0.66b0,>=0.48b0
Requires-Dist: opentelemetry-instrumentation-psycopg2<0.66b0,>=0.48b0
Requires-Dist: opentelemetry-instrumentation-requests<0.66b0,>=0.48b0
Requires-Dist: opentelemetry-instrumentation-urllib3<0.66b0,>=0.48b0
Requires-Dist: opentelemetry-sdk<2,>=1.27
Provides-Extra: all
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == 'all'
Requires-Dist: opentelemetry-resourcedetector-gcp>=1.6; extra == 'all'
Provides-Extra: gcp
Requires-Dist: opentelemetry-resourcedetector-gcp>=1.6; extra == 'gcp'
Provides-Extra: grpc
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.27; extra == 'grpc'
Description-Content-Type: text/markdown

# alytricality

An opinionated OpenTelemetry tracing distro for data pipelines. One decorator
assembles the whole SDK — resource detection, OTLP export, bundled
instrumentors, W3C context propagation, bounded flush on exit — from standard
`OTEL_*` environment variables, and never breaks the workload: any telemetry
failure degrades to no telemetry, loudly logged, never raised.

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

## Install

```sh
pip install alytricality
```

Extras: `alytricality[gcp]` adds the official GCP resource detector,
`alytricality[grpc]` the OTLP/gRPC exporter, `alytricality[all]` both.

## Use

```python
from alytricality import traced


@traced
def handler(event): ...
```

`@traced` marks the **process entry point** and always produces a SERVER root
span named after the function: it records exceptions, links any inbound trace
context found in the first argument, and performs a bounded `force_flush` on
exit. Applying it a second time to the same function is a no-op, so root spans
never stack. For notebooks, REPLs, and scripts with no function to decorate,
call `init()` instead — the same idempotent assembly, which returns the process
runtime and never raises.

Everything you do *inside* a trace is native `opentelemetry-api`:

```python
from opentelemetry import trace

trace.get_current_span().set_attribute("rows.loaded", 1042)
```

## Configuration

Standard OTel environment variables only — there are no config kwargs and no
package-specific vars, and the package never writes to the environment.

| Variable | Role |
| --- | --- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Required; there is no baked-in default |
| `OTEL_SERVICE_NAME` | Service identity |
| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` selects the gRPC exporter; otherwise HTTP/protobuf |
| `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` | Opt out of bundled instrumentors |
| `OTEL_SDK_DISABLED` | `true` turns everything into a no-op |

Export is always OTLP. `requests`, `urllib3`, `psycopg2`, and `grpc`
instrumentation is bundled and applied automatically; an instrumentor whose
target library isn't installed is skipped quietly.

## Supported window

Python 3.10–3.13, OpenTelemetry SDK 1.27–1.44 (min and max both tested in CI).
`opentelemetry-instrumentation-*` releases are pinned to the matched set for
each SDK window, so consumers don't hand-curate OTel version lines.

## License

Apache-2.0.
