undef-telemetry 0.4.0

Unified telemetry library for the Undef ecosystem

Undef Telemetry

Unified telemetry library for structured logging, distributed tracing, and metrics across Python and TypeScript. Graceful OTel degradation — works without OpenTelemetry installed, activates full export when OTel SDK is present.

Install

Python:

pip install undef-telemetry              # core (structlog)
pip install "undef-telemetry[otel]"      # + OpenTelemetry export

TypeScript:

npm install @undef-games/telemetry             # core (pino + @opentelemetry/api)

Quick Start

Python:

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()

TypeScript:

import { setupTelemetry, getLogger, shutdownTelemetry } from '@undef-games/telemetry';

setupTelemetry({ serviceName: 'my-app' });
const log = getLogger('api');
log.info({ event: 'app.start.ok', requestId: 'req-1' });
await shutdownTelemetry();

Both languages share the same API surface, event naming conventions, and configuration environment variables.

Configuration

All runtime config is via environment variables:

Variable	Default	Description
UNDEF_TELEMETRY_SERVICE_NAME	undef-service	Service identity
UNDEF_LOG_LEVEL	INFO	Log level
UNDEF_LOG_FORMAT	console	Renderer: console, json, or pretty
UNDEF_TRACE_ENABLED	false	Enable OTel tracing
UNDEF_METRICS_ENABLED	false	Enable OTel metrics

See the Configuration Reference for all 60+ environment variables.

Event Naming

Event names use 3-5 dot-separated lowercase segments:

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

// TypeScript
log.info({ event: 'auth.login.success', userId: 'u-123' });

See Conventions for full naming rules.

API Surface

Both languages export equivalent APIs:

Category	Functions
Lifecycle	setup_telemetry(), shutdown_telemetry()
Logging	get_logger(), bind_context(), clear_context()
Tracing	get_tracer(), trace (decorator/wrapper), extract_w3c_context()
Metrics	counter(), gauge(), histogram()
Policies	set_sampling_policy(), set_queue_policy(), set_exporter_policy()
Safety	register_cardinality_limit(), register_pii_rule()
Health	get_health_snapshot()
Runtime	update_runtime_config(), reconfigure_telemetry()

Full reference: Python API | TypeScript API

Polyglot Architecture

undef-telemetry/
  src/undef/telemetry/    # Python package
  typescript/             # TypeScript package (@undef-games/telemetry)
  spec/                   # Canonical API spec — all languages validate against it
  e2e/                    # Cross-language E2E tests (W3C trace propagation)

A shared spec/telemetry-api.yaml defines the required API surface. CI validates that both Python and TypeScript exports conform to it. Cross-language distributed tracing is tested end-to-end via W3C traceparent propagation.

Quality

• 100% branch coverage (Python + TypeScript)
• 100% mutation kill score (mutmut + Stryker)
• Strict type checking (mypy + ty + tsc)
• CodeQL SAST scanning
• SHA-pinned GitHub Actions
• Sigstore artifact signing
• CycloneDX SBOM on releases

Documentation

• Configuration Reference — all environment variables
• API Reference — Python function signatures and examples
• Architecture — component design and data flow
• Internals — implementation details
• Conventions — event naming and schema rules
• Operations Runbook — troubleshooting and CQ matrix
• Production Profiles — recommended configs
• Release Runbook — versioning and publishing
• TypeScript README — TypeScript-specific docs
• Examples — Python and TypeScript examples

License

Apache-2.0. See LICENSES/.