Improve logging UX for stdio transport and add human-readable console format (#67)

Author: ivan-gudak

CHANGELOG.md

@@ -15,6 +15,9 @@
   - Redirect logs to stdout (`stdout` or `console`), stderr (errors/warnings only with `stderr`, or all levels with `stderr-all`), or a custom file path
   - Use multiple destinations simultaneously (e.g., `file+console` to log to both file and stdout, or `file+stderr` for file logging with errors to stderr)
   - Disable logging entirely with `disabled`
+- Improved log readability for console and stderr output by switching from JSON to human-readable format (`YYYY-MM-DD HH:mm:ss.SSS [level] message`), making debugging easier when using `LOG_OUTPUT=console` or `LOG_OUTPUT=stderr-all`. File logging continues to use JSON format for machine parsing
+- Added runtime warning when `LOG_OUTPUT=console` or `LOG_OUTPUT=stdout` is used with stdio transport (default for VS Code), guiding users to use `LOG_OUTPUT=stderr-all` or `LOG_OUTPUT=file` instead, as stdout is reserved for MCP protocol communication
+- Enhanced documentation with clear guidance on which `LOG_OUTPUT` settings work with stdio transport (VS Code, Claude Desktop) versus HTTP transport, including practical examples for each scenario
 
 ## 0.5.3
 

README.md

@@ -471,37 +471,47 @@ AWS Lambda Functions:
 
 ### Logging Variables
 
-- `LOG_LEVEL` (optional): Log level, writing to dynatrace-managed-mcp.log in the current working directory (e.g. debug, info, warning, error)
-- `DT_ENVIRONMENT_CONFIGS`: An escaped JSON array that defines the Dynatrace Managed environment(s) to connect to. See below for contents of this.
 - `LOG_LEVEL` (optional): Log verbosity level (e.g. debug, info, warn, error). Default: `info`
-- `LOG_OUTPUT` (optional): Log output destination. Options:
-  - `file` (default): Write logs to a file
-  - `stdout`: Write logs to standard output
-  - `console`: Alias for `stdout`
-  - `stderr`: Write errors and warnings to standard error (info/debug still suppressed)
-  - `stderr-all`: Write all log levels to standard error
-  - `file+console` or `file+stdout`: Write logs to both file and stdout
+- `LOG_OUTPUT` (optional): Log output destination. Default: `file`
+  - `file`: Write logs to a file (default behavior)
+  - `stdout` / `console`: Write logs to standard output (⚠️ **stdio transport only**: Not visible in VS Code Output panel - use `stderr-all` instead)
+  - `stderr`: Write errors and warnings to standard error (info/debug suppressed)
+  - `stderr-all`: Write all log levels to standard error (✅ **Recommended for VS Code with stdio transport**)
+  - `file+console` / `file+stdout`: Write logs to both file and stdout
   - `file+stderr`: Write logs to file and errors/warnings to stderr
   - `disabled`: Disable logging entirely
 - `LOG_FILE` (optional): Path to log file when `LOG_OUTPUT` includes `file`. Default: `dynatrace-managed-mcp.log` in current working directory
 
+> [!IMPORTANT]
+> **Choosing the right LOG_OUTPUT for your setup:**
+>
+> - **VS Code with stdio transport (default)**: Use `LOG_OUTPUT=stderr-all` or `LOG_OUTPUT=file` (default)
+>   - ❌ `LOG_OUTPUT=console` won't work - stdout is reserved for MCP protocol
+>   - ✅ `LOG_OUTPUT=stderr-all` shows all logs in VS Code's Output panel
+>   - ✅ `LOG_OUTPUT=file` writes to log file (read with `tail -f dynatrace-managed-mcp.log`)
+> - **HTTP transport (`--http` mode)**: Any `LOG_OUTPUT` option works
+>   - ✅ `LOG_OUTPUT=console` visible in terminal
+>   - ✅ `LOG_OUTPUT=stderr-all` visible in terminal
+>   - ✅ `LOG_OUTPUT=file` writes to log file
+
 **Logging Examples:**
 
 ```bash
-# Log to standard output (useful for Docker/containerized environments)
-LOG_OUTPUT=stdout node dist/index.js
+# VS Code with stdio transport - see logs in Output panel
+LOG_OUTPUT=stderr-all LOG_LEVEL=debug
 
-# Log errors/warnings to stderr, suppress info/debug (standard Unix practice)
-LOG_OUTPUT=stderr node dist/index.js
+# VS Code with stdio transport - write to file (default)
+LOG_LEVEL=debug
+# Read with: tail -f dynatrace-managed-mcp.log
 
-# Log to custom file path
-LOG_OUTPUT=file LOG_FILE=/var/log/dynatrace-mcp.log node dist/index.js
+# HTTP transport - log to console
+LOG_OUTPUT=console LOG_LEVEL=debug node dist/index.js --http
 
-# Log to both file and console (useful for debugging)
-LOG_OUTPUT=file+console LOG_LEVEL=debug node dist/index.js
+# HTTP transport - log to file and console
+LOG_OUTPUT=file+console LOG_LEVEL=debug node dist/index.js --http
 
-# Log to file, send errors/warnings to stderr (production use)
-LOG_OUTPUT=file+stderr LOG_FILE=/var/log/app.log node dist/index.js
+# Log to custom file path
+LOG_OUTPUT=file LOG_FILE=/var/log/dynatrace-mcp.log node dist/index.js
 
 # Disable logging entirely (not recommended)
 LOG_OUTPUT=disabled node dist/index.js

package-lock.json

@@ -1198,6 +1198,20 @@ Never run queries that could return very large amounts of data, or that could be
     // Default stdio mode
     const transport = new StdioServerTransport();
 
+    // Warn if LOG_OUTPUT is set to stdout/console (won't work with stdio)
+    const logOutput = (process.env.LOG_OUTPUT || '').toLowerCase();
+    if (
+      logOutput === 'console' ||
+      logOutput === 'stdout' ||
+      logOutput === 'file+console' ||
+      logOutput === 'file+stdout'
+    ) {
+      console.error(
+        `WARNING: LOG_OUTPUT=${process.env.LOG_OUTPUT} won't show logs in stdio transport. ` +
+          `Stdout is reserved for MCP protocol. Use LOG_OUTPUT=stderr-all or LOG_OUTPUT=file instead.`,
+      );
+    }
+
     logger.info('Connecting server to transport...');
     await server.connect(transport);
 

