Overview

package wittgenstein_observability

Wittgenstein Observability Library.

Combines OpenTelemetry tracking, Langfuse tracking, and JSON Line file logging.

Classes

JsonLineFormatter — Formats LogRecord as a single line JSON ready for ingestion / jq.

Functions

setup_telemetry — Configure OTel — alias for configure_opentelemetry(), kept for backward compat.
instrument_app — Instrument a FastAPI instance with OpenTelemetry.
configure_opentelemetry — Configure OpenTelemetry SDK with multi-exporter factory.
get_tracer — Get a tracer for creating spans.
get_meter — Get a meter for creating metrics.
shutdown_opentelemetry — Shutdown OpenTelemetry providers gracefully.
is_otel_enabled — Check if OpenTelemetry is enabled.
get_otel_endpoint — Get the OTEL collector endpoint.
trace_llm_request — Decorator to trace LLM requests with OpenTelemetry.
trace_method — Decorator that wraps any service method in an OTel span.
configure_event_file_handler — Attaches a TimedRotatingFileHandler to the structured events logger.
is_langfuse_enabled — Check if Langfuse is configured and active via env vars.
get_langfuse_client — Retrieve or initialize the global Langfuse client instance.
observe_langfuse_trace — Decorator to automatically trace a function execution to Langfuse.

wittgenstein_observability.setup_telemetry

mkapi_definition_mkapi setup_telemetry(service_name: str = 'agent-platform') → bool

Configure OTel — alias for configure_opentelemetry(), kept for backward compat.

Pre-ADR-092 callers used ENABLE_OTEL=true/OTEL_EXPORTER_OTLP_ENDPOINT and got OTLP-traces-only. Both env vars still work: ENABLE_OTEL_TRACING is the equivalent enable-flag consulted by is_otel_enabled(), and OTEL_EXPORTER_OTLP_ENDPOINT is still read by get_otel_endpoint(). Also runs pydantic-ai and SQLAlchemy auto-instrumentation, matching this function's original behavior.

wittgenstein_observability.instrument_app

mkapi_definition_mkapi instrument_app(app: Any) → None

Instrument a FastAPI instance with OpenTelemetry.

Pre-existing lib capability (not present in the backend's own otel_config.py, which relied on the consuming app calling FastAPIInstrumentor directly) — kept as-is. Checks both this lib's original enable flag (ENABLE_OTEL) and the ported one (OTEL_EXPORTERS/ENABLE_OTEL_TRACING, via is_otel_enabled()) so pre-ADR-092 standalone consumers that only ever set ENABLE_OTEL keep working unchanged.

wittgenstein_observability.configure_opentelemetry

mkapi_definition_mkapi configure_opentelemetry(service_name: str = 'wittgenstein-core-backend') → bool

Configure OpenTelemetry SDK with multi-exporter factory.

Supports additive exporter selection via OTEL_EXPORTERS env var. Each exporter is configured for traces, metrics, and logs where applicable.

Parameters

service_name : str — Name of the service for tracing

Returns

bool — True if configuration was successful, False otherwise

wittgenstein_observability.get_tracer

mkapi_definition_mkapi get_tracer(name: str = 'wittgenstein-core')

Get a tracer for creating spans.

Parameters

name : str — Name of the tracer (typically module name)

Returns

Tracer object or NoOp tracer if OTEL is disabled

wittgenstein_observability.get_meter

mkapi_definition_mkapi get_meter(name: str = 'wittgenstein-core')

Get a meter for creating metrics.

Parameters

name : str — Name of the meter

Returns

Meter object or None if OTEL is disabled

wittgenstein_observability.shutdown_opentelemetry

mkapi_definition_mkapi shutdown_opentelemetry()

Shutdown OpenTelemetry providers gracefully.

wittgenstein_observability.is_otel_enabled

mkapi_definition_mkapi is_otel_enabled() → bool

Check if OpenTelemetry is enabled.

Returns True if EITHER

OTEL_EXPORTERS is non-empty, OR
ENABLE_OTEL_TRACING=true (legacy, backward compat)

wittgenstein_observability.get_otel_endpoint

mkapi_definition_mkapi get_otel_endpoint() → str

Get the OTEL collector endpoint.

wittgenstein_observability.trace_llm_request

mkapi_definition_mkapi trace_llm_request(func)

Decorator to trace LLM requests with OpenTelemetry.

Adds spans for LLM API calls with relevant attributes. Works alongside Langfuse for LLM-specific observability.

wittgenstein_observability.trace_method

mkapi_definition_mkapi trace_method(span_name: Optional[str] = None, component: str = 'service')

Decorator that wraps any service method in an OTel span.

Works with both sync and async methods. A no-op when OTel is not enabled.

Usage

@trace_method() async def ingest(self, doc): ...

@trace_method("embedding.encode", component="embedding") def encode(self, text): ...

wittgenstein_observability.JsonLineFormatter

mkapi_definition_mkapi class JsonLineFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases : logging.Formatter

Formats LogRecord as a single line JSON ready for ingestion / jq.

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of '%', '{' or '$' to specify that you want to use one of %-formatting, :meth:str.format ({}) formatting or :class:string.Template formatting in your format string.

.. versionchanged:: 3.2 Added the style parameter.

Methods