Skip to main content

Log Capture

The satellite captures and batches two types of logs for each MCP server installation: server logs (stderr output, connection errors, startup messages) and request logs (tool execution with full request/response data).

Overview

Log capture serves three purposes: Debugging lets developers see stderr output and tool execution details, Monitoring tracks server health and tool usage in real-time, and Audit Trail provides a complete record of tool calls with parameters and responses Both log types use the same batching strategy (3-second interval, max 20 per batch) to optimize backend API calls and database writes.

Server Logs

Server logs capture stderr output and connection events from MCP servers, particularly useful for debugging stdio-based servers.

What Gets Logged

Stdio Servers:
  • stderr output from the MCP server process
  • Connection errors (handshake failures)
  • Process spawn errors
  • Crash information
HTTP/SSE Servers:
  • Connection errors (ECONNREFUSED, ETIMEDOUT)
  • HTTP error responses (4xx, 5xx)
  • OAuth authentication failures
  • Network timeouts

Log Levels

Buffering Implementation

Example Server Logs

Request Logs

Request logs capture tool execution with full request parameters and server responses, providing complete visibility into MCP tool usage.

What Gets Logged

For each tool execution:
  • Tool name (e.g., github:list-repos)
  • Input parameters sent to tool
  • Full response from MCP server (when request logging is enabled)
  • Response time in milliseconds
  • Success/failure status
  • Error message (if failed)
  • User ID (who called the tool)
  • Timestamp

Privacy Control

Request logging can be disabled per-installation via settings:
When disabled:
  • No request logs are buffered or emitted
  • Tool execution still works normally
  • Server logs (stderr) still captured
  • Used for privacy-sensitive tools (internal APIs, credentials, PII)

Buffering Implementation

Example Request Logs

Batching Configuration

Both server logs and request logs use the same batching strategy. See Event Emission - Batching Configuration for configuration parameters and rationale.

Batching Flow

Backend Storage

Server Logs Table

Request Logs Table

Cleanup Job

A backend cron job enforces a 100-line limit per installation for both tables:
This prevents unbounded table growth while maintaining recent debugging history.

Buffer Management

Memory Usage

Server Logs:
  • Maximum ~20 entries in buffer before flush
  • Each entry: ~200 bytes average (message + metadata)
  • Max buffer size: ~4 KB per ProcessManager instance
Request Logs:
  • Maximum ~20 entries in buffer before flush
  • Each entry: Variable (depends on params/response size)
  • Typically: 500 bytes - 5 KB per entry
  • Max buffer size: ~10-100 KB per McpServerWrapper instance

Cleanup on Shutdown

Both buffer managers flush remaining logs on cleanup:

Implementation Components

The log capture system consists of several integrated components:
  • Server and request log batching implementation
  • Request logging toggle and tool response capture
  • Backend log tables and event handlers
  • 100-line cleanup job