aidputils.agents.tools.tool_traces

class aidputils.agents.tools.tool_traces.TraceUtility(tracer_name: str)

Bases: object

A small utility wrapper around OpenTelemetry tracing, modeled after MetricUtility.

Usage:

# Explicit start/end utility = TraceUtility(“my_tracer”) span = utility.create_span(“operation”, attributes={“deploymentId”: “dep-123”, “region”: “us-ashburn-1”}) utility.add_event(span, “started”, attributes={“phase”: “begin”}) # … do work … utility.end_span(span)

# Context manager that attaches to current trace with utility.start_as_current_span(“operation”, attributes={“deploymentId”: “dep-123”, “region”: “us-ashburn-1”}) as span:

utility.add_event(span, “started”, attributes={“phase”: “begin”}) # … do work …

create_span(name: str, attributes: dict | None = None)

Create (start) a span with the given name and optional attributes. The caller is responsible for ending the span (utility.end_span(span) or span.end()).

start_as_current_span(name: str, attributes: dict | None = None)

Start a span as the current span (context manager). This guarantees that if a parent span is active (e.g., from LangGraph/LangChain instrumentation), the new span will be a child of that active span, appending to the current trace.

add_event(span, name: str, attributes: dict | None = None)

Add an event to a given span with optional attributes.

end_span(span)

End the given span safely; avoid double-ending when used with context managers.