Konfiguration - Python

Wissenswerte Optionen

Umgebungen

Jede Umgebung sollte unter einem eindeutigen Namen berichten - production, staging, preview. Der Name ist eine Spalte im Panel und ein Filter in der Fehlerliste; ohne ihn sieht ein Produktionsausfall genauso aus wie ein Fehler, den jemand im Test ausgelöst hat. Lass die lokale Umgebung ohne Zugangsdaten: ohne Token und Schlüssel lädt die Integration und bleibt still - ein eigener Schalter ist nicht nötig.

Wann Ereignisse hinausgehen

Der Client sendet nie etwas während des Teils der Anfrage, auf den der Besucher wartet. send_later() plant einen Versand, ohne auf ihn zu warten - die Methode kehrt sofort zurück, während die Aufgabe im Event-Loop weiterläuft:

client.send_later(client.capture_exception(error))

Die Aufgabe wird in einer internen Menge gehalten, bis sie fertig ist - eine Coroutine, auf die nur der Event-Loop verweist, könnte sonst mitten im Flug vom Garbage Collector eingesammelt werden, was das Ereignis lautlos verwirft. Ein Fehlschlag wird an den Logger dock_ray gemeldet statt den Aufrufstapel hinaufzureichen - kein send_later()-Aufruf unterbricht die Anwendung, aus der heraus gerade gemeldet wird.

Das ASGI-Middleware arbeitet im gleichen Takt: Es meldet eine Transaktion erst, wenn die Anwendung mit dem Schreiben der Antwort fertig ist. Ein langsames oder nicht erreichbares Panel kostet den Besucher nichts.

ASGI-Middleware und FastAPI

Das Middleware öffnet eine Transaktion pro Anfrage und meldet unbehandelte Ausnahmen. Es ist gegen die reine ASGI-Schnittstelle geschrieben, nicht gegen ein bestimmtes Framework, und läuft daher unter FastAPI, Starlette und jeder anderen Anwendung, die dieses Protokoll spricht - und puffert keine gestreamten Antworten.

from fastapi import FastAPI
from dock_ray import DockRayClient, DockRayFastAPIMiddleware

client = DockRayClient(token="...", private_key="...")
app = FastAPI()

app.add_middleware(
    DockRayFastAPIMiddleware,
    client=client,
    exclude_paths=["/health", "/metrics"],
)

@app.on_event("shutdown")
async def shutdown() -> None:
    await client.close()

Jede Anfrage wird zusammen mit ihrer Methode, ihrem Pfad, der Dauer und dem Antwortstatus gemeldet. exclude_paths lässt standardmäßig /health und /metrics aus - Pfade, die von der Infrastrukturüberwachung alle paar Sekunden abgefragt werden, sollen echten Traffic nicht aus der Transaktionsliste verdrängen. capture_transactions=False schaltet diesen Teil des Middleware ab und lässt nur das Melden von Ausnahmen übrig.

HTTPException wird von FastAPI selbst behandelt und erreicht das Middleware nie als Ausnahme - erwartete Antworten wie 404 oder 422 werden also nicht zu Fehlern, sondern landen im Panel als Transaktionen mit genau diesem Statuscode.

Die IP-Adresse des Besuchers liest das Middleware aus dem Header X-Forwarded-For oder X-Real-IP, bevor es auf die Socket-Adresse zurückfällt - hinter einem Load Balancer gehört dieses Socket dem Balancer, nicht dem Besucher. Authorization, Cookie und X-Api-Key werden aus den gemeldeten Headern entfernt.

Manuelle Transaktionen

Nützlich für Arbeit außerhalb einer HTTP-Anfrage, etwa in einem Hintergrund-Worker:

import time, uuid
from dock_ray import Span

started = time.time()
await run_daily_cleanup()
ended = time.time()

span = Span(
    span_id=uuid.uuid4().hex[:16],
    trace_id=uuid.uuid4().hex,
    start_timestamp=started,
    end_timestamp=ended,
    status="200",
    description="Daily cleanup",
    op="worker.task",
    data={"url": "job:daily_cleanup", "method": "CLI"},
)

await client.capture_transaction(name="job:daily_cleanup", spans=[span])

Der Wurzel-Span - der ohne parent_span_id - trägt die URL, die Methode und den Status, nach denen das Panel die Transaktion indiziert. Fehlen diese drei Felder im Wurzel-Span, hat die Transaktion nichts, wonach sie in der Liste erscheinen könnte.

Den privaten Schlüssel schützen

Der private Schlüssel ist ein Projektgeheimnis, keine Kennung. Bewahre ihn in Umgebungsvariablen, in einem Secret-Manager oder in der Serverkonfiguration auf - niemals im Repository, in Logs, auf einem Screenshot oder in Code, der an den Browser geht. Ein Projekt kann mehrere Schlüssel haben, deshalb sollten Produktion und Staging je eigene bekommen: jeder lässt sich einzeln widerrufen, ohne die übrigen zu unterbrechen. Der Verdacht, dass ein Schlüssel abgeflossen ist, genügt, um ihn zu widerrufen und einen neuen zu erzeugen.