Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Izsekojamība un novērojamība

Nodarbība 14 no 25 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Izsekojamība un novērojamība
  2. Iebūvētā izsekošana
  3. Izsekošanas ierakstu nosaukšana
  4. Darbplūsmas sadalīšana soļos
  5. Pielāgoti izsekošanas procesori
  6. Eksportēšana uz ārējām sistēmām
  7. Nezaudē pēdējos izsekošanas ierakstus
  8. Izsekošanas atspējošana
  9. Galvenie uzraudzāmie rādītāji
  10. Galvenās atziņas

Atjaunināts 2026. gada 3. novembrī. Iepriekš izsekošanas procesori nolasīja trace.start_time, trace.end_time un span.name, kas SDK neeksistē: izsekošanai nav laika zīmoga, bet diapazonam (span) ir started_at, ended_at un span_data. Eksporta procesors neieviesa abstrakto metodi on_trace_start: tā inicializēšana izraisīja TypeError. “Ligzdotas izsekošanas” radīja jaunu izsekošanu citas iekšienē, ko SDK atzīmē kā iespējamu kļūdu: tagad soļos izmanto custom_span(). Papildinājumi: flush_traces(), sensitīvu datu apstrāde un nulles datu saglabāšana (Zero Data Retention). Kods pārbaudīts ar openai-agents 0.24.0. Avoti: Tracing (SDK dokumentācija) · openai-agents-python.

Izsekojamība un novērojamība

Aģents darbības vidē ir melnā kaste, ja tu neizseko tā darbības. Kad klients sūdzas par absurdu atbildi, tev nav nedz precīzā pieprasījuma, nedz izsaukto rīku, nedz to atgriezto vērtību. SDK izsekošana fiksē katru izpildes soli: modeļa izsaukumus, izmantotos rīkus, nodošanas (handoffs) un aizsargbarjeras. Tas ir tavs galvenais rīks aģentu atkļūdošanai, optimizēšanai un auditēšanai.

Iebūvētā izsekošana

