EliasOulkadi/shokunin / .pack/skills/error-handler
error-handler
VerifiedDesign error handling, structured logging, and observability with OpenTelemetry (traces, metrics, logs), error classification, recovery patterns (retry with jitter, circuit breaker, bulkhead, timeout), error budgets/SLOs with burn rate alerts, and production incident triage. Use when user asks to implement error handling, logging, monitoring, observability, OpenTelemetry, error boundaries, circuit breakers, retry logic, or SLO tracking. Do NOT use for incident runbooks (use runbook-gen), vendor-specific APM setup (Datadog, Sentry agent config), or K8s debugging.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.0 KB |
| assets/error-middleware.template.ts | script | 11.0 KB |
| references/error-budgets.md | markdown | 14.4 KB |
| references/opentelemetry-deep.md | markdown | 14.5 KB |
| scripts/setup-opentelemetry.sh | script | 6.5 KB |
assets/error-middleware.template.ts
View on GitHub// ─────────────────────────────────────────────────────────────
// Production Express Error Middleware
// Features: OTEL integration, error classification,
// structured logging, status code mapping
// ─────────────────────────────────────────────────────────────
import { Request, Response, NextFunction } from 'express'
import { trace, SpanStatusCode, Span } from '@opentelemetry/api'
import { SemanticAttributes } from '@opentelemetry/semantic-conventions'
import crypto from 'node:crypto'
// ── Error Classes ────────────────────────────────────────────
export class AppError extends Error {
public readonly statusCode: number
public readonly errorCode: string
public readonly isOperational: boolean
public readonly details?: Record<string, unknown>
public readonly retryable: boolean
constructor(
message: string,
statusCode: number,
errorCode: string,
options?: {
isOperational?: boolean
details?: Record<string, unknown>
retryable?: boolean
}
) {
super(message)
this.name = this.constructor.name
this.statusCode = statusCode
this.errorCode = errorCode
this.isOperational = options?.isOperational ?? true
this.details = options?.details
this.retryable = options?.retryable ?? false
Error.captureStackTrace(this, this.constructor)
}
}
export class ValidationError extends AppError {
constructor(message: string, details?: Record<string, unknown>) {
super(message, 400, 'VALIDATION_ERROR', {
isOperational: true,
details,
retryable: false,
})
}
}
export class AuthenticationError extends AppError {
constructor(message = 'Authentication required') {
super(message, 401, 'UNAUTHORIZED', {
isOperational: true,
retryable: false,
})
}
}
export class ForbiddenError extends AppError {
constructor(message = 'Insufficient permissions') {
super(message, 403, 'FORBIDDEN', {
isOperational: true,
retryable: false,
})
}
}
export class NotFoundError extends AppError {
constructor(resource = 'Resource') {
super(`${resource} not found`, 404, 'NOT_FOUND', {
isOperational: true,
retryable: false,
})
}
}
export class ConflictError extends AppError {
constructor(message: string, details?: Record<string, unknown>) {
super(message, 409, 'CONFLICT', {
isOperational: true,
details,
retryable: false,
})
}
}
export class RateLimitError extends AppError {
constructor(message = 'Too many requests') {
super(message, 429, 'RATE_LIMITED', {
isOperational: true,
retryable: true,
})
}
}
export class DownstreamError extends AppError {
public readonly upstreamService: string
public readonly upstreamStatusCode?: number
constructor(
message: string,
upstreamService: string,
options?: { upstreamStatusCode?: number; retryable?: boolean }
) {
super(message, 502, 'DOWNSTREAM_ERROR', {
isOperational: true,
retryable: options?.retryable ?? true,
details: { upstreamService, upstreamStatusCode: options?.upstreamStatusCode },
})
this.upstreamService = upstreamService
this.upstreamStatusCode = options?.upstreamStatusCode
}
}
// ── Status code mapping ──────────────────────────────────────
function isHttpError(statusCode: number): boolean {
return statusCode >= 400 && statusCode < 600
}
function defaultErrorCode(statusCode: number): string {
const map: Record<number, string> = {
400: 'VALIDATION_ERROR',
401: 'UNAUTHORIZED',
403: 'FORBIDDEN',
404: 'NOT_FOUND',
405: 'METHOD_NOT_ALLOWED',
409: 'CONFLICT',
422: 'UNPROCESSABLE_ENTITY',
429: 'RATE_LIMITED',
500: 'INTERNAL_ERROR',
502: 'DOWNSTREAM_ERROR',
503: 'SERVICE_UNAVAILABLE',
504: 'GATEWAY_TIMEOUT',
}
return map[statusCode] || 'UNKNOWN_ERROR'
}
// ── Logger interface ─────────────────────────────────────────
interface ErrorLogEntry {
timestamp: string
level: string
message: string
service: string
trace_id?: string
span_id?: string
error: {
type: string
code: string
message: string
stack?: string
}
context: {
method: string
path: string
route?: string
query?: string
request_id: string
user_id?: string
}
duration_ms?: number
}
interface Logger {
error(entry: ErrorLogEntry): void
warn(entry: Partial<ErrorLogEntry>): void
debug(entry: Partial<ErrorLogEntry>): void
}
// ── Middleware factory ────────────────────────────────────────
interface ErrorMiddlewareOptions {
serviceName: string
logger: Logger
exposeStackTraces?: boolean
sensitivePaths?: RegExp[]
onError?: (err: Error, req: Request, span?: Span) => void
}
const SENSITIVE_FIELDS = ['password', 'secret', 'token', 'authorization', 'credit_card', 'ssn']
function sanitizeHeaders(headers: Record<string, unknown>): Record<string, unknown> {
const sanitized = { ...headers }
for (const field of SENSITIVE_FIELDS) {
if (sanitized[field]) {
sanitized[field] = '[REDACTED]'
}
const lower = field.toLowerCase()
if (sanitized[lower]) {
sanitized[lower] = '[REDACTED]'
}
}
return sanitized
}
export function createErrorMiddleware(options: ErrorMiddlewareOptions) {
const {
serviceName,
logger,
exposeStackTraces = process.env.NODE_ENV !== 'production',
sensitivePaths = [/\/secrets/, /\/tokens/, /\/internal\/debug/],
onError,
} = options
return function errorMiddleware(
err: Error,
req: Request,
res: Response,
_next: NextFunction
): void {
// ── Skip sensitive paths ─────────────────────────────
for (const pattern of sensitivePaths) {
if (pattern.test(req.path)) {
res.status(404).json({ error: { code: 'NOT_FOUND', message: 'Not found' } })
return
}
}
// ── Request ID ────────────────────────────────────────
const requestId = (req.headers['x-request-id'] as string) || crypto.randomUUID()
const startTime = (req as any)._startTime ?? Date.now()
const durationMs = Date.now() - startTime
// ── Active span ───────────────────────────────────────
const activeSpan = trace.getActiveSpan()
if (activeSpan) {
activeSpan.recordException(err)
activeSpan.setStatus({
code: SpanStatusCode.ERROR,
message: err.message,
})
activeSpan.setAttribute(SemanticAttributes.HTTP_STATUS_CODE, res.statusCode)
activeSpan.setAttribute('error.code', getErrorCode(err))
activeSpan.setAttribute('error.type', err.constructor.name)
activeSpan.setAttribute('request_id', requestId)
}
// ── Determine error properties ────────────────────────
let statusCode = 500
let errorCode = 'INTERNAL_ERROR'
let details: Record<string, unknown> | undefined
let isOperational = false
let isRetryable = false
if (err instanceof AppError) {
statusCode = err.statusCode
errorCode = err.errorCode
details = err.details
isOperational = err.isOperational
isRetryable = err.retryable
} else if (isHttpError((err as any).statusCode)) {
statusCode = (err as any).statusCode
errorCode = defaultErrorCode(statusCode)
isOperational = true
} else if (err.name === 'SyntaxError') {
// JSON parse errors from body-parser
statusCode = 400
errorCode = 'VALIDATION_ERROR'
isOperational = true
} else if (err.name === 'TimeoutError' || (err as any).code === 'ETIMEDOUT') {
statusCode = 504
errorCode = 'GATEWAY_TIMEOUT'
isOperational = true
isRetryable = true
}
// ── Structured log entry ──────────────────────────────
const logEntry: ErrorLogEntry = {
timestamp: new Date().toISOString(),
level: statusCode >= 500 ? 'error' : 'warn',
message: err.message,
service: serviceName,
trace_id: activeSpan?.spanContext().traceId,
span_id: activeSpan?.spanContext().spanId,
error: {
type: err.constructor.name,
code: errorCode,
message: err.message,
stack: exposeStackTraces ? err.stack ?? '' : undefined,
},
context: {
method: req.method,
path: req.path,
route: (req as any).route?.path,
query: req.path.includes('?') ? '[REDACTED]' : undefined,
request_id: requestId,
user_id: (req as any).user?.id,
},
duration_ms: durationMs,
}
if (statusCode >= 500) {
logger.error(logEntry)
} else {
logger.warn(logEntry)
}
// ── Callback hook ─────────────────────────────────────
onError?.(err, req, activeSpan ?? undefined)
// ── Response ──────────────────────────────────────────
const body: Record<string, unknown> = {
error: {
code: errorCode,
message: isOperational ? err.message : 'An unexpected error occurred',
request_id: requestId,
},
}
if (details && isOperational) {
body.error['details'] = details
}
// Set retry-after for rate limits
if (statusCode === 429) {
res.setHeader('Retry-After', Math.ceil(60).toString())
}
res.status(statusCode).json(body)
}
}
// ── Utility ──────────────────────────────────────────────────
function getErrorCode(err: Error): string {
if (err instanceof AppError) return err.errorCode
if ((err as any).code) return String((err as any).code)
return 'UNKNOWN'
}
// ── 404 catch-all ────────────────────────────────────────────
export function notFoundHandler(req: Request, _res: Response, next: NextFunction): void {
next(new NotFoundError(req.path))
}
// ── Async handler wrapper ────────────────────────────────────
import { RequestHandler } from 'express'
export function asyncHandler(fn: RequestHandler): RequestHandler {
return (req, res, next) => {
Promise.resolve(fn(req, res, next)).catch(next)
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |