provide-telemetry 0.4.4

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, TypeScript, Go, and Rust. Graceful OTel degradation — works without OpenTelemetry installed, activates full OTLP export (traces, metrics, logs) when the OTel SDK is present. Rust requires the otel cargo feature (cargo build --features otel).

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)

Rust:

cargo add provide-telemetry
cargo add provide-telemetry --features otel

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,
  getConfig,
  getLogger,
  registerOtelProviders,
  shutdownTelemetry,
} from '@provide-io/telemetry';

setupTelemetry({ serviceName: 'my-app' });
// Required to actually export to an OTLP collector — setupTelemetry alone
// configures policies but does not register SDK providers.
await registerOtelProviders(getConfig());

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

All implementations share the same API surface, event naming conventions, and configuration environment variables. The Rust crate lives in rust/ and uses guard-based context binding for task-safe restoration.

On wire-format parity: the JSON shape emitted by each language is semantically equivalent but not byte-identical. Go follows OpenTelemetry semantic conventions for its standard fields (service.name, service.env, service.version, trace.id, span.id); Python, TypeScript, and Rust use snake_case (service, env, version, trace_id, span_id). The cross-language parity harness in spec/ normalises these key forms before comparing outputs (see _FIELD_RENAMES in spec/parity_probe_support.py), so semantic equivalence is what's tested and guaranteed — not literal wire-format identity. Consumers parsing logs across languages should normalize to whichever convention they prefer.

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

All implementations export equivalent APIs (signatures vary per language idiom):

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	get_runtime_config(), get_runtime_status(), update_runtime_config(), reconfigure_telemetry(), reload_runtime_from_env()

Full reference: Python API | TypeScript API | Go API | Rust crate

Polyglot Architecture

provide-telemetry/
  src/provide/telemetry/    # Python package
  typescript/             # TypeScript package (@provide-io/telemetry)
  go/                     # Go module (github.com/provide-io/provide-telemetry/go)
  rust/                   # Rust crate (provide-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 Python, TypeScript, Go, and Rust exports conform to it. Cross-language distributed tracing is tested end-to-end via W3C traceparent propagation.

Quality

• Coverage gates: Python and TypeScript branch coverage; Go statement coverage for the root, logger, tracer, and otel packages; Rust crate verified with cargo test
• Python runs mutmut with a 95.90% current score / 95% minimum threshold; Go requires 100% gremlins efficacy; TypeScript runs Stryker with a 96.07% current score / 95% break threshold (the re-export barrel index.ts is excluded at the config level; remaining survivors are concentrated in config/runtime/pretty/propagation edge cases); Rust nightly mutation sweep is advisory (current baseline is re-verified manually; see rust/README.md)
• Strict type checking (mypy + ty + tsc)
• CodeQL SAST scanning
• SHA-pinned third-party GitHub Actions
• Sigstore artifact signing
• CycloneDX SBOM on releases

Documentation

• Configuration Reference — all environment variables
• API Reference — shared semantic contract and Python-centered examples
• Capability Matrix — core guarantees vs feature-gated or idiomatic differences
• Architecture — component design and data flow
• Developer Experience Rubric — criteria for cross-language consistency and usability
• Internals — implementation details
• Conventions — event naming and schema rules
• Operations Runbook — troubleshooting and CQ matrix
• Polyglot Parity Roadmap — prioritized work to reach true behavioral parity
• Production Profiles — recommended configs
• Release Runbook — versioning and publishing
• TypeScript README — TypeScript-specific docs
• Go README — Go-specific docs
• Rust crate — Rust-specific source and examples
• Examples — runnable examples for the polyglot repo

License

Apache-2.0. See LICENSES/.