Labās ziņas: tev nekas nav jāaktivizē. SDK automātiski izseko katru izpildi un pēc noklusējuma nosūta datus uz OpenAI paneli vietnē platform.openai.com. Tālāk redzamais aģents, uzrakstīts bez nevienas izsekošanas instrukcijas, jau ģenerē lietojamu izsekošanas ierakstu.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Meklē produktu katalogā."""
    return f"Atrasts produkts: {name}, cena 29,99 €"

agent = Agent(
    name="Veikala aģents",
    instructions="Tu palīdzi klientiem atrast produktus.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Katra izpilde automātiski rada izsekošanas ierakstu
result = Runner.run_sync(agent, "Meklē pro klases portatīvo datoru")

Apmeklē paneli, lai redzētu pilnu izsekošanas ierakstu: ilgumu, patērētos tokenus, izsauktos rīkus un gala atbildi.

Izsekošanas ierakstu nosaukšana

Pēc dažiem simtiem izpildu paneļa saraksts kļūst vienveidīgs. Piešķir saviem izsekošanas ierakstiem jēdzīgus nosaukumus, lai tos viegli atrastu — biznesa procesa nosaukums ir labāks par tehnisku ID.

from agents import trace

with trace("premium-klienta-pasutijums"):
    result = await Runner.run(
        agent,
        "Vēlos pasūtīt 5 portatīvos datorus savai komandai",
    )

Izsekošanas nosaukums parādās panelī un atvieglo filtrēšanu.

Darbplūsmas sadalīšana soļos

Darbplūsmai ar vairākiem izsaukumiem izveido vienu izsekošanas ierakstu ap visu procesu, tad katru soli atzīmē ar custom_span(). Nelieto trace() ligzdoti cita trace() iekšienē: tad SDK reģistrē brīdinājumu Trace already exists. Creating a new trace, but this is probably a mistake. Diapazoni (spans) turpretī ir paredzēti ligzdošanai: katrs atrodas zem pašreizējā diapazona.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("pasutijuma-darbplūsma", group_id=conversation_id):
        with custom_span("1-solis-izpratne"):
            result_understanding = await Runner.run(triage_agent, message)

        with custom_span("2-solis-apstrade"):
            result_processing = await Runner.run(
                order_agent,
                result_understanding.to_input_list(),
            )

        with custom_span("3-solis-apstiprinajums", data={"step": 3}):
            result_final = await Runner.run(
                confirmation_agent,
                result_processing.to_input_list(),
            )

    return result_final.final_output

Panelī izsekošanas ieraksts pasutijuma-darbplūsma rāda trīs soļus, un zem katra — automātiskos izpildes diapazonus: aģents, modeļa izsaukumi, rīki. group_id saista vienas sarunas izsekošanas ierakstus, piemēram, izmantojot tavu pavediena ID.

Pēc noklusējuma SDK ietver katru Runner.run() izsekošanas ierakstā ar nosaukumu Agent workflow, un tajā iekšienē — aģentu, katru modeļa ģenerēšanu, katru funkcijas izsaukumu, aizsargbarjeras un nodošanas. Kompaktākai hierarhijai dokumentācija iesaka izslēgt automātiskos uzdevumu un kārtu diapazonus:

from agents import RunConfig

result = await Runner.run(
    agent,
    "Sveiki",
    run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)

Pielāgoti izsekošanas procesori

OpenAI panelis ir ērts, taču tava operāciju komanda, visticamāk, visu pārējo uzrauga citur. Lai nosūtītu datus uz savu sistēmu, uzraksti procesoru: tas saņem sākuma un beigu notikumus gan visai izsekošanai, gan katram diapazonam. Visas sešas TracingProcessor metodes ir abstraktas: tās visas ir jāievieš, pat ja tukšas, pretējā gadījumā inicializēšana neizdosies.

Lūk, ko katrs objekts faktiski piedāvā: izsekošanai ir trace_id un name, un tās export() metode atgriež arī group_id un metadata; tai nav laika zīmoga. Diapazonam ir span_id, trace_id, parent_id, started_at un ended_at (ISO 8601 virknes) un span_data, kura atribūts type ir agent, generation, function, handoff, guardrail, custom utt. Tādējādi izsekošanas ilgumu mēra procesorā.

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"[IZSEKOŠANAS SĀKUMS] {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"[IZSEKOŠANAS BEIGAS] {trace.name} - ilgums: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [DIAPAZONA SĀKUMS] {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"  [DIAPAZONA BEIGAS] {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() pievieno tavu procesoru oriģinālajam: izsekošanas dati turpina nonākt OpenAI panelī. set_trace_processors() aizvieto noklusējuma procesorus: OpenAI vairs nekas nenonāk, ja vien pats manuāli neatgriezīsi to eksportētāju sarakstā.

Eksportēšana uz ārējām sistēmām

Novērojamības rīkam tev tikai jāpārformatē diapazoni. Tālāk redzamais piemērs katram pabeigtam diapazonam raksta vienu JSON rindiņu — formātu, ko pazīst vairums žurnālu vākšanas rīku; span.export() jau nodrošina pilnu vārdnīcu.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

logger = logging.getLogger("agent-traces")


class JsonExportProcessor(TracingProcessor):
    """Raksta katru pabeigtu diapazonu kā JSON žurnālu vākšanas rīkam."""

    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

Uzmanies, ko eksportē: pēc noklusējuma ģenerēšanas diapazoni satur modeļa ievades un izvades, bet funkciju diapazoni — rīku argumentus un rezultātus. Lai tos izslēgtu, nodod RunConfig(trace_include_sensitive_data=False) vai iestati vides mainīgo OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Gataviem integrācijas risinājumiem SDK dokumentācija uzskaita daudzus trešo pušu rīkus, kas nodrošina savus procesorus.

Nezaudē pēdējos izsekošanas ierakstus

Noklusējuma eksportētājs izsekošanas datus nosūta fonā ik pēc dažām sekundēm. Strādniekā, kas apstrādā uzdevumus un neapstājas, vai īsā skriptā pēc izsekošanas ieraksta aizvēršanas izsauc flush_traces(), lai piespiestu nosūtīšanu:

from agents import flush_traces

with trace("nakts-apstrade"):
    await Runner.run(agent, "Apkopoj šodienas biļetes")
flush_traces()  # pēc izsekošanas beigām, nekad vidū

Izsekošanas atspējošana

Ir viens gadījums, kad izsekošana vairāk traucē nekā palīdz: testu komplekts, kas palaiž simtiem mock aģentu un piesārņo tavu paneli. Testos vai lokālās izstrādes laikā to vari atspējot — vai nu globāli, vai vienai izpildei.

from agents import RunConfig, set_tracing_disabled

# Pilnībā atspējot (vai vides mainīgais OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Vai vienai izpildei
result = await Runner.run(agent, "Testa ziņojums", run_config=RunConfig(tracing_disabled=True))

Vēl viens punkts, šoreiz līgumisks: saskaņā ar dokumentāciju izsekošana uz OpenAI nav pieejama organizācijām, uz kurām attiecas nulles datu saglabāšanas (Zero Data Retention) politika. Šādā gadījumā izsekošanas datus nodrošinās tikai tavs paša procesors, uzstādīts ar set_trace_processors().

Galvenie uzraudzāmie rādītāji

Ko tieši tev vajadzētu vērot? Darbības vidē pietiek ar sešiem rādītājiem, lai novērtētu aģenta veselību. Kopējā latentums — laiks starp pieprasījumu un gala atbildi — ir tas, ko sajūt tavi lietotāji; to visbiežāk nosaka kārtu skaits, proti, cik reižu aģenta cikls ir izpildījies. Patērētie tokeni, gan ievade, gan izvade vienā izpildē, nosaka tavus izdevumus.

Pārējie trīs attiecas uz kvalitāti. Rīku kļūmju līmenis — procentuālā daļa rīku, kas atgriež kļūdu — norāda uz nestabilu trešās puses API vai slikti ģenerētiem argumentiem. Aizsargbarjeru aktivizēšanās līmenis, redzams guardrail diapazonos, mēra bloķēšanas biežumu: pēkšņs pieaugums signalizē vai nu uzbrukumu, vai pārāk stingru aizsargbarjeru. Visbeidzot, nodošanu sadalījums parāda, kurš aģents atbild visbiežāk — un tādējādi, vai tava triāža nosūta pieprasījumus tur, kur tiem jānonāk.

Galvenās atziņas

  • SDK automātiski izseko katru izpildi uz OpenAI paneli (izņemot organizācijas ar nulles datu saglabāšanas politiku)
  • Viena trace() vienai darbplūsmai; soļus atzīmē ar custom_span(), un izmanto group_id, lai saistītu vienas sarunas izsekošanas ierakstus
  • Izsekošanai nav laika zīmoga; diapazonam ir started_at, ended_at un span_data.type
  • TracingProcessor ievieš visas sešas metodes; add_trace_processor() pievieno, set_trace_processors() aizvieto
  • trace_include_sensitive_data=False izslēdz ievades un izvades; flush_traces() piespiež nosūtīšanu
  • Testos atspējo izsekošanu ar set_tracing_disabled(True) vai RunConfig(tracing_disabled=True)