Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Traċċar u Osservabbiltà

Lezzjoni 14 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Traċċar u Osservabbiltà
  2. Traċċar Integrat
  3. Tismija tat-Traċċi
  4. Tqassim ta’ Fluss tax-Xogħol f’Passi
  5. Proċessuri Personalizzati tat-Traċċar
  6. Esportazzjoni lejn Sistemi Esterni
  7. Titlifx l-Aħħar Traċċi
  8. Diżattivazzjoni tat-Traċċar
  9. Metriki Ewlenin biex Timmonitorja
  10. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru, 2026. Il-proċessuri tat-traċċar qabel kienu jaqraw trace.start_time, trace.end_time, u span.name, li ma jeżistux fl-SDK: traċċa m’għandha l-ebda timestamp, u span iġorr started_at, ended_at, u span_data. Il-proċessur tal-esportazzjoni ma kienx jimplimenta on_trace_start, metodu astratt: l-istanzjar tiegħu kien iqajjem TypeError. “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żaw custom_span(). Żidiet: flush_traces(), ġestjoni ta’ data sensittiva, u Żamma ta’ Data Żero (Zero Data Retention). Il-kodiċi vverifikat ma’ openai-agents 0.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ża group_id biex tgħaqqad it-traċċi minn konversazzjoni
  • Traċċa m’għandha l-ebda timestamp; span għandu started_at, ended_at, u span_data.type
  • TracingProcessor jimplimenta s-sitt metodi tiegħu; add_trace_processor() iżid, set_trace_processors() jissostitwixxi
  • trace_include_sensitive_data=False jeskludi inputs u outputs; flush_traces() jifforza l-ibgħat
  • Diżattiva t-traċċar fit-testijiet b’set_tracing_disabled(True) jew RunConfig(tracing_disabled=True)