pipeline.observability

Pipeline observability: logging configuration for GDI pipeline and server.

This module works identically whether the package is installed as ````gdi```` or
````gdisdk```` — it derives the root logger namespace from its own ````__name__````.

Two public functions are provided:

````configure_logging()````
    Full production setup: rotating JSON-Lines file (for Grafana/Loki),
    Logfire cloud (when ````LOGFIRE_TOKEN```` is set), and a console fallback.
    Called once at server startup (e.g. ````gdiServer.py````).  Not intended for
    ````gdisdk```` users who build their own server — they should configure logging
    to match their own stack.

````configure_local_logging()````
    Lightweight local-debug setup: console output only, no file rotation.
    Called automatically inside :class:``~gdi.pipeline.pipeline.PipeLine``
    when ````verbose=True```` and no handlers are configured yet.  ````gdisdk````
    users who want readable console output can also call it manually::

        from gdisdk.pipeline.observability import configure_local_logging
        configure_local_logging()

Environment Variables (production / ````configure_logging```` only)
GDI_LOG_FILE
    Absolute path to the rotating JSON-Lines log file.

Examples

GDI_LOG_BACKUP_COUNT
    Number of daily log-rotation backups to keep.  Default: ````7````.

LOGFIRE_TOKEN
    Pydantic Logfire project write token.  Traces are forwarded to the
    Logfire cloud UI only when this variable is set.

Functions

pipeline.observability.configure_logging() → None

Full production logging setup — called once at server startup.

Sets up:

#. **Logfire** — cloud tracing when ````LOGFIRE_TOKEN```` is set, console
   output otherwise.  Python stdlib logging records are bridged into
   Logfire spans via ````instrument_logging()````.
#. **Rotating JSON-Lines file** — when ````GDI_LOG_FILE```` (or *log_file*)
   is configured; midnight rotation, configurable backup count.
#. **Console handler** — only when no file is configured (local dev
   without a Logfire token still gets readable output).

This function is idempotent — safe to call multiple times.

Parameters

log_filestr | Path | None: Path to the rotating log file. Falls back to ``GDI_LOG_FILE`` env var. log_file_backup_count : int, default ``7`` Daily backups to retain. Overridden by ``GDI_LOG_BACKUP_COUNT``. send_to_logfire : bool | str, default ``"if-token-present"`` ``"if-token-present"`` sends to cloud only when ``LOGFIRE_TOKEN`` is set. Pass ``False`` to force local-only mode.

pipeline.observability.configure_local_logging() → None

Lightweight local-debug setup: console output only, no file rotation.

Safe to call multiple times.  Automatically called by
:class:``~gdi.pipeline.pipeline.PipeLine`` when ````verbose=True```` and no
handlers are configured yet, so most ````gdisdk```` users never need to call
this directly.

Advanced users who want console output even without ````verbose=True````
can call it once at the top of their script::

    from gdisdk.pipeline.observability import configure_local_logging
    configure_local_logging()

pipeline.observability.get_logger(name: str = '') → logging.Logger

Parameters

namestr: Dotted sub-name appended after the root package, e.g. ``"pipeline"``. If empty, returns the root package logger (``"gdi"`` or ``"gdisdk"``).

pipeline.observability.render_run_trace_html(trace_file: str | Path, output_file: str | Path | None = None, svg_content: str | None = None) → Path

Render a run trace JSON file as a self-contained interactive HTML viewer.

The HTML file can be opened directly in any browser — no server required.
It provides:

- An optional **pipeline graph** card showing the execution status of every
  module (green = executed, red = not run), embedded as inline SVG when
  graphviz is available.
- A **module execution summary** table showing which modules ran, how
  many times (````executed_count````), and whether ````auto_run```` was enabled.
- A filterable / searchable **event log** table with colour-coded rows.
- Click any row to expand the full JSON record (input/output previews,
  timing, error details, etc.).

Parameters

trace_filestr | Path: Path to the JSON array trace file produced by ``run_trace_file``.
output_filestr | Path | None: Output HTML path. Defaults to trace_file with a ``.html`` extension (same directory, same stem).
svg_contentstr | None: Inline SVG string for the pipeline graph. When provided, a collapsible “Pipeline Graph” card is inserted at the top of the report. When ``None``, the graph section is omitted.

Returns

Any

Path
    The path of the written HTML file.

Examples

Standalone use::

    from gdi.pipeline.observability import render_run_trace_html
    render_run_trace_html("./output/run_trace.json")
    # writes ./output/run_trace.html