Sumanshu Arora

# logs **View and monitor deployment logs with filtering, streaming, and analysis capabilities.** ## Synopsis ```bash mcpt logs TEMPLATE [OPTIONS] ``` ## Description The `logs` command provides comprehensive log viewing and monitoring for deployed MCP server templates. It supports real-time log streaming, historical log analysis, filtering by severity levels, and formatted output for debugging and monitoring purposes. ## Arguments | Argument | Description | |----------|-------------| | `TEMPLATE` | Name of the deployed template to view logs for | ## Options | Option | Description | Default | |--------|-------------|---------| | `--follow, -f` | Follow log output in real-time | Static view | | `--tail N` | Show last N lines | All lines | | `--since DURATION` | Show logs since duration (e.g., 1h, 30m, 2d) | All logs | | `--until TIMESTAMP` | Show logs until timestamp | Current time | | `--level {debug,info,warn,error}` | Filter by log level | All levels | | `--grep PATTERN` | Filter logs matching pattern | No filter | | `--format {auto,json,plain}` | Output format | `auto` | | `--no-color` | Disable colored output | Colored output | ## Examples ### Basic Usage ```bash # View all logs for demo template mcpt logs demo # Example output: 2024-01-15 10:30:45 [INFO] MCP Server starting on stdio transport 2024-01-15 10:30:45 [INFO] Registered tool: say_hello 2024-01-15 10:30:45 [INFO] Registered tool: get_server_info 2024-01-15 10:30:45 [INFO] Registered tool: echo_message 2024-01-15 10:30:45 [INFO] Server ready to accept connections 2024-01-15 10:32:12 [INFO] Client connected via stdio 2024-01-15 10:32:15 [INFO] Tool called: say_hello(name="World") 2024-01-15 10:32:15 [INFO] Tool result: Hello, World! ``` ### Real-time Monitoring ```bash # Follow logs in real-time mcpt logs demo --follow # Follow with tail (last 50 lines + new ones) mcpt logs demo --follow --tail 50 # Monitor specific log level mcpt logs demo --follow --level error ``` ### Time-based Filtering ```bash # Show logs from last hour mcpt logs demo --since 1h # Show logs from last 30 minutes mcpt logs demo --since 30m # Show logs from specific time range mcpt logs demo --since 2024-01-15T10:00:00 --until 2024-01-15T11:00:00 # Show recent activity mcpt logs demo --since 5m --follow ``` ### Content Filtering ```bash # Filter by log level mcpt logs demo --level error mcpt logs demo --level warn # Search for specific patterns mcpt logs demo --grep "tool called" mcpt logs demo --grep "error\|exception" --level error # Combine filters mcpt logs demo --since 1h --level info --grep "client" ``` ### Output Formats ```bash # JSON format for parsing mcpt logs demo --format json --tail 10 # Example JSON output: [ { "timestamp": "2024-01-15T10:30:45Z", "level": "INFO", "message": "MCP Server starting on stdio transport", "container": "mcp-demo-123456", "source": "server.py:45" }, { "timestamp": "2024-01-15T10:32:15Z", "level": "INFO", "message": "Tool called: say_hello(name=\"World\")", "container": "mcp-demo-123456", "source": "tools.py:23", "metadata": { "tool_name": "say_hello", "parameters": {"name": "World"} } } ] # Plain text format (no formatting) mcpt logs demo --format plain --no-color ``` ## Log Levels and Filtering ### Available Log Levels | Level | Description | Color | |-------|-------------|-------| | `DEBUG` | Detailed debugging information | Gray | | `INFO` | General information messages | Blue | | `WARN` | Warning messages | Yellow | | `ERROR` | Error messages | Red | | `FATAL` | Critical errors | Magenta | ### Level Filtering Examples ```bash # Show only errors and warnings mcpt logs demo --level warn # Debug-level logging (very verbose) mcpt logs demo --level debug --tail 100 # Production monitoring (errors only) mcpt logs demo --level error --follow ``` ## Advanced Filtering ### Pattern Matching ```bash # Case-insensitive search mcpt logs demo --grep "(?i)error" # Multiple patterns (OR logic) mcpt logs demo --grep "error\|exception\|fail" # Tool-specific logs mcpt logs demo --grep "Tool called: say_hello" # Client connection logs mcpt logs demo --grep "client (connected|disconnected)" ``` ### Complex Queries ```bash # Errors in last hour mcpt logs demo --since 1h --level error # Recent tool calls with debug info mcpt logs demo --since 30m --grep "Tool" --level debug # Monitor specific functionality mcpt logs demo --follow --grep "file_server\|directory" ``` ## Performance and Troubleshooting ### Debugging Deployment Issues ```bash # Check startup logs mcpt logs demo --since 10m --level info # Look for errors during initialization mcpt logs demo --grep "starting\|initializ" --level error # Monitor resource usage logs mcpt logs demo --grep "memory\|cpu\|disk" --follow ``` ### Common Log Patterns #### Successful Startup ``` [INFO] MCP Server starting on stdio transport [INFO] Configuration loaded: {...} [INFO] Registered tool: tool_name [INFO] Server ready to accept connections ``` #### Client Connection ``` [INFO] Client connected via stdio [DEBUG] Received initialize request [DEBUG] Sent initialize response [INFO] Client session established ``` #### Tool Execution ``` [INFO] Tool called: tool_name(param="value") [DEBUG] Tool execution started [DEBUG] Tool execution completed: 0.045s [INFO] Tool result: {...} ``` #### Error Patterns ``` [ERROR] Tool execution failed: tool_name [ERROR] Invalid parameters for tool: {...} [WARN] Client disconnected unexpectedly [ERROR] Configuration error: missing required parameter ``` ### Performance Analysis ```bash # Monitor tool performance mcpt logs demo --grep "execution.*[0-9]+\.[0-9]+s" --follow # Track client connections mcpt logs demo --grep "client.*connected\|disconnected" --since 1h # Monitor error rates mcpt logs demo --level error --since 1h | wc -l ``` ## Integration with Monitoring ### Log Analysis Scripts ```bash #!/bin/bash # Simple error monitoring script ERROR_COUNT=$(mcpt logs demo --since 1h --level error --format plain | wc -l) if [ "$ERROR_COUNT" -gt 10 ]; then echo "⚠️ High error rate: $ERROR_COUNT errors in last hour" mcpt logs demo --since 1h --level error --tail 5 fi ``` ### Export for Analysis ```bash # Export logs to file mcpt logs demo --since 1d --format json > demo_logs_$(date +%Y%m%d).json # Import to log analysis tools mcpt logs demo --format json --since 1h | jq '.[] | select(.level == "ERROR")' # Create CSV for spreadsheet analysis mcpt logs demo --since 1d --format json | \ jq -r '.[] | [.timestamp, .level, .message] | @csv' > logs.csv ``` ### Real-time Monitoring Dashboard ```python #!/usr/bin/env python3 import subprocess import json import time from collections import defaultdict def monitor_logs(): """Simple real-time log monitoring.""" cmd = ["python", "-m", "mcp_template", "logs", "demo", "--follow", "--format", "json"] stats = defaultdict(int) with subprocess.Popen(cmd, stdout=subprocess.PIPE, text=True) as proc: for line in proc.stdout: try: log_entry = json.loads(line) stats[log_entry['level']] += 1 # Print stats every 100 lines if sum(stats.values()) % 100 == 0: print(f"Stats: {dict(stats)}") # Alert on errors if log_entry['level'] == 'ERROR': print(f"🚨 ERROR: {log_entry['message']}") except json.JSONDecodeError: continue if __name__ == "__main__": monitor_logs() ``` ## Container Log Management ### Log Rotation and Storage ```bash # Check log size docker logs mcp-demo-123456 | wc -l # Export container logs directly docker logs mcp-demo-123456 --since 1h > container_logs.txt # Configure log rotation (in docker-compose.yml) logging: driver: "json-file" options: max-size: "10m" max-file: "3" ``` ### Multi-container Deployments ```bash # Monitor multiple templates simultaneously mcpt logs demo --follow & mcpt logs filesystem --follow & wait ``` ## Troubleshooting Log Issues ### No Logs Available ```bash ❌ No logs available for template 'demo' ``` **Solutions**: - Verify template is deployed: `mcpt status demo` - Check if container is running: `mcpt list` - Container may have just started: try `--since 1m` ### Permission Errors ```bash ❌ Permission denied accessing container logs ``` **Solutions**: - Check Docker permissions - Run with appropriate privileges - Verify container accessibility ### Large Log Files ```bash ⚠️ Log file is very large (>100MB), consider using --tail or --since ``` **Solutions**: - Use `--tail 1000` to limit output - Use `--since 1h` for recent logs only - Consider log rotation configuration ## See Also - [`list`](list.md) - List deployments - [shell](shell.md) - Access deployment containers for debugging - [deploy](deploy.md) - Deploy templates with logging configuration - [Monitoring Guide](../user-guide/monitoring.md) - Comprehensive monitoring setup