elven-opentelemetry-instrumentation-py 0.1.0

Universal OpenTelemetry bootstrap for Python services with elite-quality defaults, privacy, auto-instrumentation, traces, and metrics.

OpenTelemetry Instrumentation Python (v1)

Python-first OpenTelemetry bootstrap for backend services, focused on:

• deterministic startup and shutdown
• explicit feature toggles for tracing, metrics and instrumentations
• strict privacy defaults for database statements and user identifiers
• zero-code startup through the official distro/configurator mechanism
• log correlation only, with no log export pipeline inside this package

Installation

pip install "elven-opentelemetry-instrumentation-py[full]"

Runtime support

v1 supports runtime="python" only.

Passing runtime="serverless" or runtime="edge" raises an explicit error.

Zero-code

export OTEL_SERVICE_NAME="my-service"
export OTEL_SERVICE_VERSION="1.0.0"
elven-otel-instrument python app.py

Disable wrapper initialization explicitly:

export OTEL_ZERO_CODE=false

Manual initialization

from opentelemetry.sdk.trace.sampling import Decision

from elven_opentelemetry_instrumentation import (
    MetricsConfig,
    ObservabilityConfig,
    PrivacyConfig,
    SamplingRule,
    ServiceConfig,
    TracingConfig,
    init_observability,
)

handle = init_observability(
    ObservabilityConfig(
        service=ServiceConfig(
            service_name="payment-service",
            service_version="1.0.0",
            deployment_environment="production",
        ),
        tracing=TracingConfig(
            enabled=True,
            rules=[
                SamplingRule(
                    attribute_key="http.route",
                    attribute_value="/healthz",
                    decision=Decision.DROP,
                ),
            ],
        ),
        metrics=MetricsConfig(enabled=True, export_interval_millis=60_000),
        privacy=PrivacyConfig(
            redact_db_statement=True,
            hash_user_id=True,
        ),
    )
)

handle.tracer.with_span("startup", lambda span: span.set_attribute("boot.ready", True))
handle.metrics.increment("jobs.started", 1)
handle.force_flush()
handle.shutdown()

Public API

init_observability(config) returns an ObservabilityHandle with:

• tracer
• metrics
• shutdown()
• force_flush()
• is_started()

The initializer is idempotent and protects against duplicate startup.

Feature precedence

For booleans, precedence is:

1. explicit config
2. environment variable
3. package default

Examples:

• OTEL_TRACES_EXPORTER=none disables traces by default
• TracingConfig(enabled=True) overrides that default
• OTEL_INSTR_PSYCOPG=false disables psycopg instrumentation unless explicitly enabled in config

Supported coverage

• Web: ASGI, WSGI, FastAPI, Flask, Django
• GraphQL: request-level enrichment plus operation and field spans through graphql-core
• HTTP clients: requests, httpx, urllib3, aiohttp-client
• Data: SQLAlchemy, psycopg, psycopg2, pymysql, mysqlclient, Redis, MongoDB
• Workers and queues: Celery, threading, asyncio, gRPC, Kafka, RabbitMQ/Pika, SQS via boto3
• Logging: stdlib logging correlation

Instrumentation is activated only when the target library is installed and enabled.

Development

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pyright
pytest