Logging

Use ctx.logger in agents and c.var.logger in routes for collected logs. Use child loggers for fields that should be attached as log attributes. In deployed apps, session logs are available through the CLI and the Agentuity Console.

For the full Logger interface, all method signatures, and OpenTelemetry tracing, see Observability Reference.

Log Levels

ctx.logger has methods for each configured level: trace, debug, info, warn, and error. Use the method that matches severity:

ctx.logger.child({ requestId: '123' }).info('Request processed');
ctx.logger.error('Failed to fetch data', error);

Configured levels from most to least verbose: trace, debug, info, warn, and error. The default minimum level is info. fatal() is also available, but it logs through error() and exits the process.

For the complete Logger interface and all method signatures, see Observability Reference.

Context Fields

Attach searchable fields with child loggers:

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('ProductSearch', {
  handler: async (ctx, input) => {
    const startTime = Date.now();
    const searchLogger = ctx.logger.child({
      query: input.query,
      userId: input.userId,
    });
 
    const results = await searchProducts(input.query);
 
    searchLogger.child({
      resultCount: results.length,
      durationMs: Date.now() - startTime,
    }).info('Search completed');
 
    return { results };
  },
});

Additional arguments passed to info(), warn(), or error() are formatted into the log message body. Use ctx.logger.child(fields) when fields should be emitted as log attributes.

Child Loggers

ctx.logger.child(fields) creates a scoped logger that attaches the given fields to every log line it emits:

const dbLogger = ctx.logger.child({ component: 'database', requestId: ctx.sessionId });
dbLogger.child({ duration: 45, rows: 10 }).info('Query executed');
// Every line includes component and requestId automatically

See Creating Child Loggers for nesting patterns.

Logging in Routes

Routes access the logger via c.var.logger:

import { Hono } from 'hono';
import type { Env } from '@agentuity/runtime';
 
import paymentHandler from '@agent/payment-handler/agent';
 
const router = new Hono<Env>();
 
router.post('/webhooks/payments', async (c) => {
  const eventType = c.req.header('x-webhook-event');
 
  c.var.logger.child({
    provider: 'stripe',
    eventType,
  }).info('Webhook received');
 
  const payload = await c.req.json();
 
  const result = await paymentHandler.run({
    event: eventType,
    customerId: payload.customer,
    amount: payload.amount,
  });
 
  c.var.logger.child({
    eventType,
    customerId: payload.customer,
    success: result.success,
  }).info('Webhook processed');
 
  return c.json({ received: true });
});
 
export default router;

Configuration

Control the minimum log level with AGENTUITY_LOG_LEVEL in your .env:

AGENTUITY_LOG_LEVEL=debug

See Log Configuration for the SDK reference section.

Viewing Logs

In dev mode, logs stream directly to your terminal. In deployed environments, use agentuity cloud session logs <session-id> or the Agentuity Console session timeline.

See Session Logs for the full CLI commands.

Best Practices

• Use ctx.logger: Use ctx.logger or c.var.logger instead of console.log for proper log collection
• Add context: Use child logger fields for searchable IDs, counts, and timing
• Use appropriate levels: info for normal flow, warn for recoverable issues, error for failures
• Create child loggers: For complex operations, create component-specific loggers

Next Steps

• Tracing: Track timing and debug performance with OpenTelemetry spans
• Sessions & Debugging: Use session IDs to trace issues across logs and spans