Metadata-Version: 2.5
Name: 3tears-observe
Version: 0.74.0
Summary: Structured logging, tracing, and OpenTelemetry setup for 3tears applications
Project-URL: Repository, https://github.com/pacepace/3tears
Author: pace
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.14
Provides-Extra: asgi
Requires-Dist: uuid-utils; extra == 'asgi'
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2,>=1.40; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.40; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.40; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation-logging<1,>=0.61b0; extra == 'otel'
Requires-Dist: opentelemetry-instrumentation<1,>=0.61b0; extra == 'otel'
Requires-Dist: opentelemetry-sdk<2,>=1.40; extra == 'otel'
Provides-Extra: otel-http
Requires-Dist: opentelemetry-api<2,>=1.40; extra == 'otel-http'
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.40; extra == 'otel-http'
Requires-Dist: opentelemetry-instrumentation-logging<1,>=0.61b0; extra == 'otel-http'
Requires-Dist: opentelemetry-instrumentation<1,>=0.61b0; extra == 'otel-http'
Requires-Dist: opentelemetry-sdk<2,>=1.40; extra == 'otel-http'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
Description-Content-Type: text/markdown

# 3tears-observe

Structured logging, tracing, and OpenTelemetry setup for 3tears applications.

## Modules

- `threetears.observe.logging` -- Structured logging with context correlation and automatic call-site capture.
- `threetears.observe.tracing` -- `@traced` decorator (zero-cost without OpenTelemetry).
- `threetears.observe.metrics` -- `counter`/`histogram`/`gauge` get-or-create accessors plus the `@metered` decorator built on them, records prometheus metrics (zero-cost without prometheus_client).
- `threetears.observe.setup` -- OpenTelemetry SDK bootstrap (TracerProvider, LoggerProvider, OTLP exporters).

## Installation

```bash
pip install 3tears-observe

# With OpenTelemetry SDK support, traces over OTLP/gRPC:
pip install 3tears-observe[otel]

# The same over OTLP/HTTP, with no gRPC installed (about 10 MB against about 49):
pip install 3tears-observe[otel-http]
```

With `otel-http`, set `TelemetryConfig(protocol="http/protobuf", endpoint="http://collector:4318")`;
spans go to `<endpoint>/v1/traces`. `protocol` defaults to `"grpc"`, which needs the `otel` extra.
Log export is OTLP/HTTP under either extra.
