undef-telemetry 0.3.18

Unified telemetry library for the Undef ecosystem

undef-telemetry

Unified telemetry package for the Undef ecosystem.

Install

pip install undef-telemetry

Optional extras:

pip install "undef-telemetry[otel]"

API

from undef.telemetry import (
    setup_telemetry,
    get_logger, logger,
    trace, tracer, get_tracer,
    counter, gauge, histogram, get_meter,
    TelemetryMiddleware,
)

Runtime Config API

• update_runtime_config(config) applies a config and returns the active runtime snapshot.
• reload_runtime_from_env() reloads env config, applies it, and returns the active runtime snapshot.
• get_runtime_config() returns a defensive copy of the active runtime snapshot.
• reconfigure_telemetry(config) only applies hot runtime policy changes in-process; provider-changing OpenTelemetry reconfiguration requires a process restart once providers have been installed.

Quick Start

from undef.telemetry import setup_telemetry, shutdown_telemetry, get_logger

setup_telemetry()
log = get_logger(__name__)
log.info("app.start.ok", request_id="req-1")
shutdown_telemetry()

Environment Variables

The most commonly set variables:

• UNDEF_TELEMETRY_SERVICE_NAME — service identity (default: undef-service)
• UNDEF_LOG_LEVEL — log level (default: INFO)
• UNDEF_LOG_FORMAT — renderer: console, json, or pretty (default: console)

See the Configuration Reference for all 60+ environment variables with types and defaults.

Event Naming Rule

Event names are strict: 3-5 dot-separated segments (last segment is status by convention). If you build names dynamically, use undef.telemetry.event_name(*segments).

from undef.telemetry import event_name, get_logger

log = get_logger(__name__)
log.info(event_name("auth", "login", "success"), user_id="u-123")
log.info(event_name("auth", "login", "failed"), reason="bad_password")

OpenObserve Quick Verification

export OPENOBSERVE_URL=http://localhost:5080/api/default
export OPENOBSERVE_USER=[e-mail]
export OPENOBSERVE_PASSWORD=password
export OPENOBSERVE_REQUIRED_SIGNALS=logs
uv run --group dev --extra otel python examples/openobserve/01_emit_all_signals.py
uv run --group dev --extra otel python examples/openobserve/02_verify_ingestion.py

Set OPENOBSERVE_REQUIRED_SIGNALS=logs,metrics,traces when your runtime has OTel extras and you want hard all-signal verification.

Script references:

• Emit all signals example
• Verify ingestion example

Quality Guarantees

• Baseline test gate runs at 100% branch coverage (--cov-branch).
• Mutation gate enforces --min-mutation-score 100.
• Mutation policy is pinned in .ci/pymutant-profiles.json (min_score: 1.0, max_drop_from_baseline: 0.0) with baseline score in .ci/pymutant-policy-baseline.json.
• CI validates linting, typing, security, compliance, examples, and integration slices.
• Async-safe default exporter policy keeps retries/backoff at zero; non-zero async retry behavior is opt-in via UNDEF_EXPORTER_*_ALLOW_BLOCKING_EVENT_LOOP=true.
• Exporter timeout settings are enforced both in OTLP exporter construction and per-attempt resilience execution bounds.

Documentation Ownership

• README: onboarding and first successful local/backend verification.
• Operations: full CQ matrix, troubleshooting, and environment operations.
• Conventions: event/schema rules and naming standards.
• Release: packaging/tagging/publishing workflow.

Docs

• Configuration Reference
• API Reference
• Internals
• Operations Runbook
• Production Profiles
• Architecture
• Telemetry Conventions
• Compliance Notes
• Release Runbook
• Examples
• Main CI Workflow
• Release Workflow