Identify users
To associate telemetry data with authenticated users, call Monocle.setUser() in your authentication middleware. This lets you filter traces and exceptions by user in the dashboard.
import type { NextFn } from '@adonisjs/core/types/http'
import type { HttpContext } from '@adonisjs/core/http'
import { Monocle } from '@monocle.sh/adonisjs-agent'
export default class SilentAuthMiddleware {
async handle(ctx: HttpContext, next: NextFn) {
await ctx.auth.check()
if (ctx.auth.user) {
Monocle.setUser({
id: ctx.auth.user.id,
email: ctx.auth.user.email,
name: ctx.auth.user.fullName,
})
}
return next()
}
}The name field takes priority in the Monocle UI, falling back to email, then id.
Do not include sensitive data (passwords, tokens, API keys) in user attributes. These values are sent to Monocle and will be visible in trace viewers.
Automatic exception capture
Exceptions thrown during a request are automatically captured by the agent. It hooks into AdonisJS's ExceptionHandler.report() method and respects your ignore rules (ignoreExceptions, ignoreStatuses, ignoreCodes).
Capture exceptions manually
You can manually capture exceptions anywhere in your code.
import { Monocle } from '@monocle.sh/adonisjs-agent'
try {
await processPayment(order)
} catch (error) {
Monocle.captureException(error, {
user: { id: '123', email: 'user@example.com' },
tags: { component: 'payment' },
extra: { orderId: order.id, amount: order.total },
})
throw error
}Capture messages
Use Monocle.captureMessage() to capture custom messages when you want to track something that is not an exception. Messages are grouped into issues alongside errors.
import { Monocle } from '@monocle.sh/adonisjs-agent'
// Simple message
Monocle.captureMessage('User failed to complete checkout')
// With severity level and context
Monocle.captureMessage('Order processing took too long', {
level: 'warning',
user: { id: '123' },
tags: { feature: 'checkout' },
extra: { orderId: 'order-456', durationMs: 15000 },
})Supported levels: debug, info, log, warning, error, fatal.