Konfiguracja - Python

Opcje, które warto znać

Środowiska

Każde środowisko powinno raportować pod jednoznaczną nazwą - production, staging, preview. Nazwa jest kolumną w panelu i filtrem na liście błędów, więc bez niej awaria z produkcji wygląda dokładnie tak samo jak błąd wywołany w testach. Środowisko lokalne zostaw bez poświadczeń: bez tokenu i klucza integracja ładuje się i milczy, więc nie musisz jej wyłączać osobnym warunkiem.

Kiedy zdarzenia wychodzą

Klient nigdy nie wysyła niczego w trakcie tej części żądania, na którą czeka odwiedzający. send_later() planuje wysyłkę bez czekania na jej zakończenie - metoda zwraca się natychmiast, a zadanie leci dalej w pętli zdarzeń:

client.send_later(client.capture_exception(error))

Zadanie jest trzymane w wewnętrznym zbiorze aż do zakończenia - korutyna, do której odwołuje się wyłącznie pętla zdarzeń, może zostać zebrana przez garbage collector w połowie lotu, co po cichu gubi zdarzenie. Niepowodzenie trafia do loggera dock_ray, a nie w górę stosu wywołań - żadne send_later() nie przerywa działania aplikacji, w której właśnie coś raportuje.

Middleware ASGI działa tym samym rytmem: transakcję raportuje dopiero wtedy, gdy aplikacja skończyła zapisywać odpowiedź. Wolny albo niedostępny panel nie kosztuje odwiedzającego ani milisekundy.

Middleware ASGI i FastAPI

Middleware otwiera jedną transakcję na żądanie i raportuje nieobsłużone wyjątki. Jest napisane wprost pod interfejs ASGI, a nie pod konkretny framework, więc działa pod FastAPI, Starlette i każdą inną aplikacją mówiącą tym protokołem - i nie buforuje odpowiedzi strumieniowych.

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()

Każde żądanie jest raportowane razem z metodą, ścieżką, czasem trwania i kodem odpowiedzi. exclude_paths domyślnie pomija /health i /metrics - ścieżki odpytywane co kilka sekund przez monitoring infrastruktury nie mają wypychać prawdziwego ruchu z listy transakcji. capture_transactions=False wyłącza tę część middleware'u, zostawiając samo raportowanie wyjątków.

HTTPException jest obsługiwany przez samo FastAPI i nigdy nie dociera do middleware'u jako wyjątek - spodziewane odpowiedzi 404 czy 422 nie zamieniają się więc w błędy, tylko trafiają do panelu jako transakcje ze swoim kodem statusu.

Adres IP odwiedzającego middleware czyta z nagłówka X-Forwarded-For albo X-Real-IP, zanim sięgnie po adres gniazda - za load balancerem to gniazdo należy do balancera, nie do odwiedzającego. Z raportowanych nagłówków są wycięte Authorization, Cookie i X-Api-Key.

Ręczne transakcje

Przydają się w zadaniach działających poza żądaniem HTTP, na przykład w workerze w tle:

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])

Ramię źródłowe - to bez parent_span_id - niesie adres, metodę i status, po których panel indeksuje transakcję. Bez tych trzech pól w ramieniu głównym transakcja nie ma po czym trafić na listę.

Ochrona klucza prywatnego

Klucz prywatny jest sekretem projektu, a nie identyfikatorem. Trzymaj go w zmiennych środowiskowych, w menedżerze sekretów albo w konfiguracji serwera - nigdy w repozytorium, w logach, na zrzucie ekranu ani w kodzie wysyłanym do przeglądarki. Jeden projekt może mieć wiele kluczy, więc produkcja i środowisko testowe powinny dostać osobne: każdy odwołuje się niezależnie, bez przerywania raportowania z pozostałych. Podejrzenie ujawnienia klucza jest wystarczającym powodem, aby go odwołać i wygenerować nowy.