feat: implement unified JSON/text logging format

- Add logFormat setting to Gateway config (text/json)
- Update UI logger to respect global logFormat setting
- Add log format selector in Settings UI
- Update Debug view to handle both text and JSON log formats
- Implement driver logging configuration for JSON mode
- Use DailyRotateFile for JSON file transport to maintain symlink functionality
- Disable driver internal transports with enabled: false for cleaner config
- Add WebSocket streaming for both text and JSON formats
- Optimize JSON detection with fast string operations
- Add basic tests for logging format functionality

This provides a unified logging system where users can switch between
human-readable text logs and structured JSON logs across all output
destinations: console, files, and WebSocket/UI debug view.

Author: lngarrett

.cursor/commands/lngarrett-lngarrett-requested-review-from-alcalzone-and-robertslando.md

@@ -191,6 +191,7 @@ export type GatewayConfig = {
 	logEnabled?: boolean
 	logLevel?: LogLevel
 	logToFile?: boolean
+	logFormat?: 'text' | 'json'
 	values?: GatewayValue[]
 	jobs?: ScheduledJob[]
 	plugins?: string[]

.cursor/commands/lngarrett.md

@@ -22,6 +22,8 @@ import {
 } from '@zwave-js/core'
 import { createDefaultTransportFormat } from '@zwave-js/core/bindings/log/node'
 import { JSONTransport } from '@zwave-js/log-transport-json'
+import winston from 'winston'
+import DailyRotateFile from 'winston-daily-rotate-file'
 import { isDocker } from './utils'
 import {
 	AssociationAddress,
@@ -2318,14 +2320,8 @@ class ZwaveClient extends TypedEventEmitter<ZwaveClientEventCallbacks> {
 
 		utils.parseSecurityKeys(this.cfg, zwaveOptions)
 
-		const logTransport = new JSONTransport()
-		logTransport.format = createDefaultTransportFormat(true, false)
-
-		zwaveOptions.logConfig.transports = [logTransport]
-
-		logTransport.stream.on('data', (data) => {
-			this.socket.emit(socketEvents.debug, data.message.toString())
-		})
+		// Setup driver logging based on format setting
+		this.setupDriverLogging(zwaveOptions)
 
 		try {
 			if (shouldUpdateSettings) {
@@ -6946,6 +6942,120 @@ class ZwaveClient extends TypedEventEmitter<ZwaveClientEventCallbacks> {
 			}
 		}, 1000)
 	}
+
+	/**
+	 * Setup driver logging based on the configured format (text or JSON)
+	 * Uses the same logFormat setting as the gateway for consistency
+	 */
+	private setupDriverLogging(zwaveOptions: PartialZWaveOptions) {
+		// Get the log format from gateway settings - this applies to both app and driver logging
+		const settings = jsonStore.get(store.settings)
+		const logFormat = settings?.gateway?.logFormat || 'text'
+
+		if (logFormat === 'json') {
+			// JSON logging for driver - create custom transports for all outputs
+			const transports = []
+
+			// Custom format to parse driver's JSON strings before Winston formatting
+			const parseDriverJsonFormat = winston.format((info) => {
+				if (typeof info.message === 'string' && info.message.startsWith('{')) {
+					try {
+						const parsed = JSON.parse(info.message)
+						// Flatten the nested structure: merge tags and message fields
+						if (parsed.tags && parsed.message) {
+							info.message = {
+								...parsed.message,
+								tags: parsed.tags
+							}
+						} else {
+							info.message = parsed
+						}
+					} catch (e) {
+						// Keep as string if parsing fails
+					}
+				}
+				return info
+			})
+
+			// Custom console transport for JSON output
+			const jsonConsoleTransport = new winston.transports.Console({
+				format: winston.format.combine(
+					parseDriverJsonFormat(),
+					winston.format.timestamp(),
+					winston.format.json(),
+				),
+			})
+			transports.push(jsonConsoleTransport)
+
+			// Custom file transport for JSON output (if file logging is enabled)
+			// Use DailyRotateFile to maintain symlink functionality and proper date handling
+			if (this.cfg.logToFile) {
+				const fileTransport = new DailyRotateFile({
+					filename: ZWAVEJS_LOG_FILE,
+					auditFile: ZWAVEJS_LOG_FILE.replace(
+						'_%DATE%',
+						'_logrotate',
+					).replace('.log', '.json'),
+					datePattern: 'YYYY-MM-DD',
+					createSymlink: true,
+					symlinkName: 'zwavejs_current.log',
+					zippedArchive: true,
+					maxFiles: `${this.cfg.maxFiles || 7}d`,
+					maxSize: '50m',
+					format: winston.format.combine(
+						parseDriverJsonFormat(),
+						winston.format.timestamp(),
+						winston.format.json(),
+					),
+				})
+				transports.push(fileTransport)
+			}
+
+			// Custom WebSocket transport for JSON output
+			const jsonTransport = new JSONTransport()
+			jsonTransport.format = winston.format.combine(
+				parseDriverJsonFormat(),
+				winston.format.timestamp(),
+				winston.format.json(),
+			)
+			transports.push(jsonTransport)
+
+			// Configure driver to use ONLY our custom transports
+			// Disable internal transports and use only our custom ones
+			zwaveOptions.logConfig = {
+				...zwaveOptions.logConfig,
+				enabled: false, // This disables ALL internal transports
+				raw: true,
+				showLogo: false,
+				transports: transports, // Use ONLY our custom transports
+			}
+
+			// Stream JSON logs to WebSocket for debug view
+			jsonTransport.stream.on('data', (data) => {
+				this.socket.emit(socketEvents.debug, data.message.toString())
+			})
+		} else {
+			// Text logging for driver (preserve original behavior)
+			// Ensure console output by setting forceConsole: true when logToFile: true
+			// This matches the original behavior where console logs were visible
+			zwaveOptions.logConfig.forceConsole = true
+
+			// Add JSONTransport for WebSocket streaming alongside existing transports
+			const logTransport = new JSONTransport()
+			logTransport.format = createDefaultTransportFormat(true, false)
+
+			// Add JSONTransport to existing transports instead of replacing them
+			if (!zwaveOptions.logConfig.transports) {
+				zwaveOptions.logConfig.transports = []
+			}
+			zwaveOptions.logConfig.transports.push(logTransport)
+
+			// Stream logs to WebSocket for debug view
+			logTransport.stream.on('data', (data) => {
+				this.socket.emit(socketEvents.debug, data.message.toString())
+			})
+		}
+	}
 }
 
 export default ZwaveClient

api/lib/Gateway.ts

@@ -70,8 +70,22 @@ export function sanitizedConfig(
 /**
  * Return a custom logger format
  */
-export function customFormat(noColor = false): winston.Logform.Format {
+export function customFormat(
+	noColor = false,
+	logFormat: 'text' | 'json' = 'text',
+): winston.Logform.Format {
 	noColor = noColor || disableColors
+
+	if (logFormat === 'json') {
+		// JSON format for all outputs
+		return combine(
+			timestamp(),
+			format.errors({ stack: true }),
+			format.json(),
+		)
+	}
+
+	// Existing text format
 	const formats: winston.Logform.Format[] = [
 		splat(), // used for formats like: logger.log('info', Message %s', strinVal)
 		timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }),
@@ -106,7 +120,10 @@ export const logStream = new PassThrough()
 /**
  * Create the base transports based on settings provided
  */
-export function customTransports(config: LoggerConfig): winston.transport[] {
+export function customTransports(
+	config: LoggerConfig,
+	logFormat: 'text' | 'json' = 'text',
+): winston.transport[] {
 	// setup transports only once (see issue #2937)
 	if (transportsList) {
 		return transportsList
@@ -117,15 +134,15 @@ export function customTransports(config: LoggerConfig): winston.transport[] {
 	if (process.env.ZUI_NO_CONSOLE !== 'true') {
 		transportsList.push(
 			new transports.Console({
-				format: customFormat(),
+				format: customFormat(false, logFormat),
 				level: config.level,
 				stderrLevels: ['error'],
 			}),
 		)
 	}
 
 	const streamTransport = new transports.Stream({
-		format: customFormat(),
+		format: customFormat(false, logFormat),
 		level: config.level,
 		stream: logStream,
 	})
@@ -137,7 +154,7 @@ export function customTransports(config: LoggerConfig): winston.transport[] {
 
 		if (process.env.DISABLE_LOG_ROTATION === 'true') {
 			fileTransport = new transports.File({
-				format: customFormat(true),
+				format: customFormat(true, logFormat),
 				filename: config.filePath,
 				level: config.level,
 			})
@@ -154,7 +171,7 @@ export function customTransports(config: LoggerConfig): winston.transport[] {
 				maxFiles: process.env.ZUI_LOG_MAXFILES || '7d',
 				maxSize: process.env.ZUI_LOG_MAXSIZE || '50m',
 				level: config.level,
-				format: customFormat(true),
+				format: customFormat(true, logFormat),
 			}
 			fileTransport = new DailyRotateFile(options)
 
@@ -182,6 +199,7 @@ export function setupLogger(
 	config?: DeepPartial<GatewayConfig>,
 ): ModuleLogger {
 	const sanitized = sanitizedConfig(module, config)
+	const logFormat = config?.logFormat || 'text'
 	// Winston automatically reuses an existing module logger
 	const logger = container.add(module) as ModuleLogger
 	const moduleName = module.toUpperCase() || '-'
@@ -196,7 +214,7 @@ export function setupLogger(
 		), // to correctly parse errors
 		silent: !sanitized.enabled,
 		level: sanitized.level,
-		transports: customTransports(sanitized),
+		transports: customTransports(sanitized, logFormat),
 	})
 	logger.module = module
 	logger.setup = (cfg) => setupLogger(container, module, cfg)