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

Reġistrar u Osservabbiltà

Lezzjoni 15 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Reġistrar u Osservabbiltà
  2. Reġistrar Bażiku Strutturat
  3. Middleware tar-Reġistrar
  4. Traċċar tas-Sejħiet bil-Kuntest
  5. Esportazzjoni għal Sistema ta’ Monitoraġġ
  6. Punti Ewlenin

Reġistrar u Osservabbiltà

Fil-produzzjoni, trid tkun taf eżattament x’inhu jiġri bis-sejħiet tal-API tiegħek: il-latency, it-tokens użati, l-iżbalji u l-ispejjeż. Ir-reġistrar strutturat u l-osservabbiltà jagħtuk dik il-viżibbiltà. Id-differenza ssir ċara mill-ewwel mument li utent jirrapporta, “L-assistent kien bil-mod minn dan il-għodu.” Mingħajr strumentazzjoni, tkun imwaħħal tgħodd bl-għajn. Biha, tkun tista’ tara fi tletin sekonda li l-latency p95 irdoppjat wara bidla fil-prompt li ttripplikat id-daqs tal-kuntest.

Reġistrar Bażiku Strutturat

Agħmilha drawwa li tkejjel madwar is-sejħa, mhux ġo fiha. Irreġistra l-arloġġ qabel, aqrah mill-ġdid wara, u emetti linja waħda li tiddeskrivi l-avveniment kollu. JSON mhux biss għad-dehra: jħalli l-aggregatur tiegħek jiffiltra fuq status, isegwi duration_ms maż-żmien, jew ifittex response_id speċifiku—xi ħaġa li test liberu qatt ma tista’ tagħmel. Il-blokk except jipproduċi l-istess struttura eżatta, inkluż it-tip ta’ eċċezzjoni u l-messaġġ, imbagħad jerġa’ jqajjemha. Ir-reġistrar mhuwiex trattament.

import logging
import json
import time
from openai import OpenAI

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s"
)
logger = logging.getLogger("openai_api")

client = OpenAI()

def appel_avec_logging(prompt: str, model: str = "gpt-5.6-terra") -> str:
    """Sejħa tal-API b'reġistrar strutturat sħiħ."""
    start = time.monotonic()
    request_id = None

    try:
        response = client.responses.create(
            model=model,
            input=prompt
        )

        duree = time.monotonic() - start

        logger.info(json.dumps({
            "event": "api_call",
            "status": "success",
            "model": response.model,
            "response_id": response.id,
            "input_tokens": response.usage.input_tokens,
            "output_tokens": response.usage.output_tokens,
            "total_tokens": response.usage.total_tokens,
            "duration_ms": round(duree * 1000),
            "prompt_length": len(prompt),
        }))

        return response.output_text

    except Exception as e:
        duree = time.monotonic() - start

        logger.error(json.dumps({
            "event": "api_call",
            "status": "error",
            "error_type": type(e).__name__,
            "error_message": str(e),
            "model": model,
            "duration_ms": round(duree * 1000),
            "prompt_length": len(prompt),
        }))
        raise

resultat = appel_avec_logging("Hello!")

Innota li nirreġistraw prompt_length, mhux il-prompt innifsu. Dik hija għażla tad-disinn, mhux żball: it-tul huwa biżżejjed biex tikkorrelata mal-latency, mingħajr ma tesporta data tal-utent għas-sistema tar-reġistrar tiegħek.

Middleware tar-Reġistrar

Li tirrepeti dan il-blokk f’kull funzjoni li ssejjaħ l-API jiggarantixxi li se tinsa xi mkien. Aħjar li ddawwar il-klient darba għal kollox. Il-klassi tad-data APIMetrics tiddefinixxi l-kuntratt ta’ x’inkejjlu, u ObservableClient jimla dik ir-rekord u jarkivjah, kemm jekk is-sejħa tirnexxi jew le. Il-metodu rapport imbagħad ibiddel l-istorja f’metriki direttament azzjonabbli—rata ta’ suċċess, latency medja, latency p95.

