Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(logs): write JSON in the cluster, so Datadog can read the context (#205)

Dev at Autonomous0f18f3d71c95
diff --git a/backend/src/utils/logger.test.ts b/backend/src/utils/logger.test.ts
new file mode 100644
index 000000000..cab8ed8a7
--- /dev/null
+++ b/backend/src/utils/logger.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Logger } from './logger.js'
+
+/**
+ * In the cluster these lines are read by Datadog, which parses a JSON line into attributes you can
+ * filter and group by. The old format — `[ts] [INFO] message {json}` — arrived as one string, so
+ * `userId` and the rest were text nobody could query. `message` and `status` are the names Datadog
+ * reads; everything else becomes `@<key>`.
+ */
+function captured(write: () => void): string[] {
+ const lines: string[] = []
+ const spy = vi.spyOn(console, 'log').mockImplementation((line: unknown) => { lines.push(String(line)) })
+ try { write() } finally { spy.mockRestore() }
+ return lines
+}
+
+describe('logger, in the cluster', () => {
+ afterEach(() => { vi.restoreAllMocks() })
+
+ const json = () => new Logger(true)
+
+ it('writes one line of JSON', () => {
+ const lines = captured(() => json().info('web user disconnected'))
+ expect(lines).toHaveLength(1)
+ expect(() => JSON.parse(lines[0])).not.toThrow()
+ })
+
+ it('names the message and the level the way Datadog reads them', () => {
+ const [line] = captured(() => json().info('web user disconnected'))
+ const entry = JSON.parse(line)
+ expect(entry.message).toBe('web user disconnected')
+ expect(entry.status).toBe('info')
+ expect(Date.parse(entry.timestamp)).not.toBeNaN()
+ })
+
+ it('puts context alongside, so a field can be filtered on', () => {
+ const [line] = captured(() => json().info('web user disconnected', { userId: 'u1', machineId: 'm1' }))
+ // Siblings, not nested under `context`: Datadog reads these as @userId and @machineId.
+ expect(JSON.parse(line)).toMatchObject({ userId: 'u1', machineId: 'm1' })
+ })
+
+ it('does not let a context field take over the message or the level', () => {
+ const [line] = captured(() => json().info('the real message', { message: 'not this', status: 'error' }))
+ const entry = JSON.parse(line)
+ expect(entry.message).toBe('the real message')
+ expect(entry.status).toBe('info')
+ })
+
+ it('says warn and error as their own levels', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+ json().warn('careful')
+ json().error('broke', new Error('the cause'))
+ expect(JSON.parse(String(warn.mock.calls[0][0])).status).toBe('warn')
+ const entry = JSON.parse(String(error.mock.calls[0][0]))
+ expect(entry.status).toBe('error')
+ expect(entry.message).toBe('broke')
+ expect(entry.error).toBe('the cause')
+ })
+})
+
+describe('logger, on a terminal', () => {
+ afterEach(() => { vi.restoreAllMocks() })
+
+ it('keeps the readable line, so `npm run dev` is not a wall of JSON', () => {
+ const [line] = captured(() => new Logger(false).info('web user disconnected', { userId: 'u1' }))
+ expect(line).toMatch(/^\[[^\]]+\] \[INFO\] web user disconnected \{"userId":"u1"\}$/)
+ })
+})
diff --git a/backend/src/utils/logger.ts b/backend/src/utils/logger.ts
index 3e83f2bfd..d84dd012a 100644
--- a/backend/src/utils/logger.ts
+++ b/backend/src/utils/logger.ts
@@ -4,25 +4,44 @@ interface LogContext {
[key: string]: unknown
}
-class Logger {
+/**
+ * One line per log, in one of two shapes.
+ *
+ * In the cluster: JSON, because that is what Datadog can read. It parses a JSON line into
+ * attributes, so `logger.info('web user disconnected', { userId })` becomes something you can filter
+ * with `@userId` and group by. `message` and `status` are the names it reads for the text and the
+ * level; every other key becomes an attribute of its own. The old format — `[ts] [INFO] text {json}`
+ * — arrived as one string, so the context was text nobody could query.
+ *
+ * Anywhere else (a terminal, the tests): that readable line, unchanged. `npm run dev` should not be
+ * a wall of JSON.
+ */
+export class Logger {
private isDevelopment = process.env.NODE_ENV === 'development'
- private formatMessage(level: LogLevel, message: string, context?: LogContext): string {
+ constructor(private readonly asJson: boolean = process.env.NODE_ENV === 'production') {}
+
+ private write(level: LogLevel, to: (line: string) => void, message: string, context?: LogContext): void {
const timestamp = new Date().toISOString()
- const contextStr = context ? ` ${JSON.stringify(context)}` : ''
- return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`
+ if (this.asJson) {
+ // Context first: a field called `message` or `status` is data about the event, and must not
+ // take the place of the event's own message or level.
+ to(JSON.stringify({ ...context, timestamp, status: level, message }))
+ return
+ }
+ to(`[${timestamp}] [${level.toUpperCase()}] ${message}${context ? ` ${JSON.stringify(context)}` : ''}`)
}
debug(message: string, context?: LogContext): void {
- if (this.isDevelopment) console.debug(this.formatMessage('debug', message, context))
+ if (this.isDevelopment) this.write('debug', (line) => console.debug(line), message, context)
}
info(message: string, context?: LogContext): void {
- console.log(this.formatMessage('info', message, context))
+ this.write('info', (line) => console.log(line), message, context)
}
warn(message: string, context?: LogContext): void {
- console.warn(this.formatMessage('warn', message, context))
+ this.write('warn', (line) => console.warn(line), message, context)
}
error(message: string, error?: Error | unknown, context?: LogContext): void {
@@ -37,7 +56,7 @@ class Logger {
} else {
errorContext = { ...context }
}
- console.error(this.formatMessage('error', message, errorContext))
+ this.write('error', (line) => console.error(line), message, errorContext)
}
}