logging docs
This commit is contained in:
AI Christianson
parent
09bd7cbf4b
commit
c3f32d640d
14
README.md
14
README.md
|
|
@ -29,6 +29,7 @@ Key sections:
|
|||
- [Recommended Configuration](https://docs.ra-aid.ai/quickstart/recommended)
|
||||
- [Open Models Setup](https://docs.ra-aid.ai/quickstart/open-models)
|
||||
- [Usage Examples](https://docs.ra-aid.ai/category/usage)
|
||||
- [Logging System](https://docs.ra-aid.ai/usage/logging)
|
||||
- [Contributing Guide](https://docs.ra-aid.ai/contributing)
|
||||
- [Getting Help](https://docs.ra-aid.ai/getting-help)
|
||||
|
||||
|
|
@ -186,10 +187,10 @@ ra-aid -m "Explain the authentication flow" --research-only
|
|||
ra-aid -m "Add new feature" --log-mode file
|
||||
|
||||
# Console-only logging with detailed output
|
||||
ra-aid -m "Add new feature" --log-mode console
|
||||
ra-aid -m "Add new feature" --log-mode console --log-level debug
|
||||
```
|
||||
|
||||
More information is available in our [Usage Examples](https://docs.ra-aid.ai/category/usage).
|
||||
More information is available in our [Usage Examples](https://docs.ra-aid.ai/category/usage) and [Logging System](https://docs.ra-aid.ai/usage/logging) documentation.
|
||||
|
||||
### Command Line Options
|
||||
|
||||
|
|
@ -207,11 +208,14 @@ More information is available in our [Usage Examples](https://docs.ra-aid.ai/cat
|
|||
- `--hil, -H`: Enable human-in-the-loop mode for interactive assistance during task execution
|
||||
- `--chat`: Enable chat mode with direct human interaction (implies --hil)
|
||||
- `--log-mode`: Logging mode (choices: file, console)
|
||||
- `file`: Logs to both file and console (only warnings+ to console)
|
||||
- `console`: Logs to console only at the specified log level
|
||||
- `file` (default): Logs to both file and console (only warnings and errors to console)
|
||||
- `console`: Logs to console only at the specified log level with no file logging
|
||||
- `--log-level`: Set specific logging level (debug, info, warning, error, critical)
|
||||
- With `--log-mode=file`: Controls the file logging level (console still shows only warnings+)
|
||||
- With `--log-mode=console`: Controls the console logging level directly
|
||||
- Default: warning
|
||||
- `--experimental-fallback-handler`: Enable experimental fallback handler to attempt to fix too calls when the same tool fails 3 times consecutively. (OPENAI_API_KEY recommended as openai has the top 5 tool calling models.) See `ra_aid/tool_leaderboard.py` for more info.
|
||||
- `--pretty-logger`: Enables panel markdown formatted logger messages for debugging purposes.
|
||||
- `--pretty-logger`: Enables colored panel-style formatted logging output for better readability.
|
||||
- `--temperature`: LLM temperature (0.0-2.0) to control randomness in responses
|
||||
- `--disable-limit-tokens`: Disable token limiting for Anthropic Claude react agents
|
||||
- `--recursion-limit`: Maximum recursion depth for agent operations (default: 100)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,23 @@
|
|||
# Getting Help
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
Before seeking external help, check the following:
|
||||
|
||||
### Check the Logs
|
||||
|
||||
RA.Aid maintains detailed logs that can help diagnose many common issues. By default, logs are stored in the `.ra-aid/logs/` directory in your working directory.
|
||||
|
||||
1. Check the most recent log file in `.ra-aid/logs/` directory
|
||||
2. Look for ERROR or WARNING level messages that might indicate what went wrong
|
||||
3. For more detailed logging options, see the [Logging documentation](/usage/logging)
|
||||
|
||||
### Common Problems
|
||||
|
||||
- **Error connecting to API**: Verify your API key is set correctly
|
||||
- **Command not found**: Ensure RA.Aid is installed properly and in your PATH
|
||||
- **Script execution failures**: Check that required dependencies are installed
|
||||
|
||||
## Bug Reports and Feature Requests
|
||||
|
||||
If you encounter any issues or have ideas for improvements, please file them on our [GitHub Issues page](https://github.com/ai-christianson/RA.Aid/issues).
|
||||
|
|
|
|||
|
|
@ -54,3 +54,15 @@ Or run with a single command:
|
|||
```bash
|
||||
ra-aid -m "Help me understand this code"
|
||||
```
|
||||
|
||||
You can control logging verbosity and location using the `--log-mode` and `--log-level` options:
|
||||
|
||||
```bash
|
||||
# Log to file (with only warnings to console)
|
||||
ra-aid -m "Your task" --log-mode file --log-level debug
|
||||
|
||||
# Log everything to console
|
||||
ra-aid -m "Your task" --log-mode console --log-level info
|
||||
```
|
||||
|
||||
For more detailed logging configuration, see the [Logging documentation](../usage/logging.md).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,167 @@
|
|||
# Logging System
|
||||
|
||||
RA.Aid includes a powerful and flexible logging system that helps you troubleshoot issues and monitor the tool's operation. This document explains how to configure and use the logging features effectively.
|
||||
|
||||
## Overview
|
||||
|
||||
The logging system in RA.Aid provides:
|
||||
|
||||
- Configurable logging modes for different use cases
|
||||
- Multiple log levels for controlling verbosity
|
||||
- File logging with rotation and backup capabilities
|
||||
- Pretty console logging with formatted display
|
||||
- Comprehensive log messages capturing agent activity
|
||||
|
||||
## Command Line Options
|
||||
|
||||
RA.Aid provides the following command line options to control logging behavior:
|
||||
|
||||
### Log Mode
|
||||
|
||||
The `--log-mode` option determines where logs are directed:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --log-mode file
|
||||
```
|
||||
|
||||
Available modes:
|
||||
|
||||
- `file` (default): Logs are written to both file and console
|
||||
- Console shows only warnings and errors
|
||||
- File contains all logs at the specified log level
|
||||
- `console`: Logs are only shown in the console at the specified log level
|
||||
- No log files are created
|
||||
|
||||
### Log Level
|
||||
|
||||
The `--log-level` option controls the verbosity of logging:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --log-level debug
|
||||
```
|
||||
|
||||
Available levels (case-insensitive):
|
||||
|
||||
- `debug`: Most verbose, includes detailed debugging information
|
||||
- `info`: General information about operations
|
||||
- `warning` (default): Potential issues that might need attention
|
||||
- `error`: Error conditions that prevent normal operation
|
||||
- `critical`: Critical errors that may cause the application to terminate
|
||||
|
||||
The log level affects different outputs depending on the log mode:
|
||||
- With `--log-mode=file`: Controls the file logging level, while console still shows only warnings and errors
|
||||
- With `--log-mode=console`: Controls the console logging level directly
|
||||
|
||||
### Pretty Logger
|
||||
|
||||
The `--pretty-logger` option enables formatted panel-style logging output:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --pretty-logger
|
||||
```
|
||||
|
||||
When enabled, log messages appear in colored panels with titles indicating the log level:
|
||||
- 🔥 CRITICAL: Bold red panels for critical errors
|
||||
- ❌ ERROR: Red panels for errors
|
||||
- ⚠️ WARNING: Yellow panels for warnings
|
||||
- ℹ️ INFO: Green panels for informational messages
|
||||
- 🐞 DEBUG: Blue panels for debug messages
|
||||
|
||||
## Log Files
|
||||
|
||||
When `--log-mode=file` is used, RA.Aid creates and maintains log files with the following characteristics:
|
||||
|
||||
### Location
|
||||
|
||||
Log files are stored in the `.ra-aid/logs/` directory in your current working directory:
|
||||
|
||||
```
|
||||
.ra-aid/logs/ra_aid_YYYYMMDD_HHMMSS.log
|
||||
```
|
||||
|
||||
RA.Aid automatically creates this directory if it doesn't exist.
|
||||
|
||||
### Naming Convention
|
||||
|
||||
Log files follow a timestamp-based naming pattern:
|
||||
|
||||
```
|
||||
ra_aid_YYYYMMDD_HHMMSS.log
|
||||
```
|
||||
|
||||
Where:
|
||||
- `YYYYMMDD`: Year, month, and day when the log file was created
|
||||
- `HHMMSS`: Hour, minute, and second when the log file was created
|
||||
|
||||
Example: `ra_aid_20250301_143027.log`
|
||||
|
||||
### Log Rotation
|
||||
|
||||
RA.Aid uses automatic log rotation to manage log file size and prevent excessive disk usage:
|
||||
|
||||
- Maximum file size: 5 MB
|
||||
- Maximum backup files: 100
|
||||
|
||||
When a log file reaches 5 MB, it is renamed with a numeric suffix (e.g., `.1`, `.2`), and a new log file is created. Up to 100 backup files are maintained.
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Usage (Default)
|
||||
|
||||
Use the default file logging mode with warnings and errors:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature"
|
||||
```
|
||||
|
||||
### Detailed File Logging
|
||||
|
||||
Log everything including debug messages to file (console still shows only warnings+):
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --log-level debug
|
||||
```
|
||||
|
||||
### Console-Only Debugging
|
||||
|
||||
Get detailed debug logs in the console without creating log files:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --log-mode console --log-level debug
|
||||
```
|
||||
|
||||
### Informational Console Logging
|
||||
|
||||
Get informational console output without debug details:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --log-mode console --log-level info
|
||||
```
|
||||
|
||||
### Pretty Logging Output
|
||||
|
||||
Use formatted panel-style logging for better readability:
|
||||
|
||||
```bash
|
||||
ra-aid -m "Add new feature" --pretty-logger
|
||||
```
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
- For troubleshooting issues, start with `--log-mode console --log-level debug`
|
||||
- Examine log files in `.ra-aid/logs/` for historical issues
|
||||
- Use `--pretty-logger` when working with complex tasks for better log clarity
|
||||
- For production use, the default settings (`--log-mode file --log-level warning`) provide a good balance of information without excessive output
|
||||
|
||||
## Log Message Format
|
||||
|
||||
Standard log messages follow this format:
|
||||
|
||||
```
|
||||
YYYY-MM-DD HH:MM:SS,MS - logger_name - LEVEL - Message text
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
2025-03-01 14:30:27,123 - ra_aid.agent_utils - WARNING - Command execution timeout after 60 seconds
|
||||
```
|
||||
|
|
@ -5,7 +5,7 @@ import type * as Preset from '@docusaurus/preset-classic';
|
|||
const config: Config = {
|
||||
title: 'RA-Aid Documentation',
|
||||
favicon: 'img/favicon.ico',
|
||||
url: 'https://ra-aid.0.dev',
|
||||
url: 'https://docs.ra-aid.ai',
|
||||
baseUrl: '/',
|
||||
|
||||
onDuplicateRoutes: 'ignore',
|
||||
|
|
|
|||
Loading…
Reference in New Issue