Buckets:
AnonymousSpottedToad/human_verified_bucket / codebase /python /ctrl-gaurav_effGen /effgen /utils /structured_logging.py
| """ | |
| Structured logging for effGen framework. | |
| .. note:: | |
| ``effgen.observability.logs`` (``get_logger`` / ``configure_logging`` / | |
| ``EffGenLogger``) is the canonical structured-logging home and shares this | |
| module's thread-local run context. This module stays available for backwards | |
| compatibility; prefer ``effgen.observability`` in new code. | |
| Provides JSON-formatted log output with consistent fields for agent execution, | |
| tool calls, and model inference. Each Agent.run() gets a unique run_id; | |
| multi-agent runs share a workflow_id. | |
| Configuration: | |
| - JSON mode: machine-readable JSON lines (for log aggregation) | |
| - Human mode: coloured, human-readable output (default) | |
| Usage: | |
| from effgen.utils.structured_logging import StructuredLogger, get_structured_logger | |
| slog = get_structured_logger("my_module") | |
| slog.agent_event("math_agent", "task_start", task="What is 2+2?") | |
| slog.tool_event("calculator", "call", input={"expression": "2+2"}) | |
| # With run context (automatically set by Agent.run): | |
| from effgen.utils.structured_logging import LogRunContext | |
| with LogRunContext(run_id="abc-123", agent_name="math_agent"): | |
| slog.info("Processing task") # run_id included automatically | |
| """ | |
| from __future__ import annotations | |
| import json | |
| import logging | |
| import threading | |
| import uuid | |
| from collections.abc import Iterator | |
| from contextlib import contextmanager | |
| from datetime import UTC, datetime | |
| from typing import Any | |
| logger = logging.getLogger(__name__) | |
| # Thread-local storage for run context | |
| _run_context = threading.local() | |
| # --------------------------------------------------------------------------- | |
| # Run / Workflow context management | |
| # --------------------------------------------------------------------------- | |
| def generate_run_id() -> str: | |
| """Generate a unique run ID.""" | |
| return uuid.uuid4().hex[:12] | |
| def generate_workflow_id() -> str: | |
| """Generate a unique workflow ID.""" | |
| return uuid.uuid4().hex[:12] | |
| def get_current_run_id() -> str | None: | |
| """Get the current run_id from thread-local context.""" | |
| return getattr(_run_context, "run_id", None) | |
| def get_current_workflow_id() -> str | None: | |
| """Get the current workflow_id from thread-local context.""" | |
| return getattr(_run_context, "workflow_id", None) | |
| def get_current_agent_name() -> str | None: | |
| """Get the current agent_name from thread-local context.""" | |
| return getattr(_run_context, "agent_name", None) | |
| def get_current_session_id() -> str | None: | |
| """Get the current session_id from thread-local context.""" | |
| return getattr(_run_context, "session_id", None) | |
| def LogRunContext( | |
| run_id: str | None = None, | |
| workflow_id: str | None = None, | |
| agent_name: str | None = None, | |
| session_id: str | None = None, | |
| ) -> Iterator[None]: | |
| """Set run-level identifiers on every log entry within the scope. | |
| Nesting is supported — inner contexts override outer. | |
| Args: | |
| run_id: Unique ID for this Agent.run() invocation | |
| workflow_id: Shared ID across multi-agent workflow | |
| agent_name: Name of the agent | |
| session_id: Session identifier | |
| Returns: | |
| A context manager that carries the identifiers for its scope. | |
| """ | |
| prev_run = getattr(_run_context, "run_id", None) | |
| prev_wf = getattr(_run_context, "workflow_id", None) | |
| prev_agent = getattr(_run_context, "agent_name", None) | |
| prev_session = getattr(_run_context, "session_id", None) | |
| _run_context.run_id = run_id or prev_run | |
| _run_context.workflow_id = workflow_id or prev_wf | |
| _run_context.agent_name = agent_name or prev_agent | |
| _run_context.session_id = session_id or prev_session | |
| try: | |
| yield | |
| finally: | |
| _run_context.run_id = prev_run | |
| _run_context.workflow_id = prev_wf | |
| _run_context.agent_name = prev_agent | |
| _run_context.session_id = prev_session | |
| # --------------------------------------------------------------------------- | |
| # JSON Formatter for stdlib logging | |
| # --------------------------------------------------------------------------- | |
| class EffGenJSONFormatter(logging.Formatter): | |
| """JSON formatter that injects effGen context fields into every log line. | |
| The injected fields are ``run_id``, ``workflow_id``, ``agent_name`` and | |
| ``session_id``. | |
| """ | |
| def format(self, record: logging.LogRecord) -> str: | |
| """Render *record* as one JSON line with the active run-context fields.""" | |
| data: dict[str, Any] = { | |
| "timestamp": datetime.now(UTC).isoformat(), | |
| "level": record.levelname, | |
| "logger": record.name, | |
| "message": record.getMessage(), | |
| } | |
| # Inject run context | |
| run_id = getattr(record, "run_id", None) or get_current_run_id() | |
| if run_id: | |
| data["run_id"] = run_id | |
| wf_id = getattr(record, "workflow_id", None) or get_current_workflow_id() | |
| if wf_id: | |
| data["workflow_id"] = wf_id | |
| agent = getattr(record, "agent_name", None) or get_current_agent_name() | |
| if agent: | |
| data["agent_name"] = agent | |
| session = getattr(record, "session_id", None) or get_current_session_id() | |
| if session: | |
| data["session_id"] = session | |
| # Iteration number if present | |
| iteration = getattr(record, "iteration", None) | |
| if iteration is not None: | |
| data["iteration"] = iteration | |
| # Source location | |
| data["module"] = record.module | |
| data["function"] = record.funcName | |
| data["line"] = record.lineno | |
| # Exception info | |
| if record.exc_info and record.exc_info[0] is not None: | |
| data["exception"] = { | |
| "type": record.exc_info[0].__name__, | |
| "message": str(record.exc_info[1]), | |
| } | |
| # Extra fields passed via `extra=` parameter | |
| skip_keys = { | |
| "name", "msg", "args", "created", "filename", "funcName", | |
| "levelname", "levelno", "lineno", "module", "msecs", "pathname", | |
| "process", "processName", "relativeCreated", "thread", "threadName", | |
| "exc_info", "exc_text", "stack_info", "message", "asctime", | |
| "run_id", "workflow_id", "agent_name", "session_id", "iteration", | |
| "taskName", | |
| } | |
| for key, value in record.__dict__.items(): | |
| if key not in skip_keys and not key.startswith("_"): | |
| try: | |
| json.dumps(value) # only include JSON-serializable values | |
| data[key] = value | |
| except (TypeError, ValueError): | |
| data[key] = str(value) | |
| return json.dumps(data, default=str) | |
| # --------------------------------------------------------------------------- | |
| # StructuredLogger — high-level API for effGen events | |
| # --------------------------------------------------------------------------- | |
| class StructuredLogger: | |
| """ | |
| High-level structured logger for effGen components. | |
| Wraps a stdlib logger and provides convenience methods for common events. | |
| Context fields (run_id, agent_name, etc.) are automatically injected. | |
| """ | |
| def __init__(self, name: str, json_mode: bool = False) -> None: | |
| self._logger = logging.getLogger(name) | |
| self._json_mode = json_mode | |
| # -- Standard log levels (delegates to stdlib) -- | |
| def debug(self, msg: str, **extra: Any) -> None: | |
| """Log at DEBUG with *extra* as structured fields.""" | |
| self._log(logging.DEBUG, msg, **extra) | |
| def info(self, msg: str, **extra: Any) -> None: | |
| """Log at INFO with *extra* as structured fields.""" | |
| self._log(logging.INFO, msg, **extra) | |
| def warning(self, msg: str, **extra: Any) -> None: | |
| """Log at WARNING with *extra* as structured fields.""" | |
| self._log(logging.WARNING, msg, **extra) | |
| def error(self, msg: str, **extra: Any) -> None: | |
| """Log at ERROR with *extra* as structured fields.""" | |
| self._log(logging.ERROR, msg, **extra) | |
| # -- Domain-specific convenience methods -- | |
| def agent_event( | |
| self, | |
| agent_name: str, | |
| event: str, | |
| *, | |
| level: int = logging.INFO, | |
| **data: Any, | |
| ) -> None: | |
| """Log an agent-level event (task_start, task_complete, error, etc.). | |
| Args: | |
| agent_name: The agent the event belongs to. | |
| event: What happened, such as ``task_start`` or ``error``. | |
| level: Level the line is logged at. | |
| **data: Extra fields recorded with the entry. | |
| """ | |
| self._log( | |
| level, | |
| f"[{agent_name}] {event}", | |
| event_type="agent", | |
| event=event, | |
| agent_name=agent_name, | |
| **data, | |
| ) | |
| def tool_event( | |
| self, | |
| tool_name: str, | |
| event: str, | |
| *, | |
| level: int = logging.DEBUG, | |
| **data: Any, | |
| ) -> None: | |
| """Log a tool-level event (call, result, error). | |
| Args: | |
| tool_name: The tool the event belongs to. | |
| event: What happened, such as ``call``, ``result`` or ``error``. | |
| level: Level the line is logged at. | |
| **data: Extra fields recorded with the entry. | |
| """ | |
| self._log( | |
| level, | |
| f"[tool:{tool_name}] {event}", | |
| event_type="tool", | |
| event=event, | |
| tool_name=tool_name, | |
| **data, | |
| ) | |
| def model_event( | |
| self, | |
| model_name: str, | |
| event: str, | |
| *, | |
| level: int = logging.DEBUG, | |
| **data: Any, | |
| ) -> None: | |
| """Log a model-level event (generate, stream, error). | |
| Args: | |
| model_name: The model the event belongs to. | |
| event: What happened, such as ``generate``, ``stream`` or ``error``. | |
| level: Level the line is logged at. | |
| **data: Extra fields recorded with the entry. | |
| """ | |
| self._log( | |
| level, | |
| f"[model:{model_name}] {event}", | |
| event_type="model", | |
| event=event, | |
| model_name=model_name, | |
| **data, | |
| ) | |
| def iteration_event( | |
| self, | |
| iteration: int, | |
| event: str, | |
| *, | |
| level: int = logging.DEBUG, | |
| **data: Any, | |
| ) -> None: | |
| """Log a ReAct iteration event. | |
| Args: | |
| iteration: The reasoning iteration the event belongs to. | |
| event: What happened in that iteration. | |
| level: Level the line is logged at. | |
| **data: Extra fields recorded with the entry. | |
| """ | |
| self._log( | |
| level, | |
| f"[iter:{iteration}] {event}", | |
| event_type="iteration", | |
| event=event, | |
| iteration=iteration, | |
| **data, | |
| ) | |
| # -- Internal -- | |
| def _log(self, level: int, msg: str, **extra: Any) -> None: | |
| """Emit a log record with extra context fields.""" | |
| # Inject current run context into extra | |
| extra.setdefault("run_id", get_current_run_id()) | |
| extra.setdefault("workflow_id", get_current_workflow_id()) | |
| extra.setdefault("agent_name", get_current_agent_name()) | |
| extra.setdefault("session_id", get_current_session_id()) | |
| # Remove None values to keep logs clean | |
| extra = {k: v for k, v in extra.items() if v is not None} | |
| self._logger.log(level, msg, extra=extra) | |
| # --------------------------------------------------------------------------- | |
| # Module-level helpers | |
| # --------------------------------------------------------------------------- | |
| _structured_loggers: dict[str, StructuredLogger] = {} | |
| def get_structured_logger(name: str, json_mode: bool = False) -> StructuredLogger: | |
| """ | |
| Get or create a StructuredLogger for the given module name. | |
| Args: | |
| name: Logger name (typically __name__) | |
| json_mode: Whether to use JSON formatting | |
| Returns: | |
| StructuredLogger instance | |
| """ | |
| key = f"{name}:{json_mode}" | |
| if key not in _structured_loggers: | |
| _structured_loggers[key] = StructuredLogger(name, json_mode=json_mode) | |
| return _structured_loggers[key] | |
| def setup_json_logging( | |
| level: str | int = "INFO", | |
| logger_name: str | None = None, | |
| ) -> None: | |
| """Configure a logger (or the root logger) to emit JSON lines. | |
| Installs an ``EffGenJSONFormatter`` stream handler. | |
| Args: | |
| level: Log level | |
| logger_name: Specific logger name, or None for root | |
| """ | |
| if isinstance(level, str): | |
| level = getattr(logging, level.upper(), logging.INFO) | |
| target = logging.getLogger(logger_name) | |
| target.setLevel(level) | |
| handler = logging.StreamHandler() | |
| handler.setLevel(level) | |
| handler.setFormatter(EffGenJSONFormatter()) | |
| target.handlers.clear() | |
| target.addHandler(handler) | |
| target.propagate = False | |
Xet Storage Details
- Size:
- 12.9 kB
- Xet hash:
- c4ec69804fc601a0c5d899309e9a1c39bdf02083fe0af0d92e87545b9224472b
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.