Skip to content

Commit 11f38a7

Browse files
JPeer264JPeer264
authored
feat(winston): Add customLevelMap for winston transport (#18922)
closes #18868 closes [JS-1498](https://linear.app/getsentry/issue/JS-1498/allow-customization-of-level-mapping-in-createsentrywinstontransport) 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: ```js 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 winstonjs/winston#1491 transports: [new SentryWinstonTransport()], }); ``` ### Merge checklist - [ ] Sentry Docs update issue has been created
1 parent 93a91cc commit 11f38a7

3 files changed

Lines changed: 325 additions & 1 deletion

File tree

‎dev-packages/node-integration-tests/suites/winston/subject.ts‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Sentry.init({
99
environment: 'test',
1010
enableLogs: true,
1111
transport: loggingTransport,
12+
debug: true,
1213
});
1314

1415
async function run(): Promise<void> {
@@ -64,6 +65,81 @@ async function run(): Promise<void> {
6465
});
6566
}
6667

68+
if (process.env.WITH_FILTER === 'true') {
69+
const FilteredSentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
70+
levels: ['error'],
71+
});
72+
const filteredLogger = winston.createLogger({
73+
transports: [new FilteredSentryWinstonTransport()],
74+
});
75+
76+
filteredLogger.info('Ignored message');
77+
filteredLogger.error('Test error message');
78+
}
79+
80+
// If unmapped custom level is requested (tests debug line for unknown levels)
81+
if (process.env.UNMAPPED_CUSTOM_LEVEL === 'true') {
82+
const customLevels = {
83+
levels: {
84+
myUnknownLevel: 0,
85+
error: 1,
86+
},
87+
};
88+
89+
// Create transport WITHOUT customLevelMap for myUnknownLevel
90+
// myUnknownLevel will default to 'info', but we only capture 'error'
91+
const UnmappedSentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
92+
levels: ['error'],
93+
});
94+
95+
const unmappedLogger = winston.createLogger({
96+
levels: customLevels.levels,
97+
level: 'error',
98+
transports: [new UnmappedSentryWinstonTransport()],
99+
});
100+
101+
// This should NOT be captured (unknown level defaults to 'info', which is not in levels)
102+
// @ts-ignore - custom levels are not part of the winston logger
103+
unmappedLogger.myUnknownLevel('This unknown level message should be skipped');
104+
// This SHOULD be captured
105+
unmappedLogger.error('This error message should be captured');
106+
}
107+
108+
// If custom level mapping is requested
109+
if (process.env.CUSTOM_LEVEL_MAPPING === 'true') {
110+
const customLevels = {
111+
levels: {
112+
customCritical: 0,
113+
customWarning: 1,
114+
customNotice: 2,
115+
},
116+
};
117+
118+
const SentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
119+
customLevelMap: {
120+
customCritical: 'fatal',
121+
customWarning: 'warn',
122+
customNotice: 'info',
123+
},
124+
});
125+
126+
const mappedLogger = winston.createLogger({
127+
levels: customLevels.levels,
128+
// https://github.com/winstonjs/winston/issues/1491
129+
// when custom levels are set with a transport,
130+
// the level must be set on the logger
131+
level: 'customNotice',
132+
transports: [new SentryWinstonTransport()],
133+
});
134+
135+
// @ts-ignore - custom levels are not part of the winston logger
136+
mappedLogger.customCritical('This is a critical message');
137+
// @ts-ignore - custom levels are not part of the winston logger
138+
mappedLogger.customWarning('This is a warning message');
139+
// @ts-ignore - custom levels are not part of the winston logger
140+
mappedLogger.customNotice('This is a notice message');
141+
}
142+
67143
await Sentry.flush();
68144
}
69145

‎dev-packages/node-integration-tests/suites/winston/test.ts‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,71 @@ describe('winston integration', () => {
123123
await runner.completed();
124124
});
125125

