provide-telemetry 0.2.2

Unified telemetry library for the provide.io ecosystem — structured logging, distributed tracing, and metrics

Provide 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 provide-telemetry              # core (structlog)
pip install "provide-telemetry[otel]"      # + OpenTelemetry export

TypeScript:

npm install @provide-io/telemetry             # core (pino + @opentelemetry/api)

Quick Start

Python:

from provide.telemetry import setup_telemetry, shutdown_telemetry, get_logger, event

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

TypeScript:

import { setupTelemetry, getLogger, shutdownTelemetry } from '@provide-io/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
PROVIDE_TELEMETRY_SERVICE_NAME	provide-service	Service identity
PROVIDE_LOG_LEVEL	INFO	Log level
PROVIDE_LOG_FORMAT	console	Renderer: console, json, or pretty
PROVIDE_TELEMETRY_ENV	dev	Deployment environment
PROVIDE_TELEMETRY_VERSION	0.0.0	Service version
PROVIDE_TRACE_ENABLED	true	Enable OTel tracing
PROVIDE_METRICS_ENABLED	true	Enable OTel metrics

See the Configuration Reference for all 60+ environment variables.

Event Naming

Event names follow the DA(R)S pattern — Domain, Action, (Resource), Status — as 3 or 4 dot-separated lowercase segments. event() returns a structured Event (a str subclass with .domain, .action, .resource, and .status fields):

# Python
log.info("auth.login.success", user_id="u-123")
log.info(event("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(), replace_pii_rules(), get_pii_rules()
Health	get_health_snapshot()
Runtime	update_runtime_config(), reconfigure_telemetry(), reload_runtime_from_env()

Full reference: Python API | TypeScript API

Polyglot Architecture

provide-telemetry/
  src/provide/telemetry/    # Python package
  typescript/             # TypeScript package (@provide-io/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/.