Skip to content

feat(winston): Add customLevelMap for winston transport #18922

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JPeer264 wants to merge 4 commits into
base: develop
Choose a base branch
from
+326 −1
Open

feat(winston): Add customLevelMap for winston transport #18922

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8ef1584
feat(winston): Add customLevelMap for winston transport
JPeer264 Jan 21, 2026
e388d33
fixup! feat(winston): Add customLevelMap for winston transport
JPeer264 Jan 26, 2026
f662b63
fix: Switch to ts-ignore. ts-expect-error was introduced in TS3.9
JPeer264 Jan 26, 2026
2f4c56e
fixup! feat(winston): Add customLevelMap for winston transport
JPeer264 Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions dev-packages/node-integration-tests/suites/winston/subject.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Sentry.init({
environment: 'test',
enableLogs: true,
transport: loggingTransport,
debug: true,
});

async function run(): Promise<void> {
Expand Down Expand Up @@ -64,6 +65,81 @@ async function run(): Promise<void> {
});
}

if (process.env.WITH_FILTER === 'true') {
const FilteredSentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
levels: ['error'],
});
const filteredLogger = winston.createLogger({
transports: [new FilteredSentryWinstonTransport()],
});

filteredLogger.info('Ignored message');
filteredLogger.error('Test error message');
}

// If unmapped custom level is requested (tests debug line for unknown levels)
if (process.env.UNMAPPED_CUSTOM_LEVEL === 'true') {
const customLevels = {
levels: {
myUnknownLevel: 0,
error: 1,
},
};

// Create transport WITHOUT customLevelMap for myUnknownLevel
// myUnknownLevel will default to 'info', but we only capture 'error'
const UnmappedSentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
levels: ['error'],
});

const unmappedLogger = winston.createLogger({
levels: customLevels.levels,
level: 'error',
transports: [new UnmappedSentryWinstonTransport()],
});

// This should NOT be captured (unknown level defaults to 'info', which is not in levels)
// @ts-ignore - custom levels are not part of the winston logger
unmappedLogger.myUnknownLevel('This unknown level message should be skipped');
// This SHOULD be captured
unmappedLogger.error('This error message should be captured');
}

// If custom level mapping is requested
if (process.env.CUSTOM_LEVEL_MAPPING === 'true') {
const customLevels = {
levels: {
customCritical: 0,
customWarning: 1,
customNotice: 2,
},
};

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

const mappedLogger = winston.createLogger({
levels: customLevels.levels,
// https://github.com/winstonjs/winston/issues/1491
// when custom levels are set with a transport,
// the level must be set on the logger
level: 'customNotice',
transports: [new SentryWinstonTransport()],
});

// @ts-ignore - custom levels are not part of the winston logger
mappedLogger.customCritical('This is a critical message');
// @ts-ignore - custom levels are not part of the winston logger
mappedLogger.customWarning('This is a warning message');
// @ts-ignore - custom levels are not part of the winston logger
mappedLogger.customNotice('This is a notice message');
}

await Sentry.flush();
}

Expand Down
223 changes: 223 additions & 0 deletions dev-packages/node-integration-tests/suites/winston/test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,71 @@ describe('winston integration', () => {
await runner.completed();
});

