# Logging

MindedJS provides a structured logging system that helps you monitor, debug, and audit your agent's behavior. The logger is available throughout your agent code and provides consistent, contextual logging with proper PII handling.

## Using the Logger

Import the logger from MindedJS:

```ts
import { logger } from 'mindedjs';
```

The logger is also available in all tool contexts, so you can use it directly in your tools without importing.

## Log Levels

The logger supports standard log levels:

```ts
// Info level - general information
logger.info('Processing customer request');

// Warning level - potential issues
logger.warn('Customer tier not found, using default');

// Error level - errors and exceptions
logger.error('Failed to process payment');

// Debug level - detailed debugging information
logger.debug('Memory state updated');
```

## Structured Logging

Use structured logging with contextual data for better observability. Pass the message as the `msg` property:

```ts
// Basic structured logging
logger.info({
  msg: 'Order refunded',
  orderId: 'ORD-123',
  customerId: 'CUST-456',
  amount: 99.99,
});

// Include session context in tools
logger.info({
  msg: 'Tool execution started',
  sessionId: state.sessionId,
  toolName: 'refundOrder',
  orderId: input.orderId,
});
```

## Log Configuration

The logger can be configured through environment variables:

```env
# Set log level (debug, info, warn, error)
LOG_LEVEL=info

# In development, you might want debug level
LOG_LEVEL=debug
```

## Best Practices

1. **Always Include Session Context**: Include `sessionId` in all tool-related logs
2. **Use Appropriate Log Levels**: Don't use `info` for debugging information
3. **Structure Your Data**: Use objects for structured logging rather than strings
4. **Log State Changes**: Log important state transitions and memory updates
5. **Error Context**: Use `err` parameter for error objects to get proper stack traces
6. **Performance Metrics**: Log timing information for performance monitoring