Traċċar u Osservabbiltà
F'din il-paġna
Aġġornat fit-3 ta’ Novembru, 2026. Il-proċessuri tat-traċċar qabel kienu jaqraw
trace.start_time,trace.end_time, uspan.name, li ma jeżistux fl-SDK: traċċa m’għandha l-ebda timestamp, u span iġorrstarted_at,ended_at, uspan_data. Il-proċessur tal-esportazzjoni ma kienx jimplimentaon_trace_start, metodu astratt: l-istanzjar tiegħu kien iqajjemTypeError. “Traċċi mbejjna” (Nested traces) kienu joħolqu traċċa ġdida ġo traċċa, li l-SDK jimmarkaha bħala żball probabbli: il-passi issa jużawcustom_span(). Żidiet:flush_traces(), ġestjoni ta’ data sensittiva, u Żamma ta’ Data Żero (Zero Data Retention). Il-kodiċi vverifikat ma’openai-agents0.24.0. Sorsi: Traċċar (dokumentazzjoni tal-SDK) · openai-agents-python.
Traċċar u Osservabbiltà
Aġent fil-produzzjoni huwa kaxxa sewda jekk ma ttraċċax l-azzjonijiet tiegħu. Meta klijent jilmenta dwar tweġiba assurda, ikollok la t-talba eżatta, la l-għodod imsejħa, u lanqas il-valuri li rritornaw. It-traċċar tal-SDK jirreġistra kull pass tal-eżekuzzjoni: sejħiet tal-mudell, għodod użati, trasferimenti (handoffs), u guardrails. Dan huwa l-għodda primarja tiegħek għad-debugging, l-ottimizzazzjoni u l-awditjar tal-aġenti tiegħek.
Traċċar Integrat
Aħbar tajba: m’għandekx bżonn tattivax xejn. L-SDK jitraċċa awtomatikament kull eżekuzzjoni, u b’mod default, jibgħat it-traċċi lid-dashboard ta’ OpenAI f’platform.openai.com. L-aġent hawn taħt, miktub mingħajr ebda istruzzjoni ta’ traċċar, diġà jipproduċi traċċa użabbli.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Searches for a product in the catalog."""
return f"Product found: {name}, price €29.99"
agent = Agent(
name="Shop Agent",
instructions="You help customers find products.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Kull eżekuzzjoni toħloq traċċa awtomatikament
result = Runner.run_sync(agent, "Search for the pro laptop")
Żur id-dashboard biex tara t-traċċa sħiħa: it-tul, it-tokens ikkunsmati, l-għodod imsejħa, u t-tweġiba finali.
Tismija tat-Traċċi
Wara ftit mijiet ta’ eżekuzzjonijiet, id-dashboard isir lista mingħajr distinzjoni. Agħti lit-traċċi tiegħek ismijiet sinifikanti biex tkun tista’ ssibhom faċilment—isem ta’ vjaġġ tan-negozju huwa aħjar minn ID tekniku.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
L-isem tat-traċċa jidher fid-dashboard u jiffaċilita l-iffiltrar.
Tqassim ta’ Fluss tax-Xogħol f’Passi
Għal fluss tax-xogħol b’sejħiet multipli, iftaħ traċċa waħda madwar kollox, imbagħad immarka kull pass b’custom_span(). Tbejjinx trace() ġo oħra: l-SDK imbagħad jirreġistra t-twissija Trace already exists. Creating a new trace, but this is probably a mistake. L-ispans (spans), madankollu, huma ddisinjati biex ikunu mbejjna: kull wieħed ipoġġi taħt l-ispans attwali.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("order-workflow", group_id=conversation_id):
with custom_span("step-1-understanding"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("step-2-processing"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("step-3-confirmation", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Fid-dashboard, it-traċċa order-workflow turi t-tliet passi, u taħt kull wieħed, l-ispans awtomatiċi tal-eżekuzzjoni: aġent, sejħiet tal-mudell, għodod. Il-group_id jgħaqqad it-traċċi mill-istess konversazzjoni, pereżempju billi tuża l-ID tal-thread tiegħek.
B’mod default, l-SDK jdur kull Runner.run() f’traċċa msejħa Agent workflow, u ġewwa t-traċċi l-aġent, kull ġenerazzjoni tal-mudell, kull sejħa ta’ funzjoni, guardrails, u trasferimenti. Għal ġerarkija aktar kompatta, id-dokumentazzjoni tissuġġerixxi li taqta’ l-ispans awtomatiċi tal-kompitu u d-dawriet (turns):
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Proċessuri Personalizzati tat-Traċċar
Id-dashboard ta’ OpenAI huwa konvenjenti, iżda t-tim operattiv tiegħek probabbilment jimmonitorja kull ħaġa oħra f’post ieħor. Biex tibgħat it-traċċi lis-sistema tiegħek stess, ikteb proċessur: dan jirċievi avvenimenti ta’ bidu u tmiem, kemm għat-traċċa sħiħa kif ukoll għal kull span. Is-sitt metodi kollha ta’ TracingProcessor huma astratti: implimentahom kollha, anke jekk vojta, inkella l-istanzjar se jfalli.
Hawnhekk hemm x’jesponi kull oġġett fil-fatt: traċċa għandha trace_id u name, u l-metodu export() tagħha jirritorna wkoll group_id u metadata; m’għandha l-ebda timestamp. Span għandu span_id, trace_id, parent_id, started_at u ended_at (strings ISO 8601), u span_data, li l-attribut type tiegħu huwa agent, generation, function, handoff, guardrail, custom, u hekk iżjed. Għalhekk, it-tul tat-traċċar jitkejjel fil-proċessur.
import time
from datetime import datetime
from typing import Any
from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor
class MyTraceProcessor(TracingProcessor):
def __init__(self) -> None:
self._starts: dict[str, float] = {}
def on_trace_start(self, trace: Trace) -> None:
self._starts[trace.trace_id] = time.monotonic()
print(f"[TRACE START] {trace.name} - {trace.trace_id}")
def on_trace_end(self, trace: Trace) -> None:
duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
print(f"[TRACE END] {trace.name} - duration: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN START] {span.span_data.type}")
def on_span_end(self, span: Span[Any]) -> None:
if span.started_at and span.ended_at:
duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
print(f" [SPAN END] {span.span_data.type} - {duration.total_seconds():.2f} s")
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
add_trace_processor(MyTraceProcessor())
add_trace_processor() jżid il-proċessur tiegħek ma’ dak oriġinali: it-traċċi jkomplu jmorru lid-dashboard ta’ OpenAI. set_trace_processors() jissostitwixxi il-proċessuri default: xejn ma jmur għand OpenAI aktar, sakemm ma tpoġġix l-esportatur tagħhom lura fil-lista int stess.
Esportazzjoni lejn Sistemi Esterni
Għal għodda ta’ osservabbiltà, għandek biss bżonn terġa’ tiffurmatta l-ispans. L-eżempju hawn taħt jikteb linja JSON waħda għal kull span lest, format li ħafna ġabbara tal-logs (log collectors) jafu kif jassimilaw; span.export() diġà jipprovdi dizzjunarju sħiħ.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Writes each finished span as JSON, for a log collector."""
def on_trace_start(self, trace: Trace) -> None:
pass
def on_trace_end(self, trace: Trace) -> None:
logger.info(json.dumps(trace.export(), default=str))
def on_span_start(self, span: Span[Any]) -> None:
pass
def on_span_end(self, span: Span[Any]) -> None:
logger.info(json.dumps(span.export(), default=str))
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
Ara x’tesporta: b’mod default, l-ispans tal-ġenerazzjoni fihom l-inputs u l-outputs tal-mudell, u l-ispans tal-funzjoni fihom l-argumenti u r-riżultati tal-għodod. Biex teskludihom, għaddi RunConfig(trace_include_sensitive_data=False) jew issa l-varjabbli tal-ambjent OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Għal integrazzjonijiet lesti, id-dokumentazzjoni tal-SDK telenka ħafna għodod ta’ partijiet terzi li jipprovdu l-proċessur tagħhom stess.
Titlifx l-Aħħar Traċċi
L-esportatur default jibgħat it-traċċi fl-isfond, kull ftit sekondi. F’ħaddiem (worker) li jipproċessa kompiti u ma jieqafx, jew f’skript qasir, sejjaħ flush_traces() wara li tagħlaq it-traċċa biex tifforza l-ibgħat:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # wara li tintemm it-traċċa, qatt mhux fin-nofs
Diżattivazzjoni tat-Traċċar
Hemm każ wieħed fejn it-traċċar jfixkel aktar milli jgħin: suite tat-testijiet li tħaddem mijiet ta’ aġenti mock u tniġġes id-dashboard tiegħek. Fit-testijiet jew waqt l-iżvilupp lokali, għalhekk tista’ tiddiżattivah, jew globalment jew għal eżekuzzjoni waħda.
from agents import RunConfig, set_tracing_disabled
# Diżattiva kompletament (jew il-varjabbli tal-ambjent OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Jew għal eżekuzzjoni waħda
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
Punt finali, dan kuntrattwali: skont id-dokumentazzjoni, it-traċċar lejn OpenAI mhuwiex disponibbli għal organizzazzjonijiet soġġetti għal politika ta’ Żamma ta’ Data Żero (Zero Data Retention). F’dan il-każ, biss il-proċessur tiegħek stess, installat b’set_trace_processors(), jagħtik it-traċċi.
Metriki Ewlenin biex Timmonitorja
Issa, x’għandek tħares lejh? Fil-produzzjoni, sitt indikaturi biżżejjed biex tikkwalifika s-saħħa ta’ aġent. Il-latenza totali—il-ħin bejn it-talba u t-tweġiba finali—hija dak li l-utenti tiegħek iħossu; spiss tiġi spjegata bin-numru ta’ dawriet (turns), jiġifieri n-numru ta’ drabi li ċ-ċiklu tal-aġent ġie eżegwit. It-tokens ikkunsmati, kemm input kif ukoll output għal kull eżekuzzjoni, jmexxu l-kont tiegħek.
It-tlieta l-oħra jirrigwardaw il-kwalità. Ir-rata ta’ falliment tal-għodod, il-perċentwal ta’ għodod li jirritornaw żball, tikxef API ta’ parti terza instabbli jew argumenti ġġenerati ħażin. Ir-rata ta’ attivazzjoni tal-guardrail, viżibbli fl-ispans guardrail, tkejjel il-frekwenza tal-imblukkar: tiġġieled f’daqqa waħda tissuġġerixxi jew attakk jew guardrail li sar wisq strett. Fl-aħħar nett, id-distribuzzjoni tat-trasferiment (handoff distribution) tgħidlek liema aġent jirrispondi l-aktar spiss—u għalhekk jekk it-triage tiegħek qed jibgħat it-talbiet fejn suppost imorru.
Punti Ewlenin
- L-SDK jitraċċa awtomatikament kull eżekuzzjoni lid-dashboard ta’ OpenAI (ħlief għal organizzazzjonijiet fuq Żamma ta’ Data Żero)
- Traċċa
trace()waħda għal kull fluss tax-xogħol; immarka l-passi b’custom_span(), u użagroup_idbiex tgħaqqad it-traċċi minn konversazzjoni - Traċċa m’għandha l-ebda timestamp; span għandu
started_at,ended_at, uspan_data.type TracingProcessorjimplimenta s-sitt metodi tiegħu;add_trace_processor()iżid,set_trace_processors()jissostitwixxitrace_include_sensitive_data=Falsejeskludi inputs u outputs;flush_traces()jifforza l-ibgħat- Diżattiva t-traċċar fit-testijiet b’
set_tracing_disabled(True)jewRunConfig(tracing_disabled=True)