elven-opentelemetry-instrumentation-py 0.1.2

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

Kubernetes Operator

Build the Python auto-instrumentation image expected by the OpenTelemetry Operator:

docker build -f Dockerfile.operator -t your-registry/elven-opentelemetry-instrumentation-py:0.1.2 .

Use that image in the Instrumentation resource:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: instrumentation
spec:
  exporter:
    endpoint: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318"
  propagators:
    - tracecontext
    - baggage
    - b3
    - b3multi
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  python:
    image: docker.io/elvenobservability/python-k8s-operator:latest
    env:
      - name: OTEL_PYTHON_DISTRO
        value: "elven"
      - name: OTEL_PYTHON_CONFIGURATOR
        value: "elven"
      - name: OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION
        value: "false"
      - name: OTEL_LOGS_EXPORTER
        value: "none"
      - name: OTEL_EXPORTER_OTLP_PROTOCOL
        value: "http/protobuf"
      - name: OTEL_METRICS_EXPORTER
        value: "otlp"
      - name: OTEL_TRACES_EXPORTER
        value: "otlp"
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318"

This image ships both /autoinstrumentation and /autoinstrumentation-musl, sets OTEL_PYTHON_DISTRO=elven, sets OTEL_PYTHON_CONFIGURATOR=elven, and keeps logs export disabled by default to match the package contract.

If you prefer split endpoints, keep the same http/protobuf protocol and point both variables to the collector HTTP port:

- name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318/v1/traces"
- name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
  value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318/v1/metrics"

For Alpine-based workloads, add:

metadata:
  annotations:
    instrumentation.opentelemetry.io/otel-python-platform: "musl"

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