126+
test("should capture winston logs with filter but don't show custom level warnings", async () => {
127+
const runner = createRunner(__dirname, 'subject.ts')
128+
.withEnv({ WITH_FILTER: 'true' })
129+
.expect({
130+
log: {
131+
items: [
132+
{
133+
timestamp: expect.any(Number),
134+
level: 'info',
135+
body: 'Test info message',
136+
severity_number: expect.any(Number),
137+
trace_id: expect.any(String),
138+
attributes: {
139+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
140+
'sentry.release': { value: '1.0.0', type: 'string' },
141+
'sentry.environment': { value: 'test', type: 'string' },
142+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
143+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
144+
'server.address': { value: expect.any(String), type: 'string' },
145+
},
146+
},
147+
{
148+
timestamp: expect.any(Number),
149+
level: 'error',
150+
body: 'Test error message',
151+
severity_number: expect.any(Number),
152+
trace_id: expect.any(String),
153+
attributes: {
154+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
155+
'sentry.release': { value: '1.0.0', type: 'string' },
156+
'sentry.environment': { value: 'test', type: 'string' },
157+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
158+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
159+
'server.address': { value: expect.any(String), type: 'string' },
160+
},
161+
},
162+
{
163+
timestamp: expect.any(Number),
164+
level: 'error',
165+
body: 'Test error message',
166+
severity_number: expect.any(Number),
167+
trace_id: expect.any(String),
168+
attributes: {
169+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
170+
'sentry.release': { value: '1.0.0', type: 'string' },
171+
'sentry.environment': { value: 'test', type: 'string' },
172+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
173+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
174+
'server.address': { value: expect.any(String), type: 'string' },
175+
},
176+
},
177+
],
178+
},
179+
})
180+
.start();
181+
182+
await runner.completed();
183+
184+
const logs = runner.getLogs();
185+
186+
const warning = logs.find(log => log.includes('Winston log level info is not captured by Sentry.'));
187+
188+
expect(warning).not.toBeDefined();
189+
});
190+
126191
test('should capture winston logs with metadata', async () => {
127192
const runner = createRunner(__dirname, 'subject.ts')
128193
.withEnv({ WITH_METADATA: 'true' })
@@ -183,4 +248,162 @@ describe('winston integration', () => {
183248

184249
await runner.completed();
185250
});
251+
252+
test('should skip unmapped custom levels when not in the levels option', async () => {
253+
const runner = createRunner(__dirname, 'subject.ts')
254+
.withEnv({ UNMAPPED_CUSTOM_LEVEL: 'true' })
255+
.expect({
256+
log: {
257+
items: [
258+
// First, the default logger captures info and error
259+
{
260+
timestamp: expect.any(Number),
261+
level: 'info',
262+
body: 'Test info message',
263+
severity_number: expect.any(Number),
264+
trace_id: expect.any(String),
265+
attributes: {
266+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
267+
'sentry.release': { value: '1.0.0', type: 'string' },
268+
'sentry.environment': { value: 'test', type: 'string' },
269+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
270+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
271+
'server.address': { value: expect.any(String), type: 'string' },
272+
},
273+
},
274+
{
275+
timestamp: expect.any(Number),
276+
level: 'error',
277+
body: 'Test error message',
278+
severity_number: expect.any(Number),
279+
trace_id: expect.any(String),
280+
attributes: {
281+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
282+
'sentry.release': { value: '1.0.0', type: 'string' },
283+
'sentry.environment': { value: 'test', type: 'string' },
284+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
285+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
286+
'server.address': { value: expect.any(String), type: 'string' },
287+
},
288+
},
289+
// Then the unmapped logger only captures error (myUnknownLevel defaults to info, which is skipped)
290+
{
291+
timestamp: expect.any(Number),
292+
level: 'error',
293+
body: 'This error message should be captured',
294+
severity_number: expect.any(Number),
295+
trace_id: expect.any(String),
296+
attributes: {
297+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
298+
'sentry.release': { value: '1.0.0', type: 'string' },
299+
'sentry.environment': { value: 'test', type: 'string' },
300+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
301+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
302+
'server.address': { value: expect.any(String), type: 'string' },
303+
},
304+
},
305+
],
306+
},
307+
})
308+
.start();
309+
310+
await runner.completed();
311+
312+
const logs = runner.getLogs();
313+
314+
const warning = logs.find(log => log.includes('Winston log level myUnknownLevel is not captured by Sentry.'));
315+
316+
expect(warning).toBeDefined();
317+
});
318+
319+
test('should map custom winston levels to Sentry severity levels', async () => {
320+
const runner = createRunner(__dirname, 'subject.ts')
321+
.withEnv({ CUSTOM_LEVEL_MAPPING: 'true' })
322+
.expect({
323+
log: {
324+
items: [
325+
// First, the default logger captures info and error
326+
{
327+
timestamp: expect.any(Number),
328+
level: 'info',
329+
body: 'Test info message',
330+
severity_number: expect.any(Number),
331+
trace_id: expect.any(String),
332+
attributes: {
333+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
334+
'sentry.release': { value: '1.0.0', type: 'string' },
335+
'sentry.environment': { value: 'test', type: 'string' },
336+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
337+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
338+
'server.address': { value: expect.any(String), type: 'string' },
339+
},
340+
},
341+
{
342+
timestamp: expect.any(Number),
343+
level: 'error',
344+
body: 'Test error message',
345+
severity_number: expect.any(Number),
346+
trace_id: expect.any(String),
347+
attributes: {
348+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
349+
'sentry.release': { value: '1.0.0', type: 'string' },
350+
'sentry.environment': { value: 'test', type: 'string' },
351+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
352+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
353+
'server.address': { value: expect.any(String), type: 'string' },
354+
},
355+
},
356+
// Then the mapped logger uses custom level mappings
357+
{
358+
timestamp: expect.any(Number),
359+
level: 'fatal', // 'critical' maps to 'fatal'
360+
body: 'This is a critical message',
361+
severity_number: expect.any(Number),
362+
trace_id: expect.any(String),
363+
attributes: {
364+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
365+
'sentry.release': { value: '1.0.0', type: 'string' },
366+
'sentry.environment': { value: 'test', type: 'string' },
367+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
368+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
369+
'server.address': { value: expect.any(String), type: 'string' },
370+
},
371+
},
372+
{
373+
timestamp: expect.any(Number),
374+
level: 'warn', // 'warning' maps to 'warn'
375+
body: 'This is a warning message',
376+
severity_number: expect.any(Number),
377+
trace_id: expect.any(String),
378+
attributes: {
379+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
380+
'sentry.release': { value: '1.0.0', type: 'string' },
381+
'sentry.environment': { value: 'test', type: 'string' },
382+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
383+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
384+
'server.address': { value: expect.any(String), type: 'string' },
385+
},
386+
},
387+
{
388+
timestamp: expect.any(Number),
389+
level: 'info', // 'notice' maps to 'info'
390+
body: 'This is a notice message',
391+
severity_number: expect.any(Number),
392+
trace_id: expect.any(String),
393+
attributes: {
394+
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
395+
'sentry.release': { value: '1.0.0', type: 'string' },
396+
'sentry.environment': { value: 'test', type: 'string' },
397+
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
398+
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
399+
'server.address': { value: expect.any(String), type: 'string' },
400+
},
401+
},
402+
],
403+
},
404+
})
405+
.start();
406+
407+
await runner.completed();
408+
});
186409
});