test("should capture winston logs with filter but don't show custom level warnings", async () => {
const runner = createRunner(__dirname, 'subject.ts')
.withEnv({ WITH_FILTER: 'true' })
.expect({
log: {
items: [
{
timestamp: expect.any(Number),
level: 'info',
body: 'Test info message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'error',
body: 'Test error message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'error',
body: 'Test error message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
],
},
})
.start();

await runner.completed();

const logs = runner.getLogs();

const warning = logs.find(log => log.includes('Winston log level info is not captured by Sentry.'));

expect(warning).not.toBeDefined();
});

test('should capture winston logs with metadata', async () => {
const runner = createRunner(__dirname, 'subject.ts')
.withEnv({ WITH_METADATA: 'true' })
Expand Down Expand Up @@ -183,4 +248,162 @@ describe('winston integration', () => {

await runner.completed();
});

test('should skip unmapped custom levels when not in the levels option', async () => {
const runner = createRunner(__dirname, 'subject.ts')
.withEnv({ UNMAPPED_CUSTOM_LEVEL: 'true' })
.expect({
log: {
items: [
// First, the default logger captures info and error
{
timestamp: expect.any(Number),
level: 'info',
body: 'Test info message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'error',
body: 'Test error message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
// Then the unmapped logger only captures error (myUnknownLevel defaults to info, which is skipped)
{
timestamp: expect.any(Number),
level: 'error',
body: 'This error message should be captured',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
],
},
})
.start();

await runner.completed();

const logs = runner.getLogs();

const warning = logs.find(log => log.includes('Winston log level myUnknownLevel is not captured by Sentry.'));

expect(warning).toBeDefined();
});

test('should map custom winston levels to Sentry severity levels', async () => {
const runner = createRunner(__dirname, 'subject.ts')
.withEnv({ CUSTOM_LEVEL_MAPPING: 'true' })
.expect({
log: {
items: [
// First, the default logger captures info and error
{
timestamp: expect.any(Number),
level: 'info',
body: 'Test info message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'error',
body: 'Test error message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
// Then the mapped logger uses custom level mappings
{
timestamp: expect.any(Number),
level: 'fatal', // 'critical' maps to 'fatal'
body: 'This is a critical message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'warn', // 'warning' maps to 'warn'
body: 'This is a warning message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
{
timestamp: expect.any(Number),
level: 'info', // 'notice' maps to 'info'
body: 'This is a notice message',
severity_number: expect.any(Number),
trace_id: expect.any(String),
attributes: {
'sentry.origin': { value: 'auto.log.winston', type: 'string' },
'sentry.release': { value: '1.0.0', type: 'string' },
'sentry.environment': { value: 'test', type: 'string' },
'sentry.sdk.name': { value: 'sentry.javascript.node', type: 'string' },
'sentry.sdk.version': { value: expect.any(String), type: 'string' },
'server.address': { value: expect.any(String), type: 'string' },
},
},
],
},
})
.start();

await runner.completed();
});
});
28 changes: 27 additions & 1 deletion packages/node-core/src/integrations/winston.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
/* eslint-disable @typescript-eslint/ban-ts-comment */
import type { LogSeverityLevel } from '@sentry/core';
import { debug } from '@sentry/core';
import { DEBUG_BUILD } from '../debug-build';
import { captureLog } from '../logs/capture';

const DEFAULT_CAPTURED_LEVELS: Array<LogSeverityLevel> = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
Expand All @@ -25,6 +27,21 @@ interface WinstonTransportOptions {
* ```
*/
levels?: Array<LogSeverityLevel>;

/**
* Use this option to map custom levels to Sentry log severity levels.
*
* @example
* ```ts
* const SentryWinstonTransport = Sentry.createSentryWinstonTransport(Transport, {
* customLevelMap: {
* myCustomLevel: 'info',
* customError: 'error',
* },
* });
* ```
*/
customLevelMap?: Record<string, LogSeverityLevel>;
}

/**
Expand Down Expand Up @@ -85,12 +102,21 @@ export function createSentryWinstonTransport<TransportStreamInstance extends obj
attributes[MESSAGE_SYMBOL] = undefined;
attributes[SPLAT_SYMBOL] = undefined;

const logSeverityLevel = WINSTON_LEVEL_TO_LOG_SEVERITY_LEVEL_MAP[levelFromSymbol as string] ?? 'info';
const customLevel = sentryWinstonOptions?.customLevelMap?.[levelFromSymbol as string];
Copy link
Member

@nicohrubec nicohrubec Jan 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@JPeer264 JPeer264 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That could actually make sense

Copy link
Member Author

@JPeer264 JPeer264 Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

const winstonLogLevel = WINSTON_LEVEL_TO_LOG_SEVERITY_LEVEL_MAP[levelFromSymbol as string]
const logSeverityLevel =
customLevel ?? winstonLogLevel ?? 'info';

if (this._levels.has(logSeverityLevel)) {
captureLog(logSeverityLevel, message as string, {
...attributes,
'sentry.origin': 'auto.log.winston',
});
} else if (!customLevel && !winstonLogLevel) {
DEBUG_BUILD &&
debug.log(
`Winston log level ${levelFromSymbol} is not captured by Sentry. Please add ${levelFromSymbol} to the "customLevelMap" option of the Sentry Winston transport.`,
);
}
} catch {
// do nothing
Expand Down
Loading