typescript-sdk
Wzorce TypeScript SDK dla Opik — asynchroniczne śledzenie i buffering danych do backendu
Instalacja
Wybierz klienta i sklonuj repozytorium do odpowiedniego katalogu skilli.
Instalacja
O skillu
TypeScript SDK dla Opik to zestaw wzorców architektonicznych do budowania nieblokujących integracji z systemem śledzenia. Biblioteka obsługuje Node.js >= 18, zarówno moduły ESM jak i CommonJS. Dane są buforowane i asynchronicznie wysyłane do backendu poprzez warstwę REST Client. Kluczowe cechy to semantyka batchowania (aktualizacje czekają na tworzenie, usuwania czekają na aktualizacje), obsługa błędów HTTP z dedykowanymi typami wyjątków oraz wymóg jawnego flushu przed wyjściem aplikacji.
Jak używać
Zainstaluj SDK TypeScript dla Opik w swoim projekcie Node.js (wymagana wersja >= 18). Upewnij się, że Twoje środowisko obsługuje zarówno moduły ESM jak i CommonJS.
Zaimportuj publiczny interfejs API z pakietu 'opik' — używaj eksportowanych funkcji takich jak Opik, track i flushAll. Nigdy nie importuj wewnętrznych klientów REST (rest_api) bezpośrednio.
Utwórz instancję OpikClient i skonfiguruj okno debounce'a poprzez OpikConfig zgodnie z potrzebami Twojej aplikacji. Architektura warstw będzie automatycznie obsługiwać buforowanie i asynchroniczne wysyłanie danych.
Używaj obiektów domenowych (Trace, Span) do enqueue'owania operacji — nie wywołuj REST API bezpośrednio z kodu domenowego. Obiekty domenowe automatycznie enqueue'ują aktualizacje i zamknięcia.
Przed wyjściem aplikacji (szczególnie w CLI i testach) jawnie wywołaj await client.flush() lub globalnie await flushAll(), aby upewnić się, że wszystkie zakolejkowane operacje zostaną wysłane do backendu. Semantyka batchowania gwarantuje, że aktualizacje czekają na tworzenie, a usuwania czekają na aktualizacje.
Obsługuj błędy HTTP za pomocą dedykowanych typów wyjątków (OpikApiError, OpikApiTimeoutError) i tłumaczeń 404 na błędy domenowe (DatasetNotFoundError, ExperimentNotFoundError). Zawsze loguj kontekst błędu zamiast go pomijać.