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

Monitoraġġ u reġistrazzjoni

Lezzjoni 13 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-osservazzjoni tal-aġent tiegħek fil-produzzjoni
  2. It-tliet livelli ta’ reġistrazzjoni
  3. Metriki biex timmonitorja
  4. Dashboard tal-monitoraġġ
  5. Twissijiet awtomatiċi
  6. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tal-gwida Computer use ta’ OpenAI u d-dokumentazzjoni tal-API tar-Risposti: ir-reġistrazzjoni issa taqra l-azzjonijiet minn computer_call u l-elementi minn response.output (messiġġi bil-phase tagħhom, sommarji tar-raġunament, sejħiet), minflok il-blokok tool_use mill-API ta’ Anthropic; l-ipprezzar hard-coded ta’ Claude Sonnet ġie sostitwit bl-ipprezzar tal-mudell użat, u datetime.utcnow() (deprekat minn Python 3.12) ġie sostitwit b’datetime.now(timezone.utc). Sorsi: Computer use · Pricing.

L-osservazzjoni tal-aġent tiegħek fil-produzzjoni

Aġent ta’ Computer Use fil-produzzjoni huwa kaxxa sewda jekk ma tistabbilixxix monitoraġġ xieraq. Kuntrastat ma’ API standard fejn tirreġistra t-talbiet u r-risposti, hawnhekk trid ttraċċa wkoll l-azzjonijiet viżwali, l-iskrinsħots, u d-deċiżjonijiet tal-mudell. Id-differenza hija konkreta: meta fluss tax-xogħol ifalli fit-3 ta’ filgħodu, il-mistoqsija li timporta mhix “liema eċċezzjoni nqalgħet”, iżda “x’ra l-aġent, u għaliex ikklikkja hemmhekk?” Reġistru li ma jwieġibx dik il-mistoqsija mhux se jgħinek fil-għodu ta’ wara.

It-tliet livelli ta’ reġistrazzjoni

Għalhekk, l-istrumentazzjoni tinbena fuq tliet saffi komplementari: x’għamel l-aġent, x’ħaseb qabel ma għamlu, u x’ra meta ddeċieda. Kull wieħed jikteb f’kanal differenti għax la l-volum u lanqas it-tul tal-ħajja utli huma l-istess.

Livell 1: Azzjonijiet

Kull azzjoni eżegwita mill-aġent trid tiġi ttraċċata. Il-format hawn taħt jipprefigġa sistematikament in-numru tal-iterazzjoni u l-isem tal-pass kurrenti, li jippermettilek tifiltra reġistru ta’ diversi eluf ta’ linji għas-sekwenza waħda li marret ħażin. L-azzjonijiet jaslu bħala oġġetti minn computer_call, bl-istess oqsma bħal fil-handler tiegħek (x, y, scroll_x, keys…). Innota t-trattament tal-azzjoni type: nirreġistraw it-tul tat-test daħħal, qatt il-kontenut tiegħu. Aġent li jimla formola ta’ login jittajpja password, u r-regola mil-lezzjoni preċedenti tapplika hawn mingħajr eċċezzjoni.

import logging

logger = logging.getLogger("computer_use")
logger.setLevel(logging.INFO)

handler = logging.FileHandler("agent.log")
handler.setFormatter(logging.Formatter("%(asctime)s | %(levelname)s | %(message)s"))
handler.addFilter(SensitiveFilter())  # filter from lesson 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Logs an action from a computer_call."""
    prefix = f"[iter={iteration}] [{step}]"
    match action.type:
        case "click" | "double_click" | "move":
            logger.info("%s %s at (%s, %s)", prefix, action.type.upper(), action.x, action.y)
        case "type":
            # Never the text itself: only its length
            logger.info("%s TYPE (%d chars)", prefix, len(action.text))
        case "scroll":
            logger.info("%s SCROLL dx=%s dy=%s", prefix, action.scroll_x, action.scroll_y)
        case "keypress":
            logger.info("%s KEYPRESS %s", prefix, "+".join(action.keys))
        case "drag":
            logger.info("%s DRAG (%d points)", prefix, len(action.path))
        case _:
            logger.info("%s %s", prefix, action.type.upper())

Livell 2: Deċiżjonijiet tal-mudell

Irreġistra x’jgħid il-mudell dwar il-għażliet tiegħu biex tifhem għaliex għażel azzjoni speċifika. Klikk f’koordinati mhux mistennija ma jfisser xejn waħdu; imqabbel mas-sentenza li preċedietha—“il-buttuna ta’ sottomissjoni tidher moħbija mill-banner tal-cookies”—issir dijanjożi. It-test huwa mqassar għal mitejn karattru, biżżejjed biex tifhem l-intenzjoni mingħajr ma tisplodi l-volum tal-fajl. Jeżistu żewġ sorsi ta’ test f’risposta tal-API tar-Risposti. Il-messaġġi intermedjarji li l-mudell jikteb qabel ma jaġixxi jġorru phase: "commentary", filwaqt li r-risposta finali ġġorr phase: "final_answer". U jekk il-mudell użat jappoġġja sommarji tar-raġunament, tiksbhom billi titlobhom (reasoning={"summary": "auto"}): jaslu f’elementi tat-tip reasoning.

