rococo 1.3.1__tar.gz → 1.3.3__tar.gz

{rococo-1.3.1 → rococo-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rococo
-Version: 1.3.1
+Version: 1.3.3
 Summary: A Python library to help build things the way we want them built
 Home-page: https://github.com/EcorRouge/rococo
 Author: Jay Grieves
@@ -39,6 +39,35 @@ Requires-Dist: PyMySQL<1.2,>=1.1.1; extra == "data"
 Requires-Dist: PyMongo<5.0,>=4.6.3; extra == "data"
 Requires-Dist: psycopg2-binary<3.0,>=2.9.10; extra == "data"
 Requires-Dist: pynamodb<7.0,>=6.0.0; extra == "data"
+Provides-Extra: observability
+Requires-Dist: requests<3.0,>=2.31.0; extra == "observability"
+Requires-Dist: opentelemetry-api<2.0,>=1.24; extra == "observability"
+Provides-Extra: observability-tracing-core
+Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "observability-tracing-core"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.24; extra == "observability-tracing-core"
+Provides-Extra: observability-flask-tracing
+Requires-Dist: opentelemetry-instrumentation-flask<1.0,>=0.45b0; extra == "observability-flask-tracing"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "observability-flask-tracing"
+Requires-Dist: Werkzeug<4.0,>=2.0; extra == "observability-flask-tracing"
+Provides-Extra: observability-fastapi-tracing
+Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.45b0; extra == "observability-fastapi-tracing"
+Requires-Dist: opentelemetry-instrumentation-httpx<1.0,>=0.45b0; extra == "observability-fastapi-tracing"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "observability-fastapi-tracing"
+Provides-Extra: observability-postgres-tracing
+Requires-Dist: opentelemetry-instrumentation-psycopg2<1.0,>=0.45b0; extra == "observability-postgres-tracing"
+Provides-Extra: observability-langgraph-tracing
+Requires-Dist: openinference-instrumentation-langchain<0.2.0,>=0.1.67; python_version < "3.15" and extra == "observability-langgraph-tracing"
+Provides-Extra: observability-tracing
+Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "observability-tracing"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.24; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-flask<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: Werkzeug<4.0,>=2.0; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-httpx<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: opentelemetry-instrumentation-psycopg2<1.0,>=0.45b0; extra == "observability-tracing"
+Requires-Dist: openinference-instrumentation-langchain<0.2.0,>=0.1.67; python_version < "3.15" and extra == "observability-tracing"
 Provides-Extra: all
 Requires-Dist: DBUtils<4.0,>=3.1; extra == "all"
 Requires-Dist: surrealdb<1.1,>=1.0.7; extra == "all"
@@ -51,6 +80,18 @@ Requires-Dist: pika<1.4,>=1.3.2; extra == "all"
 Requires-Dist: requests<3.0,>=2.31.0; extra == "all"
 Requires-Dist: twilio<10.0,>=9.8.6; extra == "all"
 Requires-Dist: jinja2<4.0,>=3.1.6; extra == "all"
+Requires-Dist: requests<3.0,>=2.31.0; extra == "all"
+Requires-Dist: opentelemetry-api<2.0,>=1.24; extra == "all"
+Requires-Dist: opentelemetry-sdk<2.0,>=1.24; extra == "all"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.24; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-flask<1.0,>=0.45b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "all"
+Requires-Dist: Werkzeug<4.0,>=2.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-fastapi<1.0,>=0.45b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-httpx<1.0,>=0.45b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-requests<1.0,>=0.45b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-psycopg2<1.0,>=0.45b0; extra == "all"
+Requires-Dist: openinference-instrumentation-langchain<0.2.0,>=0.1.67; python_version < "3.15" and extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
@@ -166,10 +207,18 @@ The following extras are available:
 - **data-mysql** - MySQL support
 - **data-mongo** - MongoDB support
 - **data-postgres** - PostgreSQL support
+- **data-dynamodb** - DynamoDB support
 - **messaging** - rabbitmq/sqs messaging
 - **emailing** - mailjet/ses emailing
 - **faxing** - iFax faxing support
 - **sms** - Twilio sms support
+- **observability** - base observability: OpenObserve logging handler plus the OpenTelemetry API used for trace correlation and the `@traced`/`traced_step` decorators
+- **observability-tracing-core** - OpenTelemetry SDK and OTLP/HTTP exporter, required by anything calling `get_tracer_provider()`
+- **observability-flask-tracing** - Flask + requests instrumentation, and Werkzeug for streaming-response detection
+- **observability-fastapi-tracing** - FastAPI + httpx + requests instrumentation
+- **observability-postgres-tracing** - psycopg2 instrumentation (query spans)
+- **observability-langgraph-tracing** - LangChain/LangGraph instrumentation via OpenInference
+- **observability-tracing** - all tracing extras (core plus every framework instrumentation above)
 
 ### Example
 

{rococo-1.3.1 → rococo-1.3.3}/README.md

@@ -101,10 +101,18 @@ The following extras are available:
 - **data-mysql** - MySQL support
 - **data-mongo** - MongoDB support
 - **data-postgres** - PostgreSQL support
+- **data-dynamodb** - DynamoDB support
 - **messaging** - rabbitmq/sqs messaging
 - **emailing** - mailjet/ses emailing
 - **faxing** - iFax faxing support
 - **sms** - Twilio sms support
+- **observability** - base observability: OpenObserve logging handler plus the OpenTelemetry API used for trace correlation and the `@traced`/`traced_step` decorators
+- **observability-tracing-core** - OpenTelemetry SDK and OTLP/HTTP exporter, required by anything calling `get_tracer_provider()`
+- **observability-flask-tracing** - Flask + requests instrumentation, and Werkzeug for streaming-response detection
+- **observability-fastapi-tracing** - FastAPI + httpx + requests instrumentation
+- **observability-postgres-tracing** - psycopg2 instrumentation (query spans)
+- **observability-langgraph-tracing** - LangChain/LangGraph instrumentation via OpenInference
+- **observability-tracing** - all tracing extras (core plus every framework instrumentation above)
 
 ### Example
 

{rococo-1.3.1 → rococo-1.3.3}/rococo/data/postgresql.py

@@ -419,8 +419,8 @@ class PostgreSQLAdapter(DbAdapter):
             return True
         except psycopg2.Error as ex:
             self._connection.rollback()
-            if retry_count < 3 and ex.args[0] == 1213:
-                # Deadlock detected
+            if retry_count < 3 and getattr(ex, 'pgcode', None) == '40P01':
+                # Deadlock detected (PostgreSQL SQLSTATE 40P01)
                 logging.warning("Deadlock detected on table %s. Retrying in %d seconds. Attempt %d",
                                 table_name, 2**retry_count, retry_count+1)
                 time.sleep(2**retry_count)

{rococo-1.3.1 → rococo-1.3.3}/rococo/emailing/mailjet.py

@@ -71,8 +71,14 @@ class MailjetService(EmailService):
     def __call__(self, config: MailjetConfig, *args, **kwargs):
         super().__call__(config)
 
-        match = re.match(r'^(.*)\s*<(.*)>$', self.config.SOURCE_EMAIL)
-        name, email = match.groups()
+        # Parse SOURCE_EMAIL which accepts two formats:
+        #   "Name <email@example.com>"  → {"Name": "Name", "Email": "email@example.com"}
+        #   "user@example.com"          → {"Name": "", "Email": "user@example.com"}
+        match = re.match(r'^\s*(.*?)\s*<(.+)>\s*$', self.config.SOURCE_EMAIL)
+        if match:
+            name, email = match.groups()
+        else:
+            name, email = '', self.config.SOURCE_EMAIL.strip()
         self.from_address = {"Name": name, "Email": email}
 
         self.client = Client(
@@ -152,7 +158,7 @@ class MailjetService(EmailService):
             response_data = result.json()["Data"]
         except Exception as e:
             message = f"Couldn't find Mailjet contact for {email}: {e}"
-            logger.exception(message, "warning")
+            logger.exception(message)
             return
 
         for contact in response_data:
@@ -163,4 +169,4 @@ class MailjetService(EmailService):
                     self.config.MAILJET_API_KEY, self.config.MAILJET_API_SECRET), timeout=15)
             except Exception as e:
                 message = f"Couldn't remove Mailjet contact for {email} : {e}"
