feat(formatter): Add YScope formatter for structured logs and remove Logback-style formatter.

src/components/modals/SettingsModal/SettingsDialog.tsx

@@ -33,8 +33,11 @@ import ThemeSwitchToggle from "./ThemeSwitchToggle";
 
 const CONFIG_FORM_FIELDS = [
     {
-        helperText: "[JSON] Log messages conversion pattern. The current syntax is similar to" +
-            " Logback conversion patterns but will change in a future release.",
+        helperText: `[JSON] Log messages conversion pattern. Add field-placeholders to insert
+        fields from JSON log events. A field-placeholder uses the following syntax:
+        \`{<field-name>[:<formatter-name>[:<formatter-options>]]}\`. \`field-name\` is required,
+        while \`formatter-name\` and \`formatter-options\` are optional. See the default pattern
+        for an example.`,
         initialValue: getConfig(CONFIG_KEY.DECODER_OPTIONS).formatString,
         label: "Decoder: Format string",
         name: LOCAL_STORAGE_KEY.DECODER_OPTIONS_FORMAT_STRING,

src/services/decoders/ClpIrDecoder.ts

@@ -12,7 +12,7 @@ import {
 import {Formatter} from "../../typings/formatters";
 import {JsonObject} from "../../typings/js";
 import {LogLevelFilter} from "../../typings/logs";
-import LogbackFormatter from "../formatters/LogbackFormatter";
+import YScopeFormatter from "../formatters/YScopeFormatter";
 import {
     convertToDayjsTimestamp,
     isJsonObject,
@@ -39,7 +39,7 @@ class ClpIrDecoder implements Decoder {
         this.#streamType = streamType;
         this.#streamReader = streamReader;
         this.#formatter = (streamType === CLP_IR_STREAM_TYPE.STRUCTURED) ?
-            new LogbackFormatter({formatString: decoderOptions.formatString}) :
+            new YScopeFormatter({formatString: decoderOptions.formatString}) :
             null;
     }
 
@@ -87,7 +87,7 @@ class ClpIrDecoder implements Decoder {
     }
 
     setFormatterOptions (options: DecoderOptions): boolean {
-        this.#formatter = new LogbackFormatter({formatString: options.formatString});
+        this.#formatter = new YScopeFormatter({formatString: options.formatString});
 
         return true;
     }

src/services/decoders/JsonlDecoder/index.ts

@@ -16,7 +16,7 @@ import {
     LogEvent,
     LogLevelFilter,
 } from "../../../typings/logs";
-import LogbackFormatter from "../../formatters/LogbackFormatter";
+import YscopeFormatter from "../../formatters/YScopeFormatter";
 import {
     convertToDayjsTimestamp,
     convertToLogLevelValue,
@@ -53,7 +53,7 @@ class JsonlDecoder implements Decoder {
         this.#dataArray = dataArray;
         this.#logLevelKey = decoderOptions.logLevelKey;
         this.#timestampKey = decoderOptions.timestampKey;
-        this.#formatter = new LogbackFormatter({formatString: decoderOptions.formatString});
+        this.#formatter = new YscopeFormatter({formatString: decoderOptions.formatString});
     }
 
     getEstimatedNumEvents (): number {
@@ -82,7 +82,7 @@ class JsonlDecoder implements Decoder {
     }
 
     setFormatterOptions (options: DecoderOptions): boolean {
-        this.#formatter = new LogbackFormatter({formatString: options.formatString});
+        this.#formatter = new YscopeFormatter({formatString: options.formatString});
 
         return true;
     }

src/services/formatters/YScopeFormatter/FieldFormatters/RoundFormatter.ts

@@ -0,0 +1,29 @@
+import {Nullable} from "../../../../typings/common";
+import {YScopeFieldFormatter} from "../../../../typings/formatters";
+import {JsonValue} from "../../../../typings/js";
+import {jsonValueToString} from "../utils";
+
+
+/**
+ * A field formatter that rounds numerical values to the nearest integer.
+ * If the field value is not a number, it is returned as-is after being
+ * converted to a string. Does not currently support any options.
+ */
+class RoundFormatter implements YScopeFieldFormatter {
+    constructor (options: Nullable<string>) {
+        if (null !== options) {
+            throw Error(`Round formatter does not support option ${options}`);
+        }
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    formatField (field: JsonValue): string {
+        if ("number" === typeof field) {
+            field = Math.round(field);
+        }
+
+        return jsonValueToString(field);
+    }
+}
+
+export default RoundFormatter;

src/services/formatters/YScopeFormatter/FieldFormatters/TimestampFormatter.ts

@@ -0,0 +1,36 @@
+import {Dayjs} from "dayjs";
+
+import {Nullable} from "../../../../typings/common";
+import {YScopeFieldFormatter} from "../../../../typings/formatters";
+import {JsonValue} from "../../../../typings/js";
+import {convertToDayjsTimestamp} from "../../../decoders/JsonlDecoder/utils";
+
+
+/**
+ * A formatter that formats timestamp values using a specified date-time pattern.
+ * If no pattern is provided as an option, the timestamp is formatted in the
+ * default ISO 8601 format.
+ */
+class TimestampFormatter implements YScopeFieldFormatter {
+    #dateFormat: Nullable<string> = null;
+
+    constructor (options: Nullable<string>) {
+        this.#dateFormat = options;
+    }
+
+    formatField (field: JsonValue): string {
+        // eslint-disable-next-line no-warning-comments
+        // TODO: We already parsed the timestamp during deserialization so this is perhaps
+        // inefficient. However, this field formatter can be used for multiple keys, so using
+        // the single parsed timestamp by itself would not work. Perhaps in future we can check
+        // if the key is the same as timestamp key and avoid parsing again.
+        const timestamp: Dayjs = convertToDayjsTimestamp(field);
+        if (null === this.#dateFormat) {
+            return timestamp.format();
+        }
+
+        return timestamp.format(this.#dateFormat);
+    }
+}
+
+export default TimestampFormatter;

src/services/formatters/YScopeFormatter/index.ts

@@ -0,0 +1,105 @@
+import {Nullable} from "../../../typings/common";
+import {
+    FIELD_PLACEHOLDER_REGEX,
+    Formatter,
+    FormatterOptionsType,
+    REPLACEMENT_CHARACTER_REGEX,
+    YScopeFieldFormatter,
+    YScopeFieldPlaceholder,
+} from "../../../typings/formatters";
+import {LogEvent} from "../../../typings/logs";
+import {
+    getFormattedField,
+    removeEscapeCharacters,
+    replaceDoubleBacklash,
+    splitFieldPlaceholder,
+    YSCOPE_FORMATTERS_MAP,
+} from "./utils";
+
+
+/**
+ * A formatter that uses a YScope format string to format log events into a string. See
+ * `YScopeFormatterOptionsType` for details about the format string.
+ */
+class YScopeFormatter implements Formatter {
+    readonly #processedFormatString: string;
+
+    #fieldPlaceholders: YScopeFieldPlaceholder[] = [];
+
+    constructor (options: FormatterOptionsType) {
+        if (REPLACEMENT_CHARACTER_REGEX.test(options.formatString)) {
+            console.log("Replacement character is an invalid character in format string." +
+                 "Replacement character will appear as \\.");
+        }
+
+        this.#processedFormatString = replaceDoubleBacklash(options.formatString);
+        this.#parseFieldPlaceholder();
+    }
+
+    formatLogEvent (logEvent: LogEvent): string {
+        let formattedLog = "";
+
+        // Keeps track of the last position in format string.
+        let lastIndex = 0;
+
+        for (const fieldPlaceholder of this.#fieldPlaceholders) {
+            const formatStringFragment =
+                this.#processedFormatString.slice(lastIndex, fieldPlaceholder.range.start);
+            const cleanedFragment = removeEscapeCharacters(formatStringFragment);
+
+            formattedLog += cleanedFragment;
+
+            formattedLog += getFormattedField(logEvent, fieldPlaceholder);
+            lastIndex = fieldPlaceholder.range.end;
+        }
+
+        const remainder = this.#processedFormatString.slice(lastIndex);
+        formattedLog += removeEscapeCharacters(remainder);
+
+        return `${formattedLog}\n`;
+    }
+
+    /**
+     * Parses field name, formatter name, and formatter options from placeholders in the format
+     * string. For each placeholder, it creates a corresponding `YScopeFieldFormatter` and adds
+     * it to the class-level array.
+     *
+     * @throws Error if `FIELD_PLACEHOLDER_REGEX` does not contain a capture group.
+     * @throws Error if a specified formatter is not supported.
+     */
+    #parseFieldPlaceholder () {
+        const placeholderPattern = new RegExp(FIELD_PLACEHOLDER_REGEX, "g");
+        const it = this.#processedFormatString.matchAll(placeholderPattern);
+        for (const match of it) {
+            // `fullMatch` includes braces and `groupMatch` excludes them.
+            const [fullMatch, groupMatch]: (string | undefined) [] = match;
+
+            if ("undefined" === typeof groupMatch) {
+                throw Error("Field placeholder regex is invalid and does not have a capture group");
+            }
+
+            const {fieldNameKeys, formatterName, formatterOptions} =
+                splitFieldPlaceholder(groupMatch);
+
+            let fieldFormatter: Nullable<YScopeFieldFormatter> = null;
+            if (null !== formatterName) {
+                const FieldFormatterConstructor = YSCOPE_FORMATTERS_MAP[formatterName];
+                if ("undefined" === typeof FieldFormatterConstructor) {
+                    throw Error(`Formatter ${formatterName} is not currently supported`);
+                }
+                fieldFormatter = new FieldFormatterConstructor(formatterOptions);
+            }
+
+            this.#fieldPlaceholders.push({
+                fieldNameKeys: fieldNameKeys,
+                fieldFormatter: fieldFormatter,
+                range: {
+                    start: match.index,
+                    end: match.index + fullMatch.length,
+                },
+            });
+        }
+    }
+}
+
+export default YScopeFormatter;