Il-konsum tat-tokens huwa rreġistrat bl-istess ritmu, u jistħoqqilu attenzjoni mill-qrib: anke b’previous_response_id, it-tokens kollha tal-input mir-risposti preċedenti fil-katina jerġgħu jiġu ffratturati bħala input, inklużi l-iskrinsħots. L-ispiża ta’ dawra għalhekk tiżdied hekk kif is-sessjoni titwal.

def log_model_response(response, iteration: int):
    """Logs notes, summaries, and calls from a response (excluding images)."""
    for item in response.output:
        if item.type == "reasoning":
            for summary in item.summary:
                logger.info("[iter=%d] REASONING: %s", iteration, summary.text[:200])
        elif item.type == "message":
            text = "".join(c.text for c in item.content if c.type == "output_text")
            logger.info("[iter=%d] MESSAGE (%s): %s", iteration, item.phase or "-", text[:200])
        elif item.type == "computer_call":
            actions = ", ".join(a.type for a in item.actions or [])
            logger.info("[iter=%d] COMPUTER_CALL %s: %s", iteration, item.call_id, actions)
        elif item.type == "function_call":
            logger.info("[iter=%d] FUNCTION_CALL %s", iteration, item.name)

    # Tokens consumed
    logger.info(
        "[iter=%d] TOKENS: in=%d out=%d",
        iteration, response.usage.input_tokens, response.usage.output_tokens,
    )

Livell 3: Skrinsħots

Iħażen l-iskrinsħots għad-debugging wara l-inċidenti, iżda ara l-ispazju fuq id-disk tiegħek: qabda PNG spiss tiżen diversi mijiet ta’ kilobytes, u fluss tax-xogħol twil jipproduċi miji minnhom. Il-klassi hawn taħt issolvi dan b’rotazzjoni sempliċi. L-isem tal-fajl jibda b’timestamp, u jallinja l-ordni alfabetika mal-ordni kronoloġika; l-issortjar f’_cleanup imbagħad huwa biżżejjed biex jidentifika l-aktar qabdiet antiki u jħassarhom sakemm jerġa’ jinżel taħt il-limitu ta’ mitt fajl. Il-qasam label jippermettilek tannota mumenti interessanti, pereżempju error jew before_validation, u ssibhom b’daqqa t’għajn fil-folder.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Saves screenshots with rotation."""

    def __init__(self, base_dir: str = "logs/screenshots", max_files: int = 100):
        self.base_dir = Path(base_dir)
        self.base_dir.mkdir(parents=True, exist_ok=True)
        self.max_files = max_files
        self.counter = 0

    def save(self, screenshot_bytes: bytes, iteration: int, label: str = ""):
        """Saves a screenshot with a descriptive name."""
        ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
        filename = f"{ts}_iter{iteration:03d}_{label}.png"
        filepath = self.base_dir / filename

        with open(filepath, "wb") as f:
            f.write(screenshot_bytes)

        self.counter += 1
        self._cleanup()

        return filepath

    def _cleanup(self):
        """Deletes old screenshots."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Metriki biex timmonitorja

Suċċess
rata għal kull fluss tax-xogħol
Medja
tul għal kull pass
Spiża
f'tokens għal kull eżekuzzjoni
Żbalji
skont it-tip u l-frekwenza

Dawn l-erba’ indikaturi huma utli biss meta mqabbla magħhom infushom maż-żmien: fluss tax-xogħol li jinżel minn disgħin u ħamsa għal tmenin fil-mija ta’ suċċess jgħidlek li interfaċċa mxietha, ferm qabel ma jilmenta l-ewwel utent. Għalhekk, implimenta kollettur tal-metriki marbut ma’ kull eżekuzzjoni. Id-dataclass WorkflowMetrics takkumula t-tokens iterazzjoni wara iterazzjoni, iżżomm rekord tal-iżbalji bil-pass u t-timestamp tagħhom, u tesponi żewġ proprjetajiet ikkalkulati: it-tul, li jaħdem anke jekk il-fluss tax-xogħol mhuwiex lest għadu, u stima tal-ispiża bbażata fuq l-ipprezzar tal-mudell użat, li tieħu mill-paġna tal-ipprezzar ta’ OpenAI minflok ma tħallisha fissa fil-kodiċi. Il-metodu summary jipproduċi d-dizzjunarju kompatt li se tarkivja f’kull eżekuzzjoni.

from dataclasses import dataclass, field
from datetime import datetime, timezone

def now() -> datetime:
    return datetime.now(timezone.utc)