‎packages/node-core/src/integrations/winston.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
/* eslint-disable @typescript-eslint/ban-ts-comment */
22
import type { LogSeverityLevel } from '@sentry/core';
3+
import { debug } from '@sentry/core';
4+
import { DEBUG_BUILD } from '../debug-build';
35
import { captureLog } from '../logs/capture';
46

57
const DEFAULT_CAPTURED_LEVELS: Array<LogSeverityLevel> = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
@@ -25,6 +27,21 @@ interface WinstonTransportOptions {
2527
* ```
2628
*/
2729
levels?: Array<LogSeverityLevel>;
30+
31+
/**
32+
* Use this option to map custom levels to Sentry log severity levels.
33+
*
34+
* @example
35+
* ```ts
36+
* const SentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
37+
* customLevelMap: {
38+
* myCustomLevel: 'info',
39+
* customError: 'error',
40+
* },
41+
* });
42+
* ```
43+
*/
44+
customLevelMap?: Record<string, LogSeverityLevel>;
2845
}
2946

3047
/**
@@ -85,12 +102,20 @@ export function createSentryWinstonTransport<TransportStreamInstance extends obj
85102
attributes[MESSAGE_SYMBOL] = undefined;
86103
attributes[SPLAT_SYMBOL] = undefined;
87104

88-
const logSeverityLevel = WINSTON_LEVEL_TO_LOG_SEVERITY_LEVEL_MAP[levelFromSymbol as string] ?? 'info';
105+
const customLevel = sentryWinstonOptions?.customLevelMap?.[levelFromSymbol as string];
106+
const winstonLogLevel = WINSTON_LEVEL_TO_LOG_SEVERITY_LEVEL_MAP[levelFromSymbol as string];
107+
const logSeverityLevel = customLevel ?? winstonLogLevel ?? 'info';
108+
89109
if (this._levels.has(logSeverityLevel)) {
90110
captureLog(logSeverityLevel, message as string, {
91111
...attributes,
92112
'sentry.origin': 'auto.log.winston',
93113
});
114+
} else if (!customLevel && !winstonLogLevel) {
115+
DEBUG_BUILD &&
116+
debug.log(
117+
`Winston log level ${levelFromSymbol} is not captured by Sentry. Please add ${levelFromSymbol} to the "customLevelMap" option of the Sentry Winston transport.`,
118+
);
94119
}
95120
} catch {
96121
// do nothing

0 commit comments

Comments
 (0)