Skip to main content
clerk-observability Implement monitoring, logging, and observability for Clerk authentication.
Use when setting up monitoring, debugging auth issues in production,
or implementing audit logging.
Trigger with phrases like "clerk monitoring", "clerk logging",
"clerk observability", "clerk metrics", "clerk audit log".
Aller à l'installation Skills Marketplace Découvrez et explorez les compétences IA créées par la communauté.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Afficher les détails du prompt Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill clerk-observabilityLa commande reste sur une seule ligne. Faites défiler horizontalement pour la vérifier avant de la copier.
Vous préférez une copie locale ? Téléchargez les fichiers actuellement disponibles dans SkillsMP.
Télécharger Zip Téléchargement... Métiers associés SOC
Basé sur la classification professionnelle SOC
Plus depuis ce dépôt Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
Explorateur de fichiers
2 fichiers name clerk-observability description Implement monitoring, logging, and observability for Clerk authentication.
Use when setting up monitoring, debugging auth issues in production,
or implementing audit logging.
Trigger with phrases like "clerk monitoring", "clerk logging",
"clerk observability", "clerk metrics", "clerk audit log".
allowed-tools Read, Write, Edit, Bash(npm:*), Grep version 1.14.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","clerk","monitoring","observability","debugging"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
Clerk Observability
Overview
Implement monitoring, logging, and observability for Clerk authentication. Covers structured auth logging, middleware performance tracking, webhook event monitoring, Sentry integration, and health check endpoints.
Prerequisites
Clerk integration working
Monitoring platform (Sentry, DataDog, or Pino logger at minimum)
Logging infrastructure (structured JSON logs recommended)
Instructions
Step 1: Structured Authentication Event Logging
import pino from 'pino'
const logger = pino ({
level : process.env .LOG_LEVEL || 'info' ,
transport : process.env .NODE_ENV === 'development' ? { target : 'pino-pretty' } : undefined ,
})
export function logAuthEvent (event : {
type : 'sign_in' | 'sign_out' | 'sign_up' | 'permission_denied' | 'session_expired'
userId?: string | null
orgId?: string | null
path: string
metadata?: Record<string , any >
}info ({
category : 'auth' ,
...event,
timestamp : new Date ().toISOString (),
})
}
export
function
logAuthError
error : Error , context : { userId?: string ; path: string }
error
category
'auth'
error
message
stack
stack
timestamp
new
Date
toISOString
Step 2: Middleware Performance Monitoring
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
const isPublicRoute = createRouteMatcher (['/' , '/sign-in(.*)' , '/sign-up(.*)' ])
export default clerkMiddleware (async (auth, req) => {
const start = Date .now ()
if (!isPublicRoute (req)) {
await auth.protect ()
}
const duration = Date .now () - start
const { userId } = await auth ()
if (duration > 100 ) {
console .warn (`[Auth Perf] ${req.nextUrl.pathname} took ${duration} ms` , {
userId : userId || 'anonymous' ,
method : req.method ,
})
}
const response = new Response (null , { status : 200 })
response.headers .set ('X-Auth-Duration' , `${duration} ms` )
})
Step 3: Webhook Event Tracking
import { logAuthEvent } from '@/lib/auth-logger'
async function handleWebhookEvent (evt : WebhookEvent const startTime = Date .now ()
const metrics = {
eventType : evt.type ,
receivedAt : new Date ().toISOString (),
processingTimeMs : 0 ,
}
switch (evt.type ) {
case 'user.created' :
logAuthEvent ({
type : 'sign_up' ,
userId : evt.data .id ,
path : '/webhooks/clerk' ,
metadata : { email : evt.data .email_addresses [0 ]?.email_address },
})
await db.user .create ({ data : { clerkId : evt.data .id } })
break
case 'session.created' :
logAuthEvent ({
type : 'sign_in' ,
userId : evt.data .user_id ,
path : '/webhooks/clerk' ,
})
break
case 'session.ended' :
logAuthEvent ({
type : 'sign_out' ,
userId : evt.data .user_id ,
path : '/webhooks/clerk' ,
})
break
}
metrics.processingTimeMs = Date .now () - startTime
if (metrics.processingTimeMs > 5000 ) {
console .error ('[Webhook] Slow processing:' , metrics)
}
return Response .json ({ received : true })
}
Step 4: Sentry Error Tracking Integration
import * as Sentry from '@sentry/nextjs'
import { auth, currentUser } from '@clerk/nextjs/server'
export async function initSentryUser (const { userId, orgId } = await auth ()
if (userId) {
const user = await currentUser ()
Sentry .setUser ({
id : userId,
email : user?.emailAddresses [0 ]?.emailAddress ,
username : user?.username || undefined ,
})
Sentry .setTag ('org_id' , orgId || 'personal' )
}
}
export function withAuthSentry (handler : Function return async (...args : any []) => {
await initSentryUser ()
try {
return await handler (...args)
} catch (error) {
Sentry .captureException (error)
throw error
}
}
}
import * as Sentry from '@sentry/nextjs'
Sentry .init ({
dsn : process.env .SENTRY_DSN ,
tracesSampleRate : 0.1 ,
beforeSend (event ) {
if (event.extra ) {
delete event.extra ['CLERK_SECRET_KEY' ]
}
return event
},
})
Step 5: Health Check Endpoint
import { clerkClient } from '@clerk/nextjs/server'
export async function GET (const checks : Record <string , { status : string ; latencyMs : number ; detail ?: string }> = {}
const clerkStart = Date .now ()
try {
const client = await clerkClient ()
await client.users .getUserList ({ limit : 1 })
checks.clerk = { status : 'healthy' , latencyMs : Date .now () - clerkStart }
} catch (err : any ) {
checks.clerk = { status : 'unhealthy' , latencyMs : Date .now () - clerkStart, detail : err.message }
}
const dbStart = Date .now ()
try {
await db.$queryRaw `SELECT 1`
checks.database = { status : 'healthy' , latencyMs : Date .now () - dbStart }
} catch (err : any ) {
checks.database = { status : 'unhealthy' , latencyMs : Date .now () - dbStart, detail : err.message }
}
const allHealthy = Object .values (checks).every ((c ) => c.status === 'healthy' )
return Response .json (
{ status : allHealthy ? 'healthy' : 'degraded' , checks, timestamp : new Date ().toISOString () },
{ status : allHealthy ? 200 : 503 }
)
}
Step 6: Dashboard Metrics Query
import { auth } from '@clerk/nextjs/server'
export async function GET (const { has } = await auth ()
if (!has ({ role : 'org:admin' })) {
return Response .json ({ error : 'Forbidden' }, { status : 403 })
}
const now = new Date ()
const dayAgo = new Date (now.getTime () - 24 * 60 * 60 * 1000 )
const metrics = {
signIns24h : await db.auditLog .count ({
where : { action : 'sign_in' , timestamp : { gte : dayAgo } },
}),
signUps24h : await db.auditLog .count ({
where : { action : 'sign_up' , timestamp : { gte : dayAgo } },
}),
authErrors24h : await db.auditLog .count ({
where : { action : 'permission_denied' , timestamp : { gte : dayAgo } },
}),
webhookEvents24h : await db.webhookEvent .count ({
where : { processedAt : { gte : dayAgo } },
}),
}
return Response .json (metrics)
}
Output
Structured auth event logging with Pino (sign-in, sign-out, sign-up, errors)
Middleware performance tracking with slow-request alerts
Webhook event monitoring with processing time metrics
Sentry integration with Clerk user context
Health check endpoint monitoring Clerk API and database
Admin metrics endpoint for auth dashboard
Error Handling Issue Monitoring Action High auth latency (p95 > 200ms) Alert via middleware timing logs, investigate caching Webhook failure rate > 1% Alert on processing errors, check endpoint health Session anomalies Track unusual sign-in patterns via audit log Clerk API errors Capture with Sentry context, check status.clerk.com
Examples
Quick Monitoring One-Liner
LOG_LEVEL=debug npm run dev 2>&1 | grep '"category":"auth"'
Resources
Next Steps Proceed to clerk-incident-runbook for incident response procedures.
