Καταγραφή και Παρατηρησιμότητα
Σε αυτήν τη σελίδα
Καταγραφή και Παρατηρησιμότητα
Σε περιβάλλον παραγωγής, πρέπει να γνωρίζετε ακριβώς τι συμβαίνει με τις κλήσεις API σας: λανθάνουσα χρόνος (latency), tokens που καταναλώθηκαν, σφάλματα και κόστος. Η δομημένη καταγραφή (structured logging) και η παρατηρησιμότητα σας προσφέρουν αυτή την ορατότητα. Η διαφορά γίνεται εμφανής τη στιγμή που ένας χρήστης αναφέρει: «Ο βοηθός είναι αργός από το πρωί». Χωρίς instrumentation, μένετε να μαντεύετε. Με αυτό, μπορείτε να δείτε σε τριάντα δευτερόλεπτα ότι το p95 latency διπλασιάστηκε μετά από μια αλλαγή στο prompt που τριπλασίασε το μέγεθος του context.
Βασική Δομημένη Καταγραφή
Κάντε συνήθεια να μετράτε γύρω από την κλήση, όχι μέσα σε αυτήν. Καταγράψτε την ώρα πριν, διαβάστε την ξανά μετά και εκπέμψτε μια μόνο γραμμή που περιγράφει ολόκληρο το συμβάν. Το JSON δεν είναι απλώς για εντυπωσιασμό: επιτρέπει στον συλλέκτη σας να φιλτράρει με βάση το status, να παρακολουθεί το duration_ms με την πάροδο του χρόνου ή να αναζητά ένα συγκεκριμένο response_id—κάτι που το ελεύθερο κείμενο δεν μπορεί ποτέ να κάνει. Το μπλοκ except παράγει την ακριβώς ίδια δομή, συμπεριλαμβανομένου του τύπου και του μηνύματος της εξαίρεσης, και στη συνέχεια επαναεκτελεί την εξαίρεση (re-raises). Η καταγραφή δεν είναι διαχείριση σφαλμάτων.
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:
"""API call with full structured logging."""
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!")
Παρατηρήστε ότι καταγράφουμε το prompt_length, όχι το ίδιο το prompt. Αυτή είναι μια σχεδιαστική επιλογή, όχι παράλειψη: το μήκος αρκεί για συσχέτιση με τη λανθάνουσα χρονική καθυστέρηση, χωρίς να εξάγετε δεδομένα χρήστη στο σύστημα καταγραφής σας.
Middleware Καταγραφής
Η επανάληψη αυτού του μπλοκ σε κάθε συνάρτηση που καλεί το API εγγυάται ότι θα το ξεχάσετε κάπου. Είναι καλύτερο να τυλίξετε τον client μια και καλή. Το dataclass APIMetrics ορίζει τη σύμβαση για το τι μετράμε, και το ObservableClient συμπληρώνει αυτή την εγγραφή και την αρχειοθετεί, είτε η κλήση succeeds είτε αποτύχει. Η μέθοδος rapport μετατρέπει στη συνέχεια το ιστορικό σε άμεσα εκτελέσιμες μετρικές—ποσοστό επιτυχίας, μέση λανθάνουσα χρονική καθυστέρηση, λανθάνουσα χρονική καθυστέρηση p95.
Αυτός ο τελευταίος αριθμός έχει τη μεγαλύτερη σημασία. Ένας μέσος όρος 450 ms μπορεί να κρύψει τον έναν στους είκοσι χρήστες που περιμένουν τρία δευτερόλεπτα· το p95 το αποκαλύπτει. Ταξινομώντας τις διάρκειες και λαμβάνοντας την τιμή στο 95ο εκατοστημόριο, περιγράφετε την πραγματική εμπειρία των χρηστών σας με τη χειρότερη εξυπηρέτηση.
from dataclasses import dataclass, field
from typing import Optional
import time
import json
@dataclass
class APIMetrics:
"""Metrics collected for each call."""
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:
"""OpenAI client with built-in observability."""
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:
"""Generate a report of collected metrics."""
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)],
}
# Usage
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))
# Result:
# {
# "total_appels": 3,
# "erreurs": 0,
# "taux_succes": "100.0%",
# "total_tokens": 95,
# "latence_moyenne_ms": 450,
# "latence_p95_ms": 520
# }
Ιχνηλάτηση Κλήσεων με Context
Σε μια κατανεμημένη αρχιτεκτονική, μια κλήση API δεν υπάρχει ποτέ μεμονωμένα: ενεργοποιείται από ένα HTTP request, το οποίο προέρχεται από μια ενέργεια χρήστη, και μερικές φορές ακολουθείται από δύο ακόμη κλήσεις. Το trace_id είναι το νήμα που συνδέει αυτά τα συμβάντα. Διαδίδοντάς το από το web layer σας—εδώ user-123-req-456—μπορείτε να ανακατασκευάσετε ολόκληρη μια συνεδρία στα logs σας από ένα μόνο παράπονο πελάτη. Εκπέμπονται δύο γραμμές, μία στην αρχή και μία κατά την ολοκλήρωση, γεγονός που βοηθά επίσης στον εντοπισμό κλήσεων που δεν επέστρεψαν ποτέ.
import uuid
class TracingClient:
"""Client with tracing to correlate requests."""
def __init__(self):
self.client = OpenAI()
def create_with_trace(self, prompt: str, trace_id: str = None,
**kwargs) -> tuple:
"""Call with trace_id for correlation."""
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
# Usage with trace_id to correlate in logs
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]}...")
Προσοχή με το prompt_preview: αυτοί οι πρώτοι εκατό χαρακτήρες πηγαίνουν κατευθείαν στα logs σας ως έχουν. Αποδεκτό στην ανάπτυξη, αφαιρέστε το μόλις αρχίσουν να ρέουν πραγματικά δεδομένα.
Εξαγωγή σε Σύστημα Παρακολούθησης
Ένα ιστορικό στη μνήμη εξαφανίζεται όταν η διαδικασία επανεκκινείται. Για να παρακολουθείτε μια υπηρεσία με την πάροδο του χρόνου, πρέπει να εκθέτετε μετρικές σε ένα εξωτερικό εργαλείο. Το καθολικό μοτίβο βασίζεται σε δύο οικογένειες: counters, που μόνο αυξάνονται και μετατρέπονται σε rates, και histograms, που διατηρούν μια κατανομή για την εξαγωγή εκατοστημορίων. Αυτή η κλάση είναι σκόπιμα ουδέτερη—απλώς πρέπει να συνδέσετε το get_metrics σε ένα endpoint για να το scrape το Prometheus, ή να στείλετε το dictionary στο Datadog.
# Pattern for exporting to Prometheus, Datadog, etc.
class MetricsExporter:
"""Metrics exporter compatible with monitoring systems."""
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()
# Call exporter.record_success() or exporter.record_error()
# after each API call
Βασικά σημεία
- Καταγράφετε κάθε κλήση με: model, tokens, latency, status, response_id
- Χρησιμοποιείτε δομημένο JSON για logs που τα εργαλεία σας μπορούν να αναλύσουν
- Συλλέγετε βασικές μετρικές: ποσοστό επιτυχίας, λανθάνουσα χρονική καθυστέρηση p95, κατανάλωση tokens
- Προσθέτετε ένα
trace_idγια συσχέτιση αιτημάτων σε κατανεμημένα συστήματα - Εξάγετε μετρικές στο σύστημα παρακολούθησής σας (Prometheus, Datadog, κ.λπ.)
- Μην καταγράφετε ποτέ το περιεχόμενο του prompt σε παραγωγή (ευαίσθητα δεδομένα)