logs
View and monitor deployment logs with filtering, streaming, and analysis capabilities.
Synopsis
mcp-template 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
# View all logs for demo template
mcp-template 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
# Follow logs in real-time
mcp-template logs demo --follow
# Follow with tail (last 50 lines + new ones)
mcp-template logs demo --follow --tail 50
# Monitor specific log level
mcp-template logs demo --follow --level error
Time-based Filtering
# Show logs from last hour
mcp-template logs demo --since 1h
# Show logs from last 30 minutes
mcp-template logs demo --since 30m
# Show logs from specific time range
mcp-template logs demo --since 2024-01-15T10:00:00 --until 2024-01-15T11:00:00
# Show recent activity
mcp-template logs demo --since 5m --follow
Content Filtering
# Filter by log level
mcp-template logs demo --level error
mcp-template logs demo --level warn
# Search for specific patterns
mcp-template logs demo --grep "tool called"
mcp-template logs demo --grep "error\|exception" --level error
# Combine filters
mcp-template logs demo --since 1h --level info --grep "client"
# JSON format for parsing
mcp-template 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)
mcp-template 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
# Show only errors and warnings
mcp-template logs demo --level warn
# Debug-level logging (very verbose)
mcp-template logs demo --level debug --tail 100
# Production monitoring (errors only)
mcp-template logs demo --level error --follow
Advanced Filtering
Pattern Matching
# Case-insensitive search
mcp-template logs demo --grep "(?i)error"
# Multiple patterns (OR logic)
mcp-template logs demo --grep "error\|exception\|fail"
# Tool-specific logs
mcp-template logs demo --grep "Tool called: say_hello"
# Client connection logs
mcp-template logs demo --grep "client (connected|disconnected)"
Complex Queries
# Errors in last hour
mcp-template logs demo --since 1h --level error
# Recent tool calls with debug info
mcp-template logs demo --since 30m --grep "Tool" --level debug
# Monitor specific functionality
mcp-template logs demo --follow --grep "file_server\|directory"
Debugging Deployment Issues
# Check startup logs
mcp-template logs demo --since 10m --level info
# Look for errors during initialization
mcp-template logs demo --grep "starting\|initializ" --level error
# Monitor resource usage logs
mcp-template 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
[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
# Monitor tool performance
mcp-template logs demo --grep "execution.*[0-9]+\.[0-9]+s" --follow
# Track client connections
mcp-template logs demo --grep "client.*connected\|disconnected" --since 1h
# Monitor error rates
mcp-template logs demo --level error --since 1h | wc -l
Integration with Monitoring
Log Analysis Scripts
#!/bin/bash
# Simple error monitoring script
ERROR_COUNT=$(mcp-template 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"
mcp-template logs demo --since 1h --level error --tail 5
fi
Export for Analysis
# Export logs to file
mcp-template logs demo --since 1d --format json > demo_logs_$(date +%Y%m%d).json
# Import to log analysis tools
mcp-template logs demo --format json --since 1h | jq '.[] | select(.level == "ERROR")'
# Create CSV for spreadsheet analysis
mcp-template logs demo --since 1d --format json | \
jq -r '.[] | [.timestamp, .level, .message] | @csv' > logs.csv
Real-time Monitoring Dashboard
#!/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
# 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
# Monitor multiple templates simultaneously
mcp-template logs demo --follow &
mcp-template logs file-server --follow &
wait
Troubleshooting Log Issues
No Logs Available
❌ No logs available for template 'demo'
Solutions:
- Verify template is deployed: mcp-template status demo
- Check if container is running: mcp-template list
- Container may have just started: try --since 1m
Permission Errors
❌ Permission denied accessing container logs
Solutions:
- Check Docker permissions
- Run with appropriate privileges
- Verify container accessibility
Large Log Files
⚠️ 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
- status - Check deployment health and status
- shell - Access deployment containers for debugging
- deploy - Deploy templates with logging configuration
- Monitoring Guide - Comprehensive monitoring setup