feat(winston): Add customLevelMap for winston transport

[JPeer264]

closes #18868
closes JS-1498

ATM it is not possible to map custom levels to OpenTelemetry levels. The option customLevelMap has been added to make this possible. Which means that custom levels would have never been send to Sentry, as they were not mapped correctly.

Now when there are custom levels it can be used like this:

const customLevels = {
  levels: {
    customCritical: 0,
    customNotice: 2,
  },
};

const SentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
  customLevelMap: {
    customCritical: 'fatal',
    customNotice: 'info',
  },
});

const mappedLogger = winston.createLogger({
  levels: customLevels.levels,
  level: 'customNotice', // this needs to be added due to https://github.com/winstonjs/winston/issues/1491
  transports: [new SentryWinstonTransport()],
});

Merge checklist

• Sentry Docs update issue has been created

[linear]

JS-1498 Allow customization of level mapping in `createSentryWinstonTransport`

[github-actions]

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.
⚠️ Warning: Base artifact is not the latest one, because the latest workflow run is not done yet. This may lead to incorrect results. Try to re-run all tests to get up to date results.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	9,205	-	9,102	+1%
GET With Sentry	1,652	18%	1,700	-3%
GET With Sentry (error only)	6,026	65%	6,128	-2%
POST Baseline	1,181	-	1,209	-2%
POST With Sentry	585	50%	578	+1%
POST With Sentry (error only)	1,035	88%	1,040	-0%
MYSQL Baseline	3,332	-	3,271	+2%
MYSQL With Sentry	465	14%	409	+14%
MYSQL With Sentry (error only)	2,692	81%	2,637	+2%

View base workflow run

[s1gr1d]

Looks good, but I am wondering if we can auto-detect those levels so users don't have to manually add them 🤔

[nicohrubec]

m: would it make sense to warn the user in case he provides a sentry level that does not exist?

[JPeer264]

That could actually make sense

[JPeer264]

@nicohrubec I added a debug warning now. This is however only then when levels are overwritten. In all other cases they will default to info already

[JPeer264]

I am wondering if we can auto-detect those levels so users don't have to manually add them 🤔

That shouldn't be a problem. The main problem is what it should get mapped to. myCustomLevel would be impossible for us to identify if this is an error or info

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Warning message misleads for known winston levels

Low Severity

The debug warning condition at line 114 (else if (!customLevel)) fires for known winston levels (like warn, info, http) when they're excluded via the levels option. The warning message tells users to add the level to customLevelMap, but for known levels that already exist in WINSTON_LEVEL_TO_LOG_SEVERITY_LEVEL_MAP, this suggestion is misleading since adding { warn: 'warn' } wouldn't change anything. The condition needs to also verify the level is truly unknown (not in the built-in map) before recommending customLevelMap.

 

[nicohrubec]

nice