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

api/lib/Gateway.ts

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

api/lib/ZwaveClient.ts

@@ -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,94 @@ 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 console transport for JSON output
+			const jsonConsoleTransport = new winston.transports.Console({
+				format: winston.format.combine(
+					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(
+						winston.format.timestamp(),
+						winston.format.json(),
+					),
+				})
+				transports.push(fileTransport)
+			}
+
+			// Custom WebSocket transport for JSON output
+			const jsonTransport = new JSONTransport()
+			jsonTransport.format = winston.format.combine(
+				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
+				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/logger.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)

src/views/Debug.vue

@@ -175,6 +175,48 @@ export default {
 			// no need to make this reative
 			this.prevScrollTop = scrollTop
 		},
+		formatLog(data) {
+			// Quick check if data looks like JSON (faster than JSON.parse)
+			const trimmed = data.trim()
+			if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+				try {
+					// Parse JSON only once
+					const logEntry = JSON.parse(data)
+					const timestamp =
+						logEntry.timestamp || new Date().toISOString()
+					const level = logEntry.level || 'info'
+					const label = logEntry.label || 'UNKNOWN'
+					const message = logEntry.message || ''
+					const context = logEntry.context || {}
+
+					// Create a formatted display string
+					let formatted = `<span style="color: #888;">${timestamp}</span> `
+					formatted += `<span style="color: #2196F3;">[${level.toUpperCase()}]</span> `
+					formatted += `<span style="color: #4CAF50;">${label}:</span> `
+					formatted += `<span style="color: #333;">${message}</span>`
+
+					// Add context information if available
+					if (Object.keys(context).length > 0) {
+						formatted += ` <span style="color: #666;">(${JSON.stringify(context)})</span>`
+					}
+
+					formatted += '</br>'
+					return formatted
+				} catch (e) {
+					// If JSON parsing fails, fall through to text handling
+				}
+			}
+
+			// Fallback to treating as plain text
+			data = ansiUp.ansi_to_html(data)
+			data = data.replace(/\n/g, '</br>')
+			if (!data.endsWith('</br>')) {
+				data += '</br>'
+			}
+			// remove background colors styles
+			data = data.replace(/background-color:rgb\([0-9, ]+\)/g, '')
+			return data
+		},
 	},
 	mounted() {
 		// init socket events
@@ -187,16 +229,9 @@ export default {
 
 		this.socket.on(socketEvents.debug, (data) => {
 			if (this.debugActive) {
-				data = ansiUp.ansi_to_html(data)
-				data = data.replace(/\n/g, '</br>')
-				if (!data.endsWith('</br>')) {
-					data += '</br>'
-				}
-
-				// remove background colors styles
-				data = data.replace(/background-color:rgb\([0-9, ]+\)/g, '')
-				// \b[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{3}Z\b
-				this.debug.push(data)
+				// Format and add the log entry
+				const formattedLog = this.formatLog(data)
+				this.debug.push(formattedLog)
 
 				if (this.debug.length > MAX_DEBUG_LINES) {
 					this.debug.shift()

src/views/Settings.vue

@@ -132,6 +132,20 @@
 											label="Log Level"
 										></v-select>
 									</v-col>
+									<v-col
+										cols="12"
+										sm="6"
+										md="4"
+										v-if="newGateway.logEnabled"
+									>
+										<v-select
+											:items="logFormats"
+											v-model="newGateway.logFormat"
+											label="Log Format"
+											hint="Choose between human-readable text or structured JSON logging"
+											persistent-hint
+										></v-select>
+									</v-col>
 									<v-col
 										cols="12"
 										sm="6"
@@ -2269,6 +2283,10 @@ export default {
 				{ title: 'Debug', value: 'debug' },
 				{ title: 'Silly', value: 'silly' },
 			],
+			logFormats: [
+				{ title: 'Text (Human-readable)', value: 'text' },
+				{ title: 'JSON (Structured)', value: 'json' },
+			],
 			headers: [
 				{ title: 'Device', key: 'device' },
 				{ title: 'Value', key: 'value', sortable: false },

test/lib/logger.test.ts

@@ -3,6 +3,7 @@ import * as utils from '../../api/lib/utils'
 import { logsDir } from '../../api/config/app'
 import {
 	customTransports,
+	customFormat,
 	defaultLogFile,
 	ModuleLogger,
 	sanitizedConfig,
@@ -177,4 +178,24 @@ describe('logger.js', () => {
 			expect(logger2.level).to.equal('warn')
 		})
 	})
+
+	describe('customFormat()', () => {
+		it('should return format object when logFormat is json', () => {
+			const format = customFormat(false, 'json')
+			expect(format).to.be.an('object')
+			expect(format).to.have.property('transform')
+		})
+
+		it('should return format object when logFormat is text', () => {
+			const format = customFormat(true, 'text')
+			expect(format).to.be.an('object')
+			expect(format).to.have.property('transform')
+		})
+
+		it('should return format object when logFormat is undefined', () => {
+			const format = customFormat(true, undefined)
+			expect(format).to.be.an('object')
+			expect(format).to.have.property('transform')
+		})
+	})
 })