Logging

llmist uses structured logging for debugging and monitoring.

Log Levels

| Level | Priority | Use Case | |-------|----------|----------| | silly | 0 | Most verbose, internal state dumps | | trace | 1 | Detailed execution flow | | debug | 2 | Debugging information | | info | 3 | General operational info | | warn | 4 | Warnings (default) | | error | 5 | Errors that may need attention | | fatal | 6 | Critical failures |

Environment Variables

# Set log level
export LLMIST_LOG_LEVEL="debug"

Variable Reference

| Variable | Description | Default | |----------|-------------|---------| | LLMIST_LOG_LEVEL | Minimum log level | warn | | LLMIST_LOG_FILE | Write logs to a file instead of console | none | | LLMIST_LOG_RESET | Truncate log file on startup (true/false) | false | | LLMIST_LOG_TEE | Also write to stdout when file logging is active (true/false) | false |

CLI Logging

Use command-line flags:

    # Set log level
    npx @llmist/cli agent "task" --log-level debug

    # Enable trace for maximum verbosity
    npx @llmist/cli agent "task" --log-level trace

Or configure in ~/.llmist/cli.toml:

[agent]
log-level = "debug"

Programmatic Configuration

Using .withLogger()

import { LLMist, createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
});

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Your prompt');

Custom Logger

import { createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
  name: 'my-app',
});

// Log directly
logger.debug('Custom message', { data: 'value' });
logger.info('Agent started');
logger.error('Something failed', { error });

Silent Mode

Suppress all logging:

const logger = createLogger({
  minLevel: 'fatal', // Only fatal errors
});

Log Output Format

Console output:

[2024-01-15 10:23:45] DEBUG (llmist): LLM call started
  model: "anthropic:claude-sonnet-4-5"
  messageCount: 3
[2024-01-15 10:23:46] DEBUG (llmist): LLM call complete
  tokens: { input: 150, output: 80 }
  duration: 1234

File output (structured JSON):

{"level":"debug","time":"2024-01-15T10:23:45.123Z","msg":"LLM call started","model":"anthropic:claude-sonnet-4-5"}

Debugging with Logs

Capture LLM Interactions

    LLMIST_LOG_LEVEL=trace npx @llmist/cli agent "task" 2>&1 | tee debug.log

Debug Gadget Execution

const logger = createLogger({ minLevel: 'trace' });

await LLMist.createAgent()
  .withLogger(logger)
  .withGadgets(MyGadget)
  .askAndCollect('Test');

Trace output shows:

Gadget parameters received
Execution timing
Return values

File Logging with Console Tee

When running in containers (Docker, Kubernetes), you often need logs in both a file (for upload/archival) and stdout (for docker logs / log aggregation). Use teeToConsole to write to both:

import { createLogger } from 'llmist';

// Programmatic option
const logger = createLogger({
  minLevel: 'debug',
  teeToConsole: true,
});

Or via environment variables:

export LLMIST_LOG_FILE="/tmp/session.log"
export LLMIST_LOG_TEE="true"

File output is stripped of ANSI colors for clean plaintext; console output preserves colors.

Production Logging

const isProd = process.env.NODE_ENV === 'production';

const logger = createLogger({
  minLevel: isProd ? 'warn' : 'debug',
});

Integration with External Loggers

Wrap external loggers:

import pino from 'pino';

const pinoLogger = pino({ level: 'debug' });

// Create adapter
const logger = {
  debug: (msg, data) => pinoLogger.debug(data, msg),
  info: (msg, data) => pinoLogger.info(data, msg),
  warn: (msg, data) => pinoLogger.warn(data, msg),
  error: (msg, data) => pinoLogger.error(data, msg),
};

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Task');