Structured Logging (agentvisor.logging)

API reference for the module backing Agent Logging — read that guide first for the concepts (idiomatic capture, the agent/agent.<name> log-level grammar, the denoise list). This page covers the module's public functions and classes directly.

Usage

Idiomatic logging requires no import from this module at all:

import logging

logger = logging.getLogger(__name__)
logger.info("Processing query", extra={"query_length": len(query)})

The advanced wrapper, for a logger that must bypass root-logger capture (only useful with AGENTVISOR_LOG_CAPTURE_ROOT=false):

import agentvisor

logger = agentvisor.get_logger(__name__)
logger.info("Processing query", extra={"query_length": len(query)})

API Reference

Functions

get_logger()

def get_logger(name: str) -> logging.Logger

Returns a logging.Logger named agentvisor.agent.<name>, attached directly to the gRPC handler. setup_logging() must have already run (it runs automatically during SDK initialization) for messages to actually reach the host.

setup_logging()

def setup_logging(client: Any = None) -> None

Configures the agentvisor.agent logger hierarchy and — unless AGENTVISOR_LOG_CAPTURE_ROOT=false — attaches a second handler to the Python root logger so idiomatic and third-party logging is captured too. Called automatically during SDK initialization; safe to call again (only the first call has effect).

parse_log_level()

def parse_log_level(s: str) -> dict[str, str]

Parses the AGENTVISOR_LOG_LEVEL grammar (<global>[,<component>=<level>]*) into a dict keyed by "_global" plus each component override, e.g. parse_log_level("warn,agent=debug") → {"_global": "warn", "agent": "debug"}.

extract_component_level()

def extract_component_level(s: str, component: str) -> str

Resolves the effective level for component from the grammar string s, using longest-prefix matching with dot-boundary semantics — falls back to the global level if no override matches.

Classes

GrpcLogHandler

class GrpcLogHandler(logging.Handler):
    def __init__(self, client: Any) -> None: ...

Sends each log record to the host via gRPC as a structured message (level, message, logger name, extra fields). All formatting happens host-side.

FallbackHandler

class FallbackHandler(logging.Handler):
    def emit(self, record: logging.LogRecord) -> None: ...

Simple stderr handler used before the gRPC connection is established (or if it's unavailable).

See Also

• Agent Logging — the concepts and log-level grammar this module implements