spanforge 1.0.0__py3-none-any.whl

spanforge/exporters/jsonl.py

@@ -0,0 +1,144 @@
+"""spanforge.exporters.jsonl — Synchronous JSONL file exporter.
+
+Appends one canonical JSON line per event to a file on disk.  Zero external
+dependencies (stdlib only).
+
+Usage::
+
+    from spanforge import configure
+    configure(exporter="jsonl", endpoint="./events.jsonl")
+
+    # Now all tracer.span() / agent_run() / agent_step() calls write to
+    # events.jsonl automatically.
+
+You can also instantiate directly for testing::
+
+    from spanforge.exporters.jsonl import SyncJSONLExporter
+    from spanforge.event import Event, EventType, Tags
+
+    exporter = SyncJSONLExporter("/tmp/test.jsonl")  # noqa: S108  # NOSONAR
+    exporter.export(my_event)
+    exporter.close()
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Literal, Union
+
+if TYPE_CHECKING:
+    from spanforge.event import Event
+
+__all__ = ["SyncJSONLExporter"]
+
+_PathLike = Union[str, Path]
+
+
+class SyncJSONLExporter:
+    """Synchronous exporter that appends events as newline-delimited JSON.
+
+    Thread-safe: a :class:`threading.Lock` serialises concurrent writes so
+    the output file is never corrupted when multiple threads share one
+    instance.
+
+    Args:
+        path:     File path, :class:`pathlib.Path`, or ``"-"`` for stdout.
+        mode:     File open mode — ``"a"`` (append, default) or ``"w"``
+                  (overwrite / truncate on first write).
+        encoding: File encoding (default ``"utf-8"``).
+
+    Raises:
+        OSError: If the file cannot be opened or written.
+    """
+
+    def __init__(
+        self,
+        path: _PathLike | str = "spanforge_events.jsonl",
+        mode: str = "a",
+        encoding: str = "utf-8",
+    ) -> None:
+        if mode not in ("a", "w"):
+            raise ValueError("mode must be 'a' or 'w'")
+        self._path_str = str(path)
+        self._mode = mode
+        self._encoding = encoding
+        self._file: IO[str] | None = None
+        self._lock = threading.Lock()
+        self._closed = False
+
+    # ------------------------------------------------------------------
+    # Internal file management
+    # ------------------------------------------------------------------
+
+    def _ensure_open(self) -> IO[str]:
+        """Open the file lazily on first write."""
+        if self._file is not None and not self._file.closed:
+            return self._file
+        if self._path_str == "-":
+            self._file = sys.stdout
+            return self._file
+        # Create parent directories if they don't exist.
+        p = Path(self._path_str)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        self._file = p.open(self._mode, encoding=self._encoding)
+        # After first open, always append.
+        self._mode = "a"
+        return self._file
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def export(self, event: Event) -> None:
+        """Write *event* as a single JSON line.
+
+        Args:
+            event: A fully-formed :class:`~spanforge.event.Event` instance.
+
+        Raises:
+            RuntimeError: If :meth:`close` has already been called.
+            OSError:       If the file write fails.
+        """
+        if self._closed:
+            raise RuntimeError("SyncJSONLExporter is closed")
+        line = event.to_json() + "\n"
+        with self._lock:
+            fh = self._ensure_open()
+            fh.write(line)
+            fh.flush()
+
+    def flush(self) -> None:
+        """Flush any buffered data to disk."""
+        with self._lock:
+            if self._file is not None and not self._file.closed:
+                self._file.flush()
+
+    def close(self) -> None:
+        """Flush and close the output file.  Safe to call multiple times."""
+        with self._lock:
+            if not self._closed:
+                if self._file is not None and self._file is not sys.stdout:
+                    try:
+                        self._file.flush()
+                        self._file.close()
+                    except OSError:
+                        pass
+                    self._file = None
+                self._closed = True
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> SyncJSONLExporter:
+        return self
+
+    def __exit__(self, *_: object) -> Literal[False]:
+        self.close()
+        return False
+
+    def __repr__(self) -> str:
+        state = "closed" if self._closed else "open"
+        return f"SyncJSONLExporter(path={self._path_str!r}, state={state})"

spanforge/exporters/sqlite.py

@@ -0,0 +1,142 @@
+"""spanforge.exporters.sqlite — Synchronous SQLite exporter.
+
+Persists events to a local SQLite database.  Zero external dependencies
+(stdlib ``sqlite3`` only).  Suitable for development, staging, and solo
+deployments where durable single-file storage is needed without standing up
+Redis, Kafka, or a cloud collector.
+
+Usage::
+
+    from spanforge import configure
+    configure(exporter="sqlite", endpoint="./spanforge.db")
+
+    # Events are now durable across process restarts.
+    # Query them with any SQLite client:
+    #   sqlite3 spanforge.db "SELECT event_type, source, ts FROM events ORDER BY ts DESC LIMIT 10;"
+
+You can also instantiate directly::
+
+    from spanforge.exporters.sqlite import SyncSQLiteExporter
+    exporter = SyncSQLiteExporter("./spanforge.db")
+    exporter.export(my_event)
+    exporter.close()
+
+Schema
+------
+Table ``events``:
+
+* ``id``         INTEGER PRIMARY KEY AUTOINCREMENT
+* ``event_id``   TEXT NOT NULL — ULID from :attr:`~spanforge.event.Event.event_id`
+* ``event_type`` TEXT NOT NULL — e.g. ``"trace.span.completed"``
+* ``source``     TEXT NOT NULL
+* ``org_id``     TEXT
+* ``trace_id``   TEXT
+* ``span_id``    TEXT
+* ``ts``         TEXT NOT NULL — ISO-8601 UTC timestamp
+* ``payload``    TEXT NOT NULL — full canonical JSON of the event
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from spanforge.event import Event
+
+__all__ = ["SyncSQLiteExporter"]
+
+_CREATE_TABLE = """
+CREATE TABLE IF NOT EXISTS events (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    event_id   TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    source     TEXT NOT NULL,
+    org_id     TEXT,
+    trace_id   TEXT,
+    span_id    TEXT,
+    ts         TEXT NOT NULL,
+    payload    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_events_trace_id  ON events (trace_id);
+CREATE INDEX IF NOT EXISTS idx_events_event_type ON events (event_type);
+CREATE INDEX IF NOT EXISTS idx_events_ts         ON events (ts);
+"""
+
+_INSERT = """
+INSERT INTO events (event_id, event_type, source, org_id, trace_id, span_id, ts, payload)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+"""
+
+
+class SyncSQLiteExporter:
+    """Synchronous exporter that writes events to a SQLite database.
+
+    Thread-safe: a :class:`threading.Lock` serialises all writes.
+
+    Args:
+        path: Filesystem path for the SQLite database file.  Defaults to
+              ``"spanforge_events.db"``.  Use ``":memory:"`` for tests.
+
+    Raises:
+        sqlite3.Error: If the database cannot be opened or the schema
+                       cannot be initialised.
+    """
+
+    def __init__(self, path: str | Path = "spanforge_events.db") -> None:
+        self._path = str(path)
+        self._lock = threading.Lock()
+        self._closed = False
+        self._conn: sqlite3.Connection = sqlite3.connect(
+            self._path,
+            check_same_thread=False,
+        )
+        self._conn.executescript(_CREATE_TABLE)
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def export(self, event: Event) -> None:
+        """Persist *event* to the SQLite database.
+
+        Args:
+            event: A fully-formed :class:`~spanforge.event.Event` instance.
+
+        Raises:
+            RuntimeError:  If :meth:`close` has already been called.
+            sqlite3.Error: If the INSERT fails.
+        """
+        if self._closed:
+            raise RuntimeError("SyncSQLiteExporter is closed")
+        ts = str(getattr(event, "timestamp", "") or "")
+        row = (
+            str(event.event_id),
+            str(event.event_type.value if hasattr(event.event_type, "value") else event.event_type),
+            str(getattr(event, "source", "") or ""),
+            str(getattr(event, "org_id", "") or "") or None,
+            str(getattr(event, "trace_id", "") or "") or None,
+            str(getattr(event, "span_id", "") or "") or None,
+            ts,
+            event.to_json(),
+        )
+        with self._lock:
+            self._conn.execute(_INSERT, row)
+            self._conn.commit()
+
+    def flush(self) -> None:
+        """Flush — commits are immediate per-write, so this is a no-op."""
+
+    def close(self) -> None:
+        """Close the database connection.  Safe to call multiple times."""
+        with self._lock:
+            if not self._closed:
+                self._closed = True
+                try:
+                    self._conn.close()
+                except sqlite3.Error:
+                    pass