ZerdaZerda

Module-Level Functions

On this page

These are the everyday entry points into the module — the functions most call sites should reach for instead of touching Tracer directly. enable_langsmith, enable_console, enable_json, disable_tracing, and is_tracing_enabled are defined in observability/__init__.py; trace is defined in observability/tracing.py but re-exported at the top level.

enable_langsmith

Python · 6 lines
def enable_langsmith(
    api_key: Optional[str] = None,
    project_name: str = "default",
    enabled: bool = True,
    **client_kwargs: Any,
) -> "BaseExporter"

Registers a LangSmithExporter with the global tracer.

Parameters

NameTypeRequiredDefaultNotes
api_keyOptional[str]noNoneFalls back to LangSmith's own env-var lookup (LANGCHAIN_API_KEY / LANGSMITH_API_KEY) if omitted — see LangSmithExporter.
project_namestrno"default"LangSmith project to log runs into.
enabledboolnoTruePass False to construct and register the exporter without turning tracing on yet — useful if you want to flip it on later with get_tracer().enable().
**client_kwargsAnyno—Forwarded to langsmith.Client(...).

Returns: the created LangSmithExporter instance, in case you want to hold a reference (e.g. to unregister_exporter() it later).

Raises: ImportError if the optional langsmith package is not installed (raised by LangSmithExporter.__init__, propagated unchanged).

Side effects: Constructs a langsmith.Client. If enabled=True (the default), registers the exporter with the global tracer, which also turns tracing on (see Tracer.register_exporter). If enabled=False, the exporter is constructed and returned but not registered at all — note this differs from the docstring's framing of "registered ... without turning tracing on": reading the source, passing enabled=False skips register_exporter() entirely, so the exporter isn't in get_tracer().exporters until you register it yourself.

Python · 3 lines
from zerda.observability import enable_langsmith

enable_langsmith(api_key="ls__...", project_name="Customer Support")

enable_console

Python
def enable_console(verbose: bool = False) -> "BaseExporter"

Constructs a ConsoleExporter(verbose=verbose) and registers it with the global tracer (which also enables tracing).

Parameters: verbose (bool, default False) — when True, the exporter also prints each span's input, output, and metadata.

Returns: the created ConsoleExporter.

Python · 2 lines
from zerda.observability import enable_console
enable_console(verbose=True)

enable_json

Python
def enable_json(path: Optional[str] = None) -> "JSONExporter"

Constructs a JSONExporter(path=path) and registers it with the global tracer.

Parameters: path (Optional[str], default None) — if given, spans are appended as JSON Lines to this file; if omitted, spans accumulate in memory (accessible via the returned exporter's .spans / .to_json()).

Returns: the created JSONExporter — hold onto it if you didn't pass path, since that's the only way to read the in-memory spans back.

Python · 4 lines
from zerda.observability import enable_json
exporter = enable_json()          # in-memory
# ...run traced code...
print(exporter.to_json())

disable_tracing

Python
def disable_tracing() -> None

Calls get_tracer().disable(). Turns tracing into a no-op; registered exporters are kept, so a later get_tracer().enable() (or registering a new exporter) resumes exporting to them without re-registering.

is_tracing_enabled

Python
def is_tracing_enabled() -> bool

Returns get_tracer().enabled — True only when the tracer has been enabled and has at least one registered exporter (see Tracer.enabled).

trace

Defined in tracing.py.

Python
def trace(name: str, type: str = "generic", **kwargs: Any) -> Callable

Decorator factory — the decorator form of get_tracer().span(...), for instrumenting an entire function without writing a with block inside its body.

Parameters

NameTypeRequiredDefaultNotes
namestryes—Span name for every call to the decorated function.
typestrno"generic"Forwarded to Tracer.span(type=...).
**kwargsAnyno—Forwarded to Tracer.span(...) — e.g. model, provider, metadata.

Returns: a decorator that wraps the target function with functools.wraps (so __name__, __doc__, etc. are preserved).

Behavior: on each call to the wrapped function, opens get_tracer().span(name, type=type, **kwargs), calls the original function with all args/kwargs passed through unchanged, sets the span's output to the function's return value via span.set_output(result), and returns that value. Function input is not automatically captured — span.set_input(...) is never called by trace(), so span.input stays None for decorator-based tracing unless you also pass an input=... kwarg through **kwargs, which — because Tracer.span() sets input once at span construction — would then be a fixed value shared by every call, not the actual per-call arguments.

Raises: whatever the wrapped function raises — propagated by the same "finish with error, then re-raise" behavior as Tracer.span().

Example

Python · 5 lines
from zerda.observability import trace

@trace("MyTool", type="tool")
def run_tool(query: str) -> str:
    return do_work(query)

Related: Tracer · Span · Exporters · Quickstart

Related pages