Dak in-numru tal-aħħar huwa l-aktar importanti. Medja ta’ 450 ms tista’ taħbi l-wieħed minn għoxrin utent li qed jistenna tliet sekondi; p95 jiżvelaha. Billi tissortja d-durati u tieħu l-valur fil-perċentil 95, tiddeskrivi l-esperjenza reali tal-aktar utenti attivi li qed jiġu servuti l-agħar.

from dataclasses import dataclass, field
from typing import Optional
import time
import json

@dataclass
class APIMetrics:
    """Metriki miġbura għal kull sejħa."""
    model: str = ""
    input_tokens: int = 0
    output_tokens: int = 0
    total_tokens: int = 0
    duration_ms: int = 0
    status: str = "unknown"
    error: Optional[str] = None
    response_id: Optional[str] = None

class ObservableClient:
    """Klient OpenAI b'osservabbiltà integrata."""

    def __init__(self):
        self.client = OpenAI()
        self.metrics_history: list[APIMetrics] = []

    def create(self, model: str, input: str, **kwargs) -> object:
        start = time.monotonic()
        metrics = APIMetrics(model=model)

        try:
            response = self.client.responses.create(
                model=model,
                input=input,
                **kwargs
            )

            metrics.status = "success"
            metrics.response_id = response.id
            metrics.input_tokens = response.usage.input_tokens
            metrics.output_tokens = response.usage.output_tokens
            metrics.total_tokens = response.usage.total_tokens
            metrics.duration_ms = round((time.monotonic() - start) * 1000)

            self.metrics_history.append(metrics)
            return response

        except Exception as e:
            metrics.status = "error"
            metrics.error = str(e)
            metrics.duration_ms = round((time.monotonic() - start) * 1000)
            self.metrics_history.append(metrics)
            raise

    def rapport(self) -> dict:
        """Iġġenera rapport tal-metriki miġbura."""
        if not self.metrics_history:
            return {"message": "No calls recorded"}

        total_calls = len(self.metrics_history)
        erreurs = sum(1 for m in self.metrics_history if m.status == "error")
        total_tokens = sum(m.total_tokens for m in self.metrics_history)
        durees = [m.duration_ms for m in self.metrics_history]

        return {
            "total_appels": total_calls,
            "erreurs": erreurs,
            "taux_succes": f"{((total_calls - erreurs) / total_calls) * 100:.1f}%",
            "total_tokens": total_tokens,
            "latence_moyenne_ms": round(sum(durees) / len(durees)),
            "latence_p95_ms": sorted(durees)[int(len(durees) * 0.95)],
        }

# Użu
obs_client = ObservableClient()

obs_client.create("gpt-5.6-terra", "Hello!")
obs_client.create("gpt-5.6-terra", "How are you?")
obs_client.create("gpt-5.6-terra", "Thanks!")

print(json.dumps(obs_client.rapport(), indent=2))
# Riżultat:
# {
#   "total_appels": 3,
#   "erreurs": 0,
#   "taux_succes": "100.0%",
#   "total_tokens": 95,
#   "latence_moyenne_ms": 450,
#   "latence_p95_ms": 520
# }

Traċċar tas-Sejħiet bil-Kuntest

F’arkitettura distribwita, sejħa tal-API qatt ma teżisti waħedha: tiġi attivat minn talba HTTP, li hi nnifisha ġejja minn azzjoni tal-utent, u xi kultant segwita minn żewġ sejħiet oħra. It-trace_id huwa l-fil li jorbot dawn l-avvenimenti flimkien. Billi tippagah mill-layer tal-web tiegħek—hawnhekk user-123-req-456—tkun tista’ tirrikostruwixxi sessjoni sħiħa fir-reġistri tiegħek minn lment wieħed tal-klijent. Jiġu emessi żewġ linji, waħda fil-bidu u waħda fit-tmiem, li tgħin ukoll biex tindividwa sejħiet li qatt ma rritornaw.

import uuid