-                logger.exception(message, "warning")
+                logger.exception(message)

rococo-1.3.3/rococo/observability/__init__.py

@@ -0,0 +1,16 @@
+# rococo/observability/__init__.py
+from rococo.observability.open_observe import OpenObserve
+# from rococo.observability.datadog import Datadog   # future provider, same shape
+
+PROVIDERS = {
+    "open_observe": OpenObserve,
+}
+
+
+def get_observability_provider(name):
+    try:
+        return PROVIDERS[name]
+    except KeyError:
+        raise ValueError(
+            f"Unknown observability provider: {name!r}. Available: {list(PROVIDERS)}"
+        )

rococo-1.3.3/rococo/observability/_extras.py

@@ -0,0 +1,26 @@
+"""
+Helpers for turning missing optional dependencies into clear, actionable errors.
+
+The observability module's third-party dependencies are all optional extras (see
+``extras_require`` in ``setup.py``). Whenever one of those imports fails, we
+re-raise as an ``ImportError`` that names the exact extra to install, rather than
+leaking a bare ``No module named ...`` that gives the caller no idea which
+``pip install 'rococo[...]'`` would fix it.
+"""
+
+
+def raise_missing_extra(extra, error):
+    """
+    Re-raise a failed optional import as a descriptive ``ImportError``.
+
+    Args:
+        extra: The name of the extra in ``setup.py`` that provides the missing
+            dependency (e.g. ``"observability-flask-tracing"``).
+        error: The original ``ImportError`` that was caught.
+    """
+    raise ImportError(
+        f"This feature of rococo.observability requires the optional "
+        f"'{extra}' dependencies, which are not installed. Install them with:\n\n"
+        f"    pip install 'rococo[{extra}]'\n\n"
+        f"(underlying import error: {error})"
+    ) from error

