Logging

Use ctx.logger in agents and c.var.logger in routes for structured logging. Logs are automatically tied to session IDs for debugging.

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

Log Levels

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

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

Levels from most to least verbose: trace → debug → info → warn → error → fatal. The default minimum level is info.

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

Structured Logging

Pass context as a second argument for searchable metadata:

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

This creates structured log entries you can filter and search in the Agentuity App or the CLI.

Child Loggers

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

const dbLogger = ctx.logger.child({ component: 'database', requestId: ctx.sessionId });
dbLogger.info('Query executed', { duration: 45, rows: 10 });
// 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.info('Webhook received', {
    provider: 'stripe',
    eventType,
  });
 
  const payload = await c.req.json();
 
  const result = await paymentHandler.run({
    event: eventType,
    customerId: payload.customer,
    amount: payload.amount,
  });
 
  c.var.logger.info('Webhook processed', {
    eventType,
    customerId: payload.customer,
    success: result.success,
  });
 
  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 full level table and defaults.

Viewing Logs

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

See Viewing Logs for the full CLI commands.

Best Practices

• Use ctx.logger: Always use ctx.logger or c.var.logger instead of console.log for proper log collection
• Add context: Include IDs, counts, and timing in structured fields
• 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