Loading...
Loading...
Best practices and guidelines for using logger in API routes. Defines appropriate logging levels, what to log, and when to avoid logging. Use when implementing or reviewing API route logging, debugging strategies, or optimizing log output.
npx skill4agent add inkeep/agents api-logging-guidelines// ❌ BAD - Request details are already logged by middleware
logger.info({ tenantId, projectId }, 'Getting project details');| Level | Use Case | Examples |
|---|---|---|
| ERROR | Unexpected failures requiring attention | Database connection failures, unhandled exceptions, critical service errors |
| WARN | Recoverable issues or concerning patterns | Rate limiting triggered, deprecated API usage, fallback behavior activated |
| INFO | Important business events (NOT routine operations) | User account created, payment processed, critical configuration changed |
| DEBUG | Detailed diagnostic information | Query parameters, intermediate calculations, cache hit/miss details |
// ✅ GOOD - Important business event
logger.info({
userId,
oldPlan: 'free',
newPlan: 'pro',
mrr: 99
}, 'User upgraded subscription');
// ✅ GOOD - Error with context
logger.error({
error,
tenantId,
webhookUrl,
attemptNumber: 3
}, 'Webhook delivery failed after retries');
// ✅ GOOD - Security-relevant event
logger.warn({
ip: c.req.header('x-forwarded-for'),
userId,
attemptedResource
}, 'Unauthorized access attempt');
// ✅ GOOD - Performance issue
logger.warn({
duration: 5234,
query,
resultCount: 10000
}, 'Slow query detected');// ❌ BAD - Routine CRUD operation
logger.info('Getting user by ID');
// ❌ BAD - Already logged by middleware
logger.info(`Processing GET request to /api/users/${id}`);
// ❌ BAD - No actionable information
logger.info('Starting database query');
// ❌ BAD - Sensitive information
logger.info({ password, apiKey }, 'User login attempt');
// ❌ BAD - Overly granular
logger.debug('Entering function processUser');
logger.debug('Exiting function processUser');// ✅ GOOD - Log errors with context
export const route = router.get('/:id', async (c) => {
try {
const result = await riskyOperation();
return c.json(result);
} catch (error) {
// Log error with relevant context
logger.error({
error,
userId: c.get('userId'),
operation: 'riskyOperation',
// Include any relevant debugging context
requestId: c.get('requestId')
}, 'Operation failed');
// Return generic error to client (don't leak internals)
return c.json({ error: 'Internal server error' }, 500);
}
});// ✅ GOOD - Log significant business events
export const route = router.post('/subscription/upgrade', async (c) => {
const { planId } = await c.req.json();
const result = await upgradeSubscription(userId, planId);
// This is worth logging - it's a significant business event
logger.info({
userId,
oldPlan: result.previousPlan,
newPlan: result.newPlan,
mrr: result.mrr,
timestamp: new Date().toISOString()
}, 'Subscription upgraded');
return c.json(result);
});// ✅ GOOD - Log performance issues
export const route = router.get('/search', async (c) => {
const start = Date.now();
const results = await performSearch(query);
const duration = Date.now() - start;
// Only log if performance is concerning
if (duration > 1000) {
logger.warn({
duration,
query,
resultCount: results.length,
cached: false
}, 'Slow search query');
}
return c.json(results);
});// ✅ GOOD - Log security-relevant events
export const route = router.post('/api/admin/*', async (c) => {
const hasPermission = await checkPermission(userId, resource);
if (!hasPermission) {
// Log unauthorized access attempts
logger.warn({
userId,
resource,
ip: c.req.header('x-forwarded-for'),
userAgent: c.req.header('user-agent')
}, 'Unauthorized access attempt');
return c.json({ error: 'Forbidden' }, 403);
}
// Proceed with authorized request...
});// More verbose logging acceptable in development
if (process.env.NODE_ENV === 'development') {
logger.debug({ params, body }, 'Request details');
}router.get('/:id', async (c) => {
const { id } = c.req.param();
logger.info({ id }, 'Getting item by ID'); // Redundant
const item = await getItem(id);
logger.info({ item }, 'Retrieved item'); // Too verbose
return c.json(item);
});router.get('/:id', async (c) => {
const { id } = c.req.param();
try {
const item = await getItem(id);
// No logging needed - routine successful operation
return c.json(item);
} catch (error) {
// Only log errors
logger.error({ error, id }, 'Failed to retrieve item');
return c.json({ error: 'Item not found' }, 404);
}
});