Tracing & Logging

For full usage examples see Observability guide. This page covers the API signatures.

setup_tracing()

from agentix.tracing import setup_tracing

setup_tracing(provider: Any = None) -> None

Configures the global OpenTelemetry tracer provider.

Argument	Description
provider=None	When None, auto-configures a ConsoleSpanExporter. Pass your own TracerProvider for production.

Zero overhead when opentelemetry-api is not installed — the call is a no-op.

# Auto-configure (local debugging)
setup_tracing()

# Production — supply your own provider
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4317"))
)
setup_tracing(provider=provider)

get_current_trace_context()

from agentix.tracing import get_current_trace_context

context: dict[str, str] = get_current_trace_context()
# {"traceparent": "00-abc123...-def456...-01", "tracestate": ""}

Returns W3C TraceContext headers (traceparent, tracestate) for propagating distributed trace context to downstream services. Returns an empty dict when there is no active span or tracing is disabled.

Span names

Span	Trigger	Key attributes
agentix.run	Each query() call	agentix.session_id, agentix.agent_name, agentix.model, agentix.provider
agentix.llm_call	Each LLM API request	agentix.model, agentix.turn
agentix.tool_call	Each tool execution	agentix.tool_name, agentix.tool_use_id
agentix.subagent	Each sub-agent dispatch	agentix.child_name
agentix.gateway_dispatch	Each gateway message	agentix.channel_type, agentix.user_id, agentix.session_id

setup_logging()

from agentix.log import setup_logging

setup_logging(
    level: str | int = "INFO",
    json: bool = False,
    stream: Any = None,          # defaults to sys.stderr
) -> None

Configures the agentix logger namespace in isolation (propagate=False).

JSONFormatter

from agentix.log import JSONFormatter
import logging

handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logging.getLogger("agentix").addHandler(handler)
logging.getLogger("agentix").setLevel(logging.INFO)

Each JSON log line includes: timestamp (ISO 8601 + ms), level, logger, message, module, function, line, and optionally exception (traceback) and data (structured key-value dict from log_event()).

log_event() / get_logger()

from agentix.log import log_event, get_logger
import logging

log = get_logger("mymodule")   # → logging.getLogger("agentix.mymodule")

log_event(log, logging.INFO, "my_event", key="value", count=42)
# Emits: {"message": "my_event", "data": {"key": "value", "count": 42}, ...}