feat: add flatten: 'otel' and otelAttributesFormat for winston-transport 0.29+ (2.3.0)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerx/node-winston",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "private": false,
   "description": "A set of winston formats, console transport and logger creation functions",
   "author": "MakerX",
@@ -47,6 +47,10 @@
     "@makerx/node-common": "^1.5.0",
     "@makerx/prettier-config": "2.0.1",
     "@makerx/ts-toolkit": "^5.0.0-beta.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.223.0",
+    "@opentelemetry/sdk-logs": "^0.223.0",
+    "@opentelemetry/winston-transport": "^0.34.0",
     "@rollup/plugin-commonjs": "29.0.2",
     "@rollup/plugin-typescript": "^12.3.0",
     "@tsconfig/node20": "20.1.9",
@@ -62,6 +66,8 @@
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^5.5.5",
     "npm-run-all": "^4.1.5",
+    "otel-winston-transport-0.27": "npm:@opentelemetry/winston-transport@^0.27.0",
+    "otel-winston-transport-0.31": "npm:@opentelemetry/winston-transport@^0.31.0",
     "rimraf": "^6.1.3",
     "rollup": "4.60.2",
     "tslib": "^2.8.1",

src/index.ts

@@ -9,6 +9,7 @@ import {
 } from 'winston'
 import * as Transport from 'winston-transport'
 import { jsonStringifyValuesFormat } from './json-stringify-values-format'
+import { otelAttributesFormat } from './otel-attributes-format'
 import { omitFormat } from './omit-format'
 import { omitNilFormat } from './omit-nil-format'
 import { prettyConsoleFormat } from './pretty-console-format'
@@ -36,6 +37,7 @@ export * from './redact-values'
 export * from './serialize-error'
 export * from './serialize-error-format'
 export * from './map-audit-level-for-otel'
+export * from './otel-attributes-format'
 export * from './utils'
 
 // winstonjs' default levels have debug and verbose reversed, which is confusing and causes filtering issues with Seq,
@@ -153,16 +155,24 @@ export interface CreateLoggerOptions {
   redactedValue?: string
 
   /**
-   * When `true`, appends `jsonStringifyValuesFormat` as the final logger-level format — applied after every
-   * other logger-level format (including any `loggerOptions.format`) — serialising every top-level value on
-   * the log info to a JSON string. Produces a flat `{ key: string }` shape suitable for transports/aggregators
-   * that expect scalar values (e.g. OTEL + Azure Log Analytics).
+   * Appends a flattening format as the final logger-level format — applied after every other
+   * logger-level format (including any `loggerOptions.format`), so it affects every transport.
+   *
+   * - `'otel'` appends {@link otelAttributesFormat}: the shape `@opentelemetry/winston-transport` 0.29
+   *   and later needs. An `err`/`error` value stays an object holding `name`, `message` and `stack`,
+   *   which the transport records as the exception, the rest of the error goes to `<key>Detail` as
+   *   JSON, and every other object value becomes a JSON string.
+   * - `true` appends `jsonStringifyValuesFormat`, serialising every top-level object value — errors
+   *   included — to a JSON string. For a transport before 0.29; from 0.29 the transport records a
+   *   stringified error as one `exception.message` holding the whole JSON.
+   *
+   * To flatten only what one transport receives, put the format on that transport instead.
    */
-  flatten?: boolean
+  flatten?: boolean | 'otel'
 
   /**
-   * Optional `JSON.stringify` replacer forwarded to `flatten` when serialising each top-level value.
-   * Only applied when `flatten` is `true`.
+   * Optional `JSON.stringify` replacer forwarded to `flatten` when serialising each value.
+   * Applied in both `flatten` modes.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   flattenReplacer?: (this: any, key: string, value: any) => any
@@ -279,7 +289,8 @@ export function createLogger(options: CreateLoggerOptions): any {
   if (redactPaths) loggerFormats.push(redactFormat({ paths: redactPaths, redactedValue, errorSerializer }))
   if (options.loggerOptions?.format) loggerFormats.push(options.loggerOptions.format)
   // flatten is applied last so all prior transformations are captured in the stringified values
-  if (flatten) loggerFormats.push(jsonStringifyValuesFormat({ replacer: flattenReplacer }))
+  if (flatten === 'otel') loggerFormats.push(otelAttributesFormat({ replacer: flattenReplacer }))
+  else if (flatten) loggerFormats.push(jsonStringifyValuesFormat({ replacer: flattenReplacer }))
 
   // create logger options using supplied options + transports; loggerOptions.levels (if any) overrides defaultLevels
   const loggerOptions: LoggerOptions = {