class TracingClient:
    """Klient b'traċċar biex jikkorrelata t-talbiet."""

    def __init__(self):
        self.client = OpenAI()

    def create_with_trace(self, prompt: str, trace_id: str = None,
                          **kwargs) -> tuple:
        """Sejħa b'trace_id għall-korrelazzjoni."""
        if trace_id is None:
            trace_id = str(uuid.uuid4())[:8]

        start = time.monotonic()

        logger.info(json.dumps({
            "event": "api_request_start",
            "trace_id": trace_id,
            "prompt_preview": prompt[:100],
        }))

        response = self.client.responses.create(
            model=kwargs.get("model", "gpt-5.6-terra"),
            input=prompt,
            **{k: v for k, v in kwargs.items() if k != "model"}
        )

        duration = time.monotonic() - start

        logger.info(json.dumps({
            "event": "api_request_complete",
            "trace_id": trace_id,
            "response_id": response.id,
            "tokens": response.usage.total_tokens,
            "duration_ms": round(duration * 1000),
        }))

        return response, trace_id

# Użu b'trace_id biex tikkorrelata fir-reġistri
tracing = TracingClient()
response, trace = tracing.create_with_trace(
    "Summarize logging best practices.",
    trace_id="user-123-req-456"
)
print(f"Trace: {trace} | Response: {response.output_text[:80]}...")

Oqgħod attent ma’ prompt_preview: dawk l-ewwel mitt karattru jmorru dritt fir-reġistri tiegħek hekk kif inhuma. Aċċettabbli fl-iżvilupp, neħħih malli tibda tgħaddi data reali.

Esportazzjoni għal Sistema ta’ Monitoraġġ

Storja fil-memorja tisparixxi meta l-proċess jerġa’ jibda. Biex timmonitorja servizz maż-żmien, għandek tesponi l-metriki għal għodda esterna. Il-mudell universali jiddependi fuq żewġ familji: counters, li jiżdiedu biss u jiġu derivati f’rati, u histograms, li jżommu distribuzzjoni biex joħorġu l-perċentili. Din il-klassi hija intenzjonalment newtrali—għandek biss tgħaqqad get_metrics ma’ endpoint biex Prometheus jiskrapjah, jew timbotta d-dizzjunarju lejn Datadog.

# Mudell għall-esportazzjoni lejn Prometheus, Datadog, eċċ.
class MetricsExporter:
    """Esportatur tal-metriki kompatibbli mas-sistemi ta' monitoraġġ."""

    def __init__(self):
        self.counters = {
            "api_calls_total": 0,
            "api_errors_total": 0,
            "tokens_consumed_total": 0,
        }
        self.histograms = {
            "api_latency_ms": [],
        }

    def record_success(self, tokens: int, latency_ms: int):
        self.counters["api_calls_total"] += 1
        self.counters["tokens_consumed_total"] += tokens
        self.histograms["api_latency_ms"].append(latency_ms)

    def record_error(self):
        self.counters["api_calls_total"] += 1
        self.counters["api_errors_total"] += 1

    def get_metrics(self) -> dict:
        latencies = self.histograms["api_latency_ms"]
        return {
            **self.counters,
            "latency_avg_ms": round(sum(latencies) / max(len(latencies), 1)),
            "error_rate": self.counters["api_errors_total"] /
                         max(self.counters["api_calls_total"], 1),
        }

exporter = MetricsExporter()
# Sejjaħ exporter.record_success() jew exporter.record_error()
# wara kull sejħa tal-API

Punti Ewlenin

  • Irreġistra kull sejħa b’: mudell, tokens, latency, status, response_id
  • Uża JSON strutturat għar-reġistri li l-għodod tiegħek jistgħu janalizzaw
  • Iġbor metriki ewlenin: rata ta’ suċċess, latency p95, konsum tat-tokens
  • Żid trace_id biex tikkorrelata t-talbiet f’sistemi distribwiti
  • Esporta l-metriki għas-sistema ta’ monitoraġġ tiegħek (Prometheus, Datadog, eċċ.)
  • Qatt tirreġistra l-kontenut tal-prompt fil-produzzjoni (data sensittiva)