The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
feat(upgrade): emit structured logfmt logs for upgrade flow (#20539)
Charles Bochet2a9fef23419c
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/upgrade.command.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/upgrade.command.tsindex 0cc931af787..81ecc588204 100644--- a/packages/twenty-server/src/database/commands/upgrade-version-command/upgrade.command.ts+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/upgrade.command.ts@@ -1,10 +1,10 @@-import chalk from 'chalk';import { Command, CommandRunner, Option } from 'nest-commander';import { isDefined } from 'twenty-shared/utils';import { CommandLogger } from 'src/database/commands/logger';import { UpgradeSequenceReaderService } from 'src/engine/core-modules/upgrade/services/upgrade-sequence-reader.service';import { UpgradeSequenceRunnerService } from 'src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service';+import { formatUpgradeLog } from 'src/engine/core-modules/upgrade/utils/format-upgrade-log.util';type RawUpgradeCommandOptions = {workspaceId?: Set<string>;@@ -126,18 +126,31 @@ export class UpgradeCommand extends CommandRunner {const sequence = this.upgradeSequenceReaderService.getUpgradeSequence();this.logger.log(- chalk.blue(- [- 'Initialized upgrade sequence:',- `- ${sequence.length} step(s)`,- ...sequence.map(- (step, index) =>- ` [${index}] ${step.kind} — ${step.name} (${step.version})`,- ),- ].join('\n '),- ),+ formatUpgradeLog({+ humanMessage: `Initialized upgrade sequence: ${sequence.length} step(s)`,+ event: 'sequence.initialized',+ logFields: {+ stepCount: sequence.length,+ dryRun: options.dryRun ?? false,+ },+ }),);+ for (const [index, step] of sequence.entries()) {+ this.logger.verbose(+ formatUpgradeLog({+ humanMessage: ` [${index}] ${step.kind} — ${step.name} (${step.version})`,+ event: 'sequence.step',+ logFields: {+ index,+ kind: step.kind,+ name: step.name,+ version: step.version,+ },+ }),+ );+ }+const { totalSuccesses, totalFailures } =await this.upgradeSequenceRunnerService.run({sequence,@@ -150,9 +163,15 @@ export class UpgradeCommand extends CommandRunner {});this.logger.log(- chalk.blue(- `Upgrade summary: ${totalSuccesses} workspace(s) succeeded, ${totalFailures} workspace(s) failed`,- ),+ formatUpgradeLog({+ humanMessage: `Upgrade summary: ${totalSuccesses} workspace(s) succeeded, ${totalFailures} workspace(s) failed`,+ event: 'summary',+ logFields: {+ totalSuccesses,+ totalFailures,+ dryRun: options.dryRun ?? false,+ },+ }),);if (totalFailures > 0) {@@ -161,7 +180,15 @@ export class UpgradeCommand extends CommandRunner {);}} catch (error) {- this.logger.error(chalk.red(`Upgrade failed: ${error.message}`));+ const errorMessage =+ error instanceof Error ? error.message : String(error);++ this.logger.error(+ formatUpgradeLog({+ humanMessage: `Upgrade failed: ${errorMessage}`,+ event: 'aborted',+ }),+ );throw error;}}diff --git a/packages/twenty-server/src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service.ts b/packages/twenty-server/src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service.tsindex 0fd848f6d56..5e370e6e659 100644--- a/packages/twenty-server/src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service.ts+++ b/packages/twenty-server/src/engine/core-modules/upgrade/services/upgrade-sequence-runner.service.ts@@ -17,6 +17,7 @@ import {UpgradeSequenceReaderService,} from 'src/engine/core-modules/upgrade/services/upgrade-sequence-reader.service';import { WorkspaceCommandRunnerService } from 'src/engine/core-modules/upgrade/services/workspace-command-runner.service';+import { formatUpgradeLog } from 'src/engine/core-modules/upgrade/utils/format-upgrade-log.util';import { WorkspaceVersionService } from 'src/engine/workspace-manager/workspace-version/services/workspace-version.service';import { assertUnreachable, isDefined } from 'twenty-shared/utils';@@ -75,9 +76,17 @@ export class UpgradeSequenceRunnerService {isDefined(options.workspaceCountLimit)) {this.logger.log(- `Stopping before instance step "${step.name}": ` +- 'upgrade was run with a workspace filter (-w, --start-from-workspace-id, or --workspace-count-limit). ' +- 'Instance commands require all workspaces to be aligned.',+ formatUpgradeLog({+ humanMessage:+ `Stopping before instance step "${step.name}": ` ++ 'upgrade was run with a workspace filter (-w, --start-from-workspace-id, or --workspace-count-limit). ' ++ 'Instance commands require all workspaces to be aligned.',+ event: 'sequence.stopped',+ logFields: {+ before: step.name,+ reason: 'workspace-filter-active',+ },+ }),);break;@@ -120,8 +129,16 @@ export class UpgradeSequenceRunnerService {if (report.fail.length > 0) {this.logger.error(- `Workspace steps ended with ${report.fail.length} failure(s). ` +- 'Aborting — cannot proceed to next instance step.',+ formatUpgradeLog({+ humanMessage:+ `Workspace steps ended with ${report.fail.length} failure(s). ` ++ 'Aborting — cannot proceed to next instance step.',+ event: 'sequence.aborted',+ logFields: {+ failures: report.fail.length,+ reason: 'workspace-failures',+ },+ }),);return { totalSuccesses, totalFailures };diff --git a/packages/twenty-server/src/engine/core-modules/upgrade/services/workspace-command-runner.service.ts b/packages/twenty-server/src/engine/core-modules/upgrade/services/workspace-command-runner.service.tsindex 798bf3f9027..5041143ba79 100644--- a/packages/twenty-server/src/engine/core-modules/upgrade/services/workspace-command-runner.service.ts+++ b/packages/twenty-server/src/engine/core-modules/upgrade/services/workspace-command-runner.service.ts@@ -6,6 +6,7 @@ import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twentimport { type RegisteredWorkspaceCommand } from 'src/engine/core-modules/upgrade/services/upgrade-command-registry.service';import { UpgradeMigrationService } from 'src/engine/core-modules/upgrade/services/upgrade-migration.service';import { UpgradeStatusService } from 'src/engine/core-modules/upgrade/services/upgrade-status.service';+import { formatUpgradeLog } from 'src/engine/core-modules/upgrade/utils/format-upgrade-log.util';type WorkspaceCommandEntry = Pick<RegisteredWorkspaceCommand,@@ -35,8 +36,19 @@ export class WorkspaceCommandRunnerService {}: RunWorkspaceCommandsArgs): Promise<void> {const { workspaceId, index, total } = iteratorContext;+ const dryRunPrefix = options.dryRun ? '(dry run) ' : '';+this.logger.log(- `${options.dryRun ? '(dry run) ' : ''}Upgrading workspace ${workspaceId} ${index + 1}/${total}`,+ formatUpgradeLog({+ humanMessage: `${dryRunPrefix}Upgrading workspace ${workspaceId} ${index + 1}/${total}`,+ event: 'workspace.start',+ logFields: {+ workspaceId,+ index: index + 1,+ total,+ dryRun: options.dryRun ?? false,+ },+ }),);const executedByVersion =@@ -53,7 +65,17 @@ export class WorkspaceCommandRunnerService {});}- this.logger.log(`Upgrade for workspace ${workspaceId} completed.`);+ this.logger.log(+ formatUpgradeLog({+ humanMessage: `Upgrade for workspace ${workspaceId} completed.`,+ event: 'workspace.success',+ logFields: {+ workspaceId,+ executedByVersion,+ dryRun: options.dryRun ?? false,+ },+ }),+ );} finally {if (!options.dryRun) {await this.safeInvalidateWorkspace(workspaceId);@@ -65,10 +87,18 @@ export class WorkspaceCommandRunnerService {try {await this.upgradeStatusService.invalidateInstanceAndAllWorkspacesStatus();} catch (error) {+ const errorMessage =+ error instanceof Error ? error.message : String(error);+this.logger.warn(- `Failed to invalidate upgrade-status cache for workspace ${workspaceId}: ${- error instanceof Error ? error.message : String(error)- }`,+ formatUpgradeLog({+ humanMessage: `Failed to invalidate upgrade-status cache (triggered by workspace ${workspaceId}): ${errorMessage}`,+ event: 'cache.invalidate.failed',+ logFields: {+ scope: 'instance-and-all-workspaces',+ triggeredByWorkspaceId: workspaceId,+ },+ }),);}}diff --git a/packages/twenty-server/src/engine/core-modules/upgrade/utils/__tests__/format-upgrade-log.util.spec.ts b/packages/twenty-server/src/engine/core-modules/upgrade/utils/__tests__/format-upgrade-log.util.spec.tsnew file mode 100644index 00000000000..3e301aaa103--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/upgrade/utils/__tests__/format-upgrade-log.util.spec.ts@@ -0,0 +1,149 @@+import { formatUpgradeLog } from 'src/engine/core-modules/upgrade/utils/format-upgrade-log.util';++describe('formatUpgradeLog', () => {+ it('emits humanMessage on its own lines followed by a single-line "[upgrade] event=<event>" tail', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'Upgrade for workspace abc-123 completed.',+ event: 'workspace.success',+ }),+ ).toMatchInlineSnapshot(`+"Upgrade for workspace abc-123 completed.+[upgrade] event=workspace.success"+`);+ });++ it('serializes numeric, boolean and string logFields after the humanMessage', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'Upgrading workspace abc-123 1/10',+ event: 'workspace.start',+ logFields: {+ workspaceId: 'abc-123',+ index: 1,+ total: 10,+ dryRun: false,+ },+ }),+ ).toMatchInlineSnapshot(`+"Upgrading workspace abc-123 1/10+[upgrade] event=workspace.start workspaceId=abc-123 index=1 total=10 dryRun=false"+`);+ });++ it('matches the summary call site emitted by UpgradeCommand at the end of a run', () => {+ expect(+ formatUpgradeLog({+ humanMessage:+ 'Upgrade summary: 42 workspace(s) succeeded, 1 workspace(s) failed',+ event: 'summary',+ logFields: {+ totalSuccesses: 42,+ totalFailures: 1,+ dryRun: false,+ },+ }),+ ).toMatchInlineSnapshot(`+"Upgrade summary: 42 workspace(s) succeeded, 1 workspace(s) failed+[upgrade] event=summary totalSuccesses=42 totalFailures=1 dryRun=false"+`);+ });++ it('preserves a multi-line humanMessage as-is and keeps the structured tail on its own single line', () => {+ const errorMessage =+ 'Workspace migration runner failed:\n - Option id is required\n - Option id is invalid';++ expect(+ formatUpgradeLog({+ humanMessage: `Upgrade failed: ${errorMessage}`,+ event: 'aborted',+ logFields: {+ totalSuccesses: 41,+ totalFailures: 2,+ dryRun: false,+ },+ }),+ ).toMatchInlineSnapshot(`+"Upgrade failed: Workspace migration runner failed:+ - Option id is required+ - Option id is invalid+[upgrade] event=aborted totalSuccesses=41 totalFailures=2 dryRun=false"+`);+ });++ it('emits null and undefined logFields explicitly', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'migration-foo executed successfully',+ event: 'instance.success',+ logFields: {+ command: 'migration-foo',+ error: undefined,+ executedByVersion: null,+ },+ }),+ ).toMatchInlineSnapshot(`+"migration-foo executed successfully+[upgrade] event=instance.success command=migration-foo error=undefined executedByVersion=null"+`);+ });++ it('quotes values containing whitespace, quotes or equals signs', () => {+ expect(+ formatUpgradeLog({+ humanMessage:+ 'Workspace abc failed on migrate-foo: Connection timed out',+ event: 'workspace.failed',+ logFields: {+ workspaceId: 'abc',+ command: 'migrate-foo',+ },+ }),+ ).toMatchInlineSnapshot(`+"Workspace abc failed on migrate-foo: Connection timed out+[upgrade] event=workspace.failed workspaceId=abc command=migrate-foo"+`);+ });++ it('escapes embedded quotes and backslashes in logField values', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'Workspace abc failed',+ event: 'workspace.failed',+ logFields: {+ reason: 'bad "quote" and \\ backslash',+ },+ }),+ ).toMatchInlineSnapshot(`+"Workspace abc failed+[upgrade] event=workspace.failed reason="bad \\"quote\\" and \\\\ backslash""+`);+ });++ it('keeps multi-line logField values on a single log line via \\n / \\r / \\t escaping', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'Workspace abc failed',+ event: 'workspace.failed',+ logFields: {+ reason: 'line one\nline two\rline three\ttab',+ },+ }),+ ).toMatchInlineSnapshot(`+"Workspace abc failed+[upgrade] event=workspace.failed reason="line one\\nline two\\rline three\\ttab""+`);+ });++ it('escapes an event name containing whitespace or =', () => {+ expect(+ formatUpgradeLog({+ humanMessage: 'Something happened',+ event: 'weird event=with-equals',+ }),+ ).toMatchInlineSnapshot(`+"Something happened+[upgrade] event="weird event=with-equals""+`);+ });+});diff --git a/packages/twenty-server/src/engine/core-modules/upgrade/utils/format-upgrade-log.util.ts b/packages/twenty-server/src/engine/core-modules/upgrade/utils/format-upgrade-log.util.tsnew file mode 100644index 00000000000..490db9ccc36--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/upgrade/utils/format-upgrade-log.util.ts@@ -0,0 +1,49 @@+import { isDefined } from 'twenty-shared/utils';++type UpgradeLogScalar = string | number | boolean;++type UpgradeLogFields = Record<string, UpgradeLogScalar | null | undefined>;++type FormatUpgradeLogParams = {+ humanMessage: string;+ event: string;+ logFields?: UpgradeLogFields;+};++const UPGRADE_LOG_PREFIX = '[upgrade]';++const NEEDS_QUOTING = /[\s"=]/;+const CONTROL_CHARACTERS = /[\n\r\t]/;++const escapeLogValue = (value: UpgradeLogScalar): string => {+ const raw = String(value);++ if (!NEEDS_QUOTING.test(raw) && !CONTROL_CHARACTERS.test(raw)) {+ return raw;+ }++ const escaped = raw+ .replace(/\\/g, '\\\\')+ .replace(/"/g, '\\"')+ .replace(/\n/g, '\\n')+ .replace(/\r/g, '\\r')+ .replace(/\t/g, '\\t');++ return `"${escaped}"`;+};++export const formatUpgradeLog = ({+ humanMessage,+ event,+ logFields = {},+}: FormatUpgradeLogParams): string => {+ const tailParts: string[] = [`event=${escapeLogValue(event)}`];++ for (const [key, value] of Object.entries(logFields)) {+ tailParts.push(+ `${key}=${isDefined(value) ? escapeLogValue(value) : String(value)}`,+ );+ }++ return `${humanMessage}\n${UPGRADE_LOG_PREFIX} ${tailParts.join(' ')}`;+};