v3: one OpenTelemetry setup, transport 0.29+, generic error shaping

.github/workflows/pr.yml

@@ -2,7 +2,7 @@ name: Pull Request
 
 on:
   pull_request:
-    branches: [main]
+    branches: [main, v2.x]
     paths-ignore:
       - '**/*.md'
 

eslint.config.mjs

@@ -34,4 +34,26 @@ export default [
       },
     },
   },
+  {
+    // The OpenTelemetry transport is an optional peer. Importing it, or `@opentelemetry/api-logs`, from
+    // the library would make it required and can add a second `api-logs` copy to an app. A transport
+    // that gets its logger from a second copy before the SDK registers its provider writes every line
+    // to a no-op logger. Specs and the fixture under src/tests import the real packages, which are
+    // dev dependencies.
+    files: ['src/**/*.ts'],
+    ignores: ['src/**/*.spec.ts', 'src/tests/**'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['@opentelemetry/*', 'otel-winston-transport-*'],
+              message: 'The library must not depend on OpenTelemetry packages. See the comment in eslint.config.mjs.',
+            },
+          ],
+        },
+      ],
+    },
+  },
 ]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerx/node-winston",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "private": false,
   "description": "A set of winston formats, console transport and logger creation functions",
   "author": "MakerX",
@@ -49,6 +49,7 @@
     "@makerx/ts-toolkit": "^5.0.0-beta.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.223.0",
+    "@opentelemetry/instrumentation-winston": "^0.68.1",
     "@opentelemetry/sdk-logs": "^0.223.0",
     "@opentelemetry/winston-transport": "^0.34.0",
     "@rollup/plugin-commonjs": "29.0.2",
@@ -66,8 +67,7 @@
     "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",
+    "otel-winston-transport-0.29": "npm:@opentelemetry/winston-transport@~0.29.0",
     "rimraf": "^6.1.3",
     "rollup": "4.60.2",
     "tslib": "^2.8.1",
@@ -76,12 +76,18 @@
     "vitest": "^4.1.12"
   },
   "peerDependencies": {
+    "@opentelemetry/winston-transport": ">=0.29",
     "es-toolkit": ">=1",
     "logform": ">=2",
     "triple-beam": ">=1",
     "winston": ">=3",
     "winston-transport": ">=4"
   },
+  "peerDependenciesMeta": {
+    "@opentelemetry/winston-transport": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@colors/colors": "^1.6.0",
     "yamlify-object": "^3.0.0",

scripts/smoke-cjs.cjs

@@ -13,19 +13,28 @@ const expectedFns = [
   'createSerializableErrorReplacer',
   'serializableErrorReplacer',
   'serializeErrorFormat',
+  'createErrorSerializer',
   'createLogger',
+  'otelAttributesFormat',
+  'mapAuditLevelForOtel',
   'jsonStringifyValuesFormat',
   'redactFormat',
   'omitFormat',
   'omitNilFormat',
   'prettyConsoleFormat',
+  'CallbackTransport',
 ]
 const missing = expectedFns.filter((name) => typeof main[name] !== 'function')
 if (missing.length > 0) {
   console.error(`CJS smoke: missing or non-function exports: ${missing.join(', ')}`)
   process.exit(1)
 }
 
+if (distPkg.peerDependenciesMeta?.['@opentelemetry/winston-transport']?.optional !== true) {
+  console.error('CJS smoke: dist/package.json does not mark @opentelemetry/winston-transport as an optional peer')
+  process.exit(1)
+}
+
 const err = new Error('boom')
 err.cause = new Error('cause')
 const out = main.serializeError(err)
@@ -37,4 +46,7 @@ if (!out || out.message !== 'boom' || !out.cause || out.cause.message !== 'cause
 const logger = main.createLogger({ name: 'smoke', consoleOptions: { silent: true } })
 logger.info('cjs smoke ok')
 
+const otelLogger = main.createLogger({ otel: true, consoleOptions: { silent: true } })
+otelLogger.audit('cjs smoke otel ok', { error: err })
+
 console.log('CJS smoke test passed')

src/audit-level.ts

@@ -0,0 +1,18 @@
+// Internal: deliberately not re-exported from index.ts.
+import { type TransformableInfo } from 'logform'
+import { LEVEL } from 'triple-beam'
+
+/**
+ * Copies the record's level onto `logLevel`, and exports an `audit` record at `info` severity.
+ *
+ * The level is read from the triple-beam `LEVEL` symbol, because a format such as
+ * `format.colorize()` rewrites the string `level`. A `logLevel` the record already has is kept,
+ * so a second pass leaves `logLevel` at `audit` after the first pass has changed `LEVEL`.
+ * See `mapAuditLevelForOtel` for why the mapping exists.
+ */
+export const applyAuditLevelMapping = (info: TransformableInfo): TransformableInfo => {
+  const level = info[LEVEL] as string | undefined
+  if (typeof info.logLevel !== 'string') info.logLevel = level
+  if (level === 'audit') info[LEVEL] = 'info'
+  return info
+}