rococo-1.3.3/rococo/observability/base.py

@@ -0,0 +1,17 @@
+
+class ObservabilityBase:
+    def __init__(self, **config_kwargs):
+        self.config = config_kwargs
+        self._validate_required_config()
+        self.setup()
+
+    def setup(self):
+        raise NotImplementedError("Subclasses must implement the setup method.")
+
+    def _validate_required_config(self):
+        missing = [key for key in self.REQUIRED_CONFIG_KEYS if not self.config.get(key)]
+        if missing:
+            raise ValueError(
+                f"{self.__class__.__name__} configuration is incomplete. "
+                f"Missing required key(s): {', '.join(missing)}."
+            )

rococo-1.3.3/rococo/observability/logging/open_observe_handler.py

@@ -0,0 +1,128 @@
+import atexit
+import base64
+import logging
+import queue
+import threading
+import time
+from urllib.parse import urljoin
+
+from .._extras import raise_missing_extra
+
+try:
+    import requests
+except ImportError as e:
+    # 'requests' is the hard dependency of the base logging handler's transport.
+    raise_missing_extra("observability", e)
+
+try:
+    from opentelemetry import trace
+except ImportError as e:
+    # Every emitted record is correlated with the active trace, so the
+    # opentelemetry API is a hard requirement too (it ships in the same base
+    # 'observability' extra). Fail here, at import time, rather than from
+    # inside emit() — handler errors raised during logging are swallowed by
+    # logging.Handler.handleError in some configurations.
+    raise_missing_extra("observability", e)
+
+
+class OpenObserveHandler(logging.Handler):
+    """
+    Ships log records to an OpenObserve logs stream via HTTP ingestion.
+
+    Non-blocking by design: emit() only builds the log entry and pushes it
+    onto an in-memory queue — a single background thread drains the queue
+    and does the actual HTTP POST (batched), so callers never block on
+    network I/O. Mirrors pyrollbar's default 'thread' handler behavior.
+    """
+
+    def __init__(self, base_url, org_id, ingestion_token, env, stream="app-logs",
+                 service_name=None, timeout=2, queue_maxsize=10_000, batch_size=50):
+        super().__init__()
+        self.url = urljoin(
+            base_url.rstrip("/") + "/",   # ensure exactly one trailing slash
+            f"api/{org_id}/{stream}/_json",  # no leading slash — relative to base
+        )
+        self.auth_header = "Basic " + base64.b64encode((org_id + ':' + ingestion_token).encode()).decode()
+        self.env = env
+        self.service_name = service_name
+        self.timeout = timeout
+        self.batch_size = batch_size
+
+        self._queue = queue.Queue(maxsize=queue_maxsize)
+        self._stop_event = threading.Event()
+        self._worker = threading.Thread(
+            target=self._process_queue,
+            name="OpenObserveHandler-sender",
+            daemon=True,
+        )
+        self._worker.start()
+
+        # Ensure a normal process exit gives the queue a chance to drain
+        atexit.register(self.close)
+
+    def emit(self, record):
+        log_entry = {
+            "_timestamp": int(time.time() * 1_000_000),
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "env": self.env,
+        }
+        if self.service_name:
+            log_entry["service"] = self.service_name
+        if record.exc_info:
+            log_entry["stack_trace"] = self.format(record)
+
+        # Correlate with the active trace, if one exists.
+        span = trace.get_current_span()
+        span_context = span.get_span_context()
+        if span_context.is_valid:
+            log_entry["trace_id"] = format(span_context.trace_id, "032x")
+            log_entry["span_id"] = format(span_context.span_id, "016x")
+
+        try:
+            self._queue.put_nowait(log_entry)
+        except queue.Full:
+            # Queue backed up (OpenObserve unreachable/slow for a while) —
+            # drop rather than block the caller.
+            pass
+
+    def _process_queue(self):
+        """Runs on the background thread: drains the queue, sends batches."""
+        while not self._stop_event.is_set() or not self._queue.empty():
+            batch = self._drain_batch()
+            if batch:
+                self._send(batch)
+            else:
+                time.sleep(0.1)   # nothing to do — avoid a busy loop
+
+    def _drain_batch(self):
+        """Pulls up to self.batch_size entries currently on the queue, non-blocking."""
+        batch = []
+        try:
+            while len(batch) < self.batch_size:
+                batch.append(self._queue.get_nowait())
+        except queue.Empty:
+            pass
+        return batch
+
+    def _send(self, batch):
+        try:
+            requests.post(
+                self.url,
+                json=batch,
+                headers={"Authorization": self.auth_header, "Content-Type": "application/json"},
+                timeout=self.timeout,
+            )
+        except requests.RequestException:
+            pass
+
+    def close(self):
+        """
+        Signals the background thread to finish draining and stop, then
+        waits briefly for it. Registered via atexit so a normal process
+        exit flushes pending logs; a hard kill (SIGKILL) still loses
+        whatever's in the queue at that instant, same as any in-memory queue.
+        """
+        self._stop_event.set()
+        self._worker.join(timeout=5)
+        super().close()

