@syntaxza/slack-webhook-transport

A Slack transport for Winston 3+ that logs to a channel via webhooks.

Why

The original code for this module was created by @TheAppleFreak. You can find his NPM module here: Link

This module introduces retry logic in the slack webhook transport.

I would often find that messages being spammed through the original winston-slack-webhook-transport, would not arrive to selected slack channels during multiple lambda invocations and so messages were lost.

With bluebird-retry, we are able to retry those messages to the slack channel via the transport.

Installation

npm install winston @syntaxza/slack-webhook-transport

Usage

Set up with transports

const winston = require('winston');
const SlackHook = require('@syntaxza/slack-webhook-transport');

const logger = winston.createLogger({
	level: 'info',
	transports: [
		new SlackHook({
			webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx',
		}),
	],
});

logger.info('This should now appear on Slack');

Set up by adding

const winston = require('winston');
const SlackHook = require('@syntaxza/slack-webhook-transport');

const logger = winston.createLogger({});

logger.add(SlackHook, { webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx' });

Options

• webhookUrl - Slack incoming webhook URL. This can be from a basic integration or a bot. REQUIRED
• channel - Slack channel to post message to.
• username - Username to post message with.
• iconEmoji - Status icon to post message with. (interchangeable with iconUrl)
• iconUrl - Status icon to post message with. (interchangeable with iconEmoji)
• formatter - Custom function to format messages with. This function accepts the info object (see Winston documentation) and must return an object with at least one of the following three keys: text (string), attachments (array of attachment objects), blocks (array of layout block objects). These will be used to structure the format of the logged Slack message. By default, messages will use the format of [level]: [message] with no attachments or layout blocks.
• level - Level to log. Global settings will apply if this is blank.
• unfurlLinks - Enables or disables link unfurling. (Default: false)
• unfurlMedia - Enables or disables media unfurling. (Default: false)
• mrkdwn - Enables or disables mrkdwn formatting within attachments or layout blocks (Default: false)
• maxTransportInterval - Sets the max interval for the slack transport to deliver the message (Default: 500ms)
• maxTransportRetries - Sets the max amount of retries the slack transport will attempt to deliver the message (Default: 3)

Message formatting

@syntaxza/slack-webhook-transport supports the ability to format messages using Slack's message layout features. To do this, supply a custom formatter that supplies the requisite object structure to create the desired layout.

Note that if you're using the blocks feature, supplying the text parameter will cause it to function as a fallback for surfaces that do not support blocks, such as IRC clients or notifications.

const winston = require('winston');
const SlackHook = require('@syntaxza/slack-webhook-transport');

const logger = winston.createLogger({
	level: 'info',
	transports: [
		new SlackHook({
			webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx',
			formatter: (info) => {
				return {
					text: `${info.level}: ${info.message}`,
					attachments: [
						{
							text: "Or don't pass anything. That's fine too",
						},
					],
					blocks: [
						{
							type: 'section',
							text: {
								type: 'plain_text',
								text: 'You can pass more info to the formatter by supplying additional parameters in the logger call',
							},
						},
					],
				};
			},
		}),
	],
});

logger.info('Definitely try playing around with this.');