Archery Logger

Every web application needs reliable logging to monitor health and trace errors during production. Archery comes equipped with a centralized, multi-transport logging facility out of the box.

The Logger

The Archery Logger supports hierarchical context, structured JSON logging, and async fault-tolerant delivery.

You can access the application's global logger from anywhere via the Application container:

final logger = App().archeryLogger;

await logger.info('User successfully registered', {
  'user_id': user.id
});

Log Levels

Archery supports standard severity levels, ranked from most to least severe:

1. error: Critical issues where the application may not continue.
2. success: Successful significant operations.
3. warning: Non-fatal issues requiring attention.
4. info: General informational messages.
5. debug: Diagnostic information.
6. trace: Fine-grained tracing for development.

await logger.error('Database connection failed', {'error': e.toString()});
await logger.success('Payment processed');
await logger.debug('Processing queue batch');

Contextual Loggers

You may want to attach shared context to a sequence of logs, such as a Request ID in middleware. Archery allows you to spawn child loggers with inherited context:

final requestLogger = App().archeryLogger.child({'request_id': 'abc123'});

await requestLogger.info('Incoming request');
// {"message":"Incoming request","context":{"request_id":"abc123"}}

Log Transports

Archery's Logger dispatches entries to one or more LogTransport instances. The framework provides default transports for console output and file rotation.

Console Transport

The ConsoleTransport writes beautifully formatted ANSI-colored logs to stdout. You can optionally instruct it to output raw JSON strings, which is ideal if you are piping your container's stdout to an aggregator like Datadog or ELK.

Note: The Console transport silently drops all logs when your application's config app.debug is disabled, preventing verbose console spam in production.

// Colored human-readable output
final transport = ConsoleTransport(useColors: true);

// JSON Lines output
final jsonTransport = ConsoleTransport(formatJson: true);

File Transport

The LogFileTransport appends logs to a local disk file as JSON Lines (one JSON object per line), supporting automatic file rotation when a file reaches a maximum threshold.

final fileTransport = LogFileTransport(
  filePath: 'storage/logs/app.log',
  maxFileSize: 10 * 1024 * 1024, // 10 MB limit
  maxFiles: 5,                   // Keep 5 rotated files
);