rococo-1.3.3/rococo/observability/open_observe.py

@@ -0,0 +1,333 @@
+
+from .base import ObservabilityBase
+from .logging.open_observe_handler import OpenObserveHandler
+
+
+class OpenObserve(ObservabilityBase):
+    """
+    OpenObserve integration for logging and tracing.
+
+    Required config kwargs:
+        OO_BASE_URL (str): Base URL of the OpenObserve instance, e.g. "http://host:5080".
+        OO_ORG_ID (str): Organization identifier (the slug, not the display name).
+        OO_INGESTION_TOKEN (str): Ingestion token for this org, from the Ingestion page.
+
+    Optional config kwargs:
+        SERVICE_NAME (str): Used to tag logs/traces with `service`/`service.name`.
+            If unset, tracing resource attributes and log tagging are skipped.
+        APP_ENV (str): Environment label (dev/staging/production), tagged on
+            logs and traces. Defaults to no `env` field if unset.
+    """
+
+    REQUIRED_CONFIG_KEYS = ("OO_BASE_URL", "OO_ORG_ID", "OO_INGESTION_TOKEN")
+
+    def setup(self):
+        # config
+        self.oo_base_url = self.config.get("OO_BASE_URL")
+        self.oo_org_id = self.config.get("OO_ORG_ID")
+        self.oo_ingestion_token = self.config.get("OO_INGESTION_TOKEN")
+        self.service_name = self.config.get("SERVICE_NAME")
+        if not all([self.oo_base_url, self.oo_org_id, self.oo_ingestion_token]):
+            raise ValueError(
+                "OpenObserve configuration is incomplete. Please set OO_BASE_URL, OO_ORG_ID, and OO_INGESTION_TOKEN."
+            )
+        
+        # state
+        self._requests_instrumented = False
+        self._psycopg2_instrumented = False
+        self._httpx_instrumented = False
+        self._langgraph_instrumented = False
+        self._tracer_provider_registered = False
+
+
+    def _get_stream(self, stream_name):
+        return f"{stream_name}"
+
+    def get_logging_handler(self, env=None, stream=None):
+        return OpenObserveHandler(
+            base_url=self.oo_base_url,
+            org_id=self.oo_org_id,
+            ingestion_token=self.oo_ingestion_token,
+            env=env or self.config.get("APP_ENV"),
+            stream=stream or self._get_stream('logs'),
+            service_name=self.service_name,
+        )
+
+    def get_tracer_provider(self, env=None, service_name=None, stream=None, register=True):
+        # OpenObserveTracer itself needs opentelemetry-sdk + otlp exporter —
+        # these ARE core requirements for any service doing tracing at all,
+        # so this import can stay at module level in open_observe.py/open_observe_tracer.py
+        from .tracing.open_observe_tracer import OpenObserveTracer
+
+        tracer = OpenObserveTracer(
+            url=self.oo_base_url,
+            org_id=self.oo_org_id,
+            ingestion_token=self.oo_ingestion_token,
+            service_name=service_name or self.service_name,
+            env=env or self.config.get("APP_ENV"),
+            stream=stream or self._get_stream("traces"),
+            register=register and not self._tracer_provider_registered,
+        )
+        if register:
+            self._tracer_provider_registered = True
+        return tracer.provider
+
+    def enable_flask_tracing(self, app, excluded_urls="^/$,^/health$"):
+        """
+        One-call setup for Flask apps: registers the tracer provider (if not
+        already registered), instruments Flask + requests, and wraps every
+        view function in its own span — including streaming/SSE views, where
+        the span stays open for the full duration of response iteration
+        (not just the view function's initial return), so persistence logic
+        that runs during/after streaming still nests correctly.
+ 
+        App code only ever needs to call this single method.
+        """
+        try:
+            from opentelemetry.instrumentation.flask import FlaskInstrumentor
+            from opentelemetry.instrumentation.requests import RequestsInstrumentor
+        except ImportError as e:
+            from ._extras import raise_missing_extra
+            raise_missing_extra("observability-flask-tracing", e)
+ 
+        self.get_tracer_provider()   # no-ops registration if already done
+ 
+        FlaskInstrumentor().instrument_app(
+            app,
+            excluded_urls=excluded_urls   # regex — excludes exact root path "/" and "/health"
+        )
+        if not self._requests_instrumented:
+            RequestsInstrumentor().instrument(
+                excluded_urls=self.oo_base_url  # regex-matched — excludes calls to OpenObserve itself
+            )
+            self._requests_instrumented = True
+ 
+        self._wrap_view_functions(app)
+ 
+    def _wrap_view_functions(self, app, excluded_endpoints=None):
+        """
+        Wraps every registered Flask view function in its own span, named
+        after the Python function. Must run AFTER all blueprints/routes are
+        registered, since app.view_functions is only fully populated by then.
+        """
+        from opentelemetry import trace
+        excluded_endpoints = excluded_endpoints or set()
+        tracer = trace.get_tracer(__name__)
+ 
+        for endpoint, view_func in app.view_functions.items():
+            if endpoint in excluded_endpoints:
+                continue
+            app.view_functions[endpoint] = self._traced_view(tracer, view_func)
+ 
+    def _traced_view(self, tracer, view_func):
+        """
+        Wraps a single view function. Detects Werkzeug streaming responses
+        (SSE, chunked, etc.) and keeps the span open across the full body
+        iteration rather than closing it the instant the view returns the
+        Response object — otherwise any work that happens while the stream
+        is being consumed (e.g. persistence at the end of an SSE generator)
+        runs with no active span/parent context at all.
+        """
+        from opentelemetry import trace, context as otel_context
+        from functools import wraps
+        try:
+            from werkzeug.wrappers import Response
+        except ImportError as e:
+            from ._extras import raise_missing_extra
+            raise_missing_extra("observability-flask-tracing", e)
+ 
+        span_name = f"{view_func.__module__}.{view_func.__name__}"
+ 
+        @wraps(view_func)
+        def wrapper(*args, **kwargs):
+            span = tracer.start_span(span_name)
+            ctx = trace.set_span_in_context(span)
+            token = otel_context.attach(ctx)
+ 
+            try:
+                result = view_func(*args, **kwargs)
+            except Exception as e:
+                span.record_exception(e)
+                span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
+                otel_context.detach(token)
+                span.end()
+                raise
+
+            if isinstance(result, Response) and result.is_streamed:
+                # Real work may still be happening (streaming body, and any
+                # persistence logic run at the end of the generator) — keep
+                # the span alive across that, not just the view's return.
+                otel_context.detach(token)
+                result.response = self._traced_stream(tracer, span, ctx, result.response)
+                return result
+ 
+            # Normal, non-streaming view — span covers exactly this call
+            otel_context.detach(token)
+            span.end()
+            return result
+ 
+        return wrapper
+ 
+    def _traced_stream(self, tracer, span, ctx, body_iter):
+        from opentelemetry import trace, context as otel_context
+
+        it = iter(body_iter)
+        try:
+            while True:
+                token = otel_context.attach(ctx)
+                try:
+                    chunk = next(it)   # the real work happens HERE — now correctly inside the attached context
+                finally:
+                    otel_context.detach(token)
+                yield chunk
+        except StopIteration:
+            return
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
+            raise
+        finally:
+            # Client disconnect (GeneratorExit) closes THIS generator at its
+            # last `yield` — but that does NOT automatically close `it`.
+            # Close it explicitly, with context attached, so any cleanup logic
+            # in stream_chat_message (e.g. _persist_interrupted_stream) also
+            # runs under the correct span.
+            if hasattr(it, "close"):
+                token = otel_context.attach(ctx)
+                try:
+                    it.close()
+                finally:
+                    otel_context.detach(token)
+            span.end()
+
+    def enable_fastapi_tracing(self, app, excluded_urls="^/$,^/health$"):
+        """
+        One-call setup for FastAPI apps: registers the tracer provider (if
+        not already registered) and instruments FastAPI + httpx. App code
+        only ever needs to call this single method, once, at app startup.
+
+        excluded_urls: comma-separated regex patterns for paths to skip
+        (defaults to root "/" and "/health" — typical health-check noise).
+        """
+
+        # Lazy imports — only services that call this need
+        # opentelemetry-instrumentation-fastapi/-httpx installed
+        try:
+            from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+            from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+        except ImportError as e:
+            from ._extras import raise_missing_extra
+            raise_missing_extra("observability-fastapi-tracing", e)
+
+        self.get_tracer_provider()   # no-ops registration if already done
+
+        FastAPIInstrumentor.instrument_app(app, excluded_urls=excluded_urls)
+
+        if not self._httpx_instrumented:
+            HTTPXClientInstrumentor().instrument()
+            self._httpx_instrumented = True
+
+
+    def enable_postgres_tracing(self):
+        """
+        Patches psycopg2 globally so every query run through it produces a
+        span automatically — no changes needed in adapter/repository code.
+
+        Call this exactly once per process, as early as possible, before any
+        psycopg2 connection is created (e.g. from RepositoryFactory.__init__,
+        guarded by a class-level flag + lock — see the calling pattern used
+        there). Safe to call more than once; only instruments the first time.
+        """
+        # Lazy import — only services that call this need
+        # opentelemetry-instrumentation-psycopg2 installed
+        try:
+            from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
+        except ImportError as e:
+            from ._extras import raise_missing_extra
+            raise_missing_extra("observability-postgres-tracing", e)
+
+        if not self._psycopg2_instrumented:
+            Psycopg2Instrumentor().instrument(
+                enable_commenter=True,   # tags SQL with trace context as a
+                                         # comment — lets you correlate a slow
+                                         # query in Postgres logs/pg_stat_statements
+                                         # back to the exact trace that issued it
+                commenter_options={},
+            )
+            self._psycopg2_instrumented = True
+
+
+    def enable_langgraph_tracing(self):
+        """
+        Instruments LangChain/LangGraph via OpenInference — hooks into
+        langchain-core, the shared foundation underlying LangGraph, so this
+        covers node/edge execution, chain/tool calls, and LLM invocations
+        automatically, with zero changes needed in chatbot.py.
+
+        Spans are emitted through whatever tracer provider is already
+        globally registered — call get_tracer_provider() / enable_fastapi_tracing()
+        / enable_flask_tracing() first, so LangGraph spans nest correctly
+        under the active request span rather than being orphaned.
+
+        Safe to call multiple times; only instruments once per process.
+        """
+
+        # Lazy import — only services that call this need
+        # openinference-instrumentation-langchain installed
+        try:
+            from openinference.instrumentation.langchain import LangChainInstrumentor
+        except ImportError as e:
+            from ._extras import raise_missing_extra
+            raise_missing_extra("observability-langgraph-tracing", e)
+
+        if not self._langgraph_instrumented:
+            LangChainInstrumentor().instrument()
+            self._langgraph_instrumented = True
+
+
+    def enable_class_tracing(self, cls, skip_methods=None, name_prefix=None, include_subclasses=True):
+        """
+        Wraps every public, callable, non-dunder method defined directly on
+        `cls` with the shared @traced decorator. If include_subclasses=True
+        (default), also recursively wraps every currently-loaded subclass's
+        own directly-defined methods — so calling this once on the top of
+        your repository hierarchy covers the whole tree.
+
+            self.enable_class_tracing(PostgreSQLRepository)
+            # traces PostgreSQLRepository, BaseRepository, and every
+            # concrete repo (DataImportJobRepository, etc.) in one call
+
+        Note: only classes already imported at call time are visible via
+        __subclasses__() — call this after your views/modules that define
+        repository subclasses have been imported (e.g. after
+        initialize_views(api) in create_app()).
+        """
+        # decorators.traced needs only opentelemetry-api (the base extra) —
+        # class tracing emits spans on whatever provider is already registered,
+        # so it must not drag in the SDK via open_observe_tracer.
+        from .tracing.decorators import traced
+        import inspect
+
+        default_skip = {"__init__", "__init_subclass__"}
+        skip_methods = default_skip | set(skip_methods or [])
+
+        self._trace_single_class(cls, skip_methods, name_prefix, traced, inspect)
+
+        if include_subclasses:
+            for subclass in self._all_subclasses(cls):
+                self._trace_single_class(subclass, skip_methods, name_prefix, traced, inspect)
+
+    def _trace_single_class(self, cls, skip_methods, name_prefix, traced, inspect):
+        if cls.__dict__.get("_oo_class_traced", False):
+            return
+        for name, attr in list(vars(cls).items()):
+            if name.startswith("_") or name in skip_methods:
+                continue
+            if inspect.isfunction(attr):
+                span_name = f"{name_prefix or cls.__name__}.{name}"
+                setattr(cls, name, traced(name=span_name)(attr))
+        cls._oo_class_traced = True
+
+    def _all_subclasses(self, cls):
+        direct = set(cls.__subclasses__())
+        return direct.union(s for sub in direct for s in self._all_subclasses(sub))