@dataclass
class WorkflowMetrics:
    """Collects metrics for a workflow."""
    workflow_id: str
    input_price_per_million: float  # pricing for the model in use
    output_price_per_million: float
    start_time: datetime = field(default_factory=now)
    end_time: datetime | None = None
    iterations: int = 0
    total_input_tokens: int = 0
    total_output_tokens: int = 0
    errors: list = field(default_factory=list)
    steps_completed: int = 0
    steps_total: int = 0

    def record_iteration(self, response):
        self.iterations += 1
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens

    def record_error(self, error: str, step: str):
        self.errors.append({
            "step": step,
            "error": error,
            "timestamp": now().isoformat(),
        })

    def finalize(self):
        self.end_time = now()

    @property
    def duration_seconds(self) -> float:
        end = self.end_time or now()
        return (end - self.start_time).total_seconds()

    @property
    def estimated_cost_usd(self) -> float:
        # Estimate: prompt caching and a hosted environment are not counted
        input_cost = self.total_input_tokens / 1_000_000 * self.input_price_per_million
        output_cost = self.total_output_tokens / 1_000_000 * self.output_price_per_million
        return input_cost + output_cost

    def summary(self) -> dict:
        return {
            "workflow_id": self.workflow_id,
            "duration_s": round(self.duration_seconds, 1),
            "iterations": self.iterations,
            "tokens": self.total_input_tokens + self.total_output_tokens,
            "cost_usd": round(self.estimated_cost_usd, 4),
            "success": len(self.errors) == 0,
            "errors": len(self.errors),
            "steps": f"{self.steps_completed}/{self.steps_total}",
        }

Dashboard tal-monitoraġġ

Għall-monitoraġġ f’ħin reali, ibgħat il-metriki lil servizz ta’ monitoraġġ minflok ma tħallihom jorqdu f’fajl. Il-funzjoni hawn taħt tibgħat is-sommarju b’timestamp lil endpoint HTTP, b’żewġ prekawzjonijiet li huma importanti daqs l-ibgħat innifsu: dewmien massimu ta’ ħames sekondi, u eċċezzjoni maqbuda li tillimita ruħha għal twissija. Kollettur tal-metriki mhux disponibbli qatt m’għandu jwaqqa’ l-fluss tax-xogħol li qed josserva—il-kuntrarju ikun id-definizzjoni ta’ superviżjoni kontroproduttiva.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Sends metrics to a monitoring service."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests sets the JSON header itself
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Metrics push error: {e}")

Twissijiet awtomatiċi

Dashboard li ħadd ma jħares lejh huwa sempliċiment arkivju. Għalhekk, ikkonfigura twissijiet ibbażati fuq limiti biex l-anomalija tiġi għandek. L-erba’ kundizzjonijiet miżmuma hawnhekk ikopru devjazzjonijiet klassiċi: spiża ogħla minn żewġ dollari, tul li jaqbeż it-tliet minuti, aktar minn tletin iterazzjoni, jew aktar minn żewġ żbalji fl-istess eżekuzzjoni. Dawn il-valuri huma punti tat-tluq, mhux veritajiet: ikkalibrahom fuq kejl mill-eżekuzzjonijiet ta’ suċċess tiegħek stess, u poġġi l-limitu ferm ‘il fuq mill-medjana osservata tiegħek. Twissija li tinxtegħel kuljum se tiġi injorata mit-tieni ġimgħa.

def check_alerts(metrics: WorkflowMetrics):
    """Checks thresholds and triggers alerts."""
    alerts = []

    if metrics.estimated_cost_usd > 2.0:
        alerts.append(f"High cost: ${metrics.estimated_cost_usd:.2f}")

    if metrics.duration_seconds > 180:
        alerts.append(f"Excessive duration: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Too many iterations: {metrics.iterations}")

    if len(metrics.errors) > 2:
        alerts.append(f"Multiple errors: {len(metrics.errors)}")

    for alert in alerts:
        logger.warning(f"ALERT: {alert}")
        # Send notification (email, Slack, etc.)

    return alerts

Agħmilha drawwa li ssejjaħ check_alerts eżatt wara finalize, imbagħad push_metrics: tikseb traċċa arkivjata f’kull eżekuzzjoni, sinjal mibgħut lid-dashboard, u notifika biss meta xi ħaġa tiġbed l-attenzjoni tiegħek.

Punti Ewlenin

  • Irreġistra l-azzjonijiet, il-messaġġi u s-sommarji tal-mudell, u l-qabdiet fuq tliet livelli separati
  • Immonitorja r-rata ta’ suċċess, it-tul, l-ispiża tat-tokens, u l-iżbalji; l-istorja kkatenata terġa’ tiġi ffratturata bħala input f’kull dawra
  • Implimenta rotazzjoni tal-iskrinsħots biex tevita li timla d-disk
  • Stabbilixxi twissijiet awtomatiċi fuq limiti kritiċi
  • Qatt ma tirreġistra data sensittiva (passwords, tokens, data personali)