src/index.ts

@@ -1,5 +1,37 @@
 import winston from 'winston';
 
+function createFormat(): winston.Logform.Format {
+  const logOutput = (process.env.LOG_OUTPUT || 'file').toLowerCase();
+  const useConsole = [
+    'console',
+    'stdout',
+    'stderr',
+    'stderr-all',
+    'file+console',
+    'file+stdout',
+    'file+stderr',
+  ].includes(logOutput);
+
+  if (useConsole) {
+    // Use human-readable format for console output
+    return winston.format.combine(
+      winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }),
+      winston.format.errors({ stack: true }),
+      winston.format.printf(({ timestamp, level, message, ...meta }) => {
+        const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';
+        return `${timestamp} [${level}] ${message}${metaStr}`;
+      }),
+    );
+  } else {
+    // Use JSON format for file output
+    return winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.errors({ stack: true }),
+      winston.format.json(),
+    );
+  }
+}
+
 function createTransports(): winston.transport[] {
   const logOutput = (process.env.LOG_OUTPUT || 'file').toLowerCase();
   const logFile = process.env.LOG_FILE || 'dynatrace-managed-mcp.log';
@@ -45,11 +77,7 @@ function createTransports(): winston.transport[] {
 
 export const logger = winston.createLogger({
   level: (process.env.LOG_LEVEL || 'info').toLowerCase(),
-  format: winston.format.combine(
-    winston.format.timestamp(),
-    winston.format.errors({ stack: true }),
-    winston.format.json(),
-  ),
+  format: createFormat(),
   transports: createTransports(),
 });