logs¶

View and monitor deployment logs with filtering, streaming, and analysis capabilities.

Synopsis¶

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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

# 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¶

#!/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¶

# 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¶

#!/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
mcpt logs demo --follow &
mcpt logs filesystem --follow &
wait

Troubleshooting Log Issues¶

No Logs Available¶

❌ 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¶

❌ 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