clerk-observability

Skill do implementacji monitorowania, logowania i obserwacji autentykacji Clerk. Pozwala ustawić strukturalne logowanie zdarzeń auth, śledzić wydajność middleware'u, monitorować webhook'i, integrować się z Sentry oraz tworzyć endpointy health check. Idealny do debugowania problemów auth w produkcji i wdrażania audit logging. Kompatybilny z Claude Code, Codex i OpenClaw.

1. Upewnij się, że masz już działającą integrację Clerk oraz platformę monitorowania (Sentry, DataDog lub Pino logger). Przygotuj infrastrukturę logowania — zalecane są strukturalne logi JSON.

2. Wdróż strukturalne logowanie zdarzeń autentykacji, tworząc moduł auth-logger.ts z biblioteką Pino. Skonfiguruj logger z odpowiednim poziomem logowania (info/debug) i transportem — w development użyj pino-pretty, w produkcji JSON. Dodaj funkcje logAuthEvent() do rejestrowania zdarzeń (sign_in, sign_out, sign_up, permission_denied, session_expired) z userId, orgId i metadanymi.

3. Zaimplementuj middleware performance monitoring w pliku middleware.ts, aby śledzić czas odpowiedzi Clerk middleware i rejestrować opóźnienia. Pozwoli to szybko identyfikować wąskie gardła w procesie autentykacji.

4. Skonfiguruj monitorowanie webhook'ów Clerk — dodaj logowanie dla każdego zdarzenia webhook'a (user.created, session.ended itp.) z timestampem i pełnym payload'em. To umożliwi audyt i debugowanie zdarzeń w real-time.

5. Zintegruj Sentry lub inną platformę error tracking, aby automatycznie rejestrować błędy autentykacji z kontekstem (userId, path, stack trace). Funkcja logAuthError() powinna wysyłać błędy do Sentry z pełnym kontekstem.

6. Utwórz health check endpoint, który sprawdza status Clerk API i infrastruktury logowania. Endpoint powinien zwracać status wszystkich zintegrowanych serwisów monitorowania.