Skip to content

Logging

llmist uses structured logging for debugging and monitoring.

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
Terminal window
# Set log level
export LLMIST_LOG_LEVEL="debug"
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

Use command-line flags:

Terminal window
# 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"
import { LLMist, createLogger } from 'llmist';
const logger = createLogger({
minLevel: 'debug',
});
await LLMist.createAgent()
.withLogger(logger)
.askAndCollect('Your prompt');
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 });

Suppress all logging:

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

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"}
Terminal window
LLMIST_LOG_LEVEL=trace npx @llmist/cli agent "task" 2>&1 | tee debug.log
const logger = createLogger({ minLevel: 'trace' });
await LLMist.createAgent()
.withLogger(logger)
.withGadgets(MyGadget)
.askAndCollect('Test');

Trace output shows:

  • Gadget parameters received
  • Execution timing
  • Return values

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:

Terminal window
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.

const isProd = process.env.NODE_ENV === 'production';
const logger = createLogger({
minLevel: isProd ? 'warn' : 'debug',
});

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');