Monitoraġġ u reġistrazzjoni
F'din il-paġna
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_callu l-elementi minnresponse.output(messiġġi bil-phasetagħhom, sommarji tar-raġunament, sejħiet), minflok il-blokoktool_usemill-API ta’ Anthropic; l-ipprezzar hard-coded ta’ Claude Sonnet ġie sostitwit bl-ipprezzar tal-mudell użat, udatetime.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
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)