mozenge-winston-azure-transport v1.0.3

winston-azure-transport

A Windows Azure blob storage transport for winston. This is intended to replicate the "log to blob container functionality" found in Azure for node or iisnode applications, including log rollover and expiry in an easy to configure manner.

This borrows heavily from an original coffeescript version by Parsimotion, however it only requires a container SAS and works with winston 3.

Credit

NOTE: This is a fork of https://github.com/blushingpenguin/winston-azure-transport, 99.99% of the code in this repository was written by user blushingpenguin on github. This fork simply fixes an intialization error I encountered while trying to use the library and adds an extra optional config parameter onAzureStorageErrorCallback, which is meant to be a callback that will receive and handle Azure Storage errors(See the General usage section below for usage example).

Installation

  $ npm install winston
  $ npm install mozenge-winston-azure-transport

Usage from iisnode

If node is being hosted in an Azure Windows app service (using iisnode), then configuration can be made largely automatic by using the Azure provided app settings. Firstly, to enable logging to storage from the Azure portal, navigate to your app service and configure "Application Logging (Blob)" from the "Diagnostic Logs" tab. Then add code to enable logging to your node application:

import winston from "winston";
import { getAzureBlobTransport } from "winston-azure-transport";

const logger = winston.createLogger({
    transports: getAzureBlobTransport()
});
logger.log("info", "Hello, world!");

getAzureBlobTransport will return null if it doesn't detect any configuration for azure blob logging (either from the environment provided by iisnode or from appsettings passed to it). This can be handled with code like:

function createLogger() {
    // Configure a console logger for winston
    const transports : TransportStream[] = [
        new winston.transports.Console({
            level: "info"
        })
    ];
    // Add an azure transport if configured
    const transport = getAzureBlobTransport();
    if (transport) {
        transports.push(transport);
    }
    // Create a winston logger
    const logger = winston.createLogger({
        transports
    });
    return logger;
}

You can also easily combine this with express using express-winston:

import express from "express";
import expressWinston from "express-winston";
import winston from "winston";
import { AzureBlobTransport, IAzureBlobTransportOptions } from "mozenge-winston-azure-transport";

const app = express();

const logger = createLogger();

// Add express middleware
app.use(expressWinston.logger({
    winstonInstance,
    meta: true,
    expressFormat: true
}));

// Add more middleware
app.use(express.static("public"));
...
// etc

// Add an express error logger
app.use(expressWinston.errorLogger({
    winstonInstance
}));

This easily adds full logging to azure blob storage for actions and errors to iisnode applications.

General usage

For general usage AzureBlobTransport can be directly created with options passed to the constructor as in the example below.

import winston from "winston";
import { AzureBlobTransport } from "mozenge-winston-azure-transport";

const logger = winston.createLogger({
    transports: [
        new AzureBlobTransport({
            containerUrl: "https://mystorage.blob.core.windows.net/errors?sv=2018-03-28&sr=c&sig=x&st=2019-01-01T00:00:00Z&se=2219-01-01T00:00:00Z&sp=rwdl",
            nameFormat: "my-app-logs/{yyyy}/{MM}/{dd}/{hh}/node.log",
            retention: 365,
            onAzureStorageError: (error, block) => { // this is optional
                console.log('RECEIVED ERROR object');
                console.log(error);
                if (block) {
                    console.log('received block string as well');
                    console.log(block);
                }
            },
        })
    ]
});
logger.log("info", "Hello, world!");

AzureBlobTransport accepts the following options:

containerUrl

The container url can be obtained from the Azure portal by navigating to your app service, configuring "Application Logging (Blob)" from the "Diagnostics Logs" tab, then viewing the "DIAGNOSTICS_AZUREBLOBCONTAINERSASURL" application setting on the "Application Settings" tab.

Alternatively you can use Azure Storage Explorer to generate the URL by choosing "Get Shared Access Signature" from the context menu of the storage container you wish to log to.

name

The name of the logger within winston (defaults to AzureBlobTransport).

nameFormat

The name format can be omitted and defaults to "{yyyy}/{MM}/{dd}/{hh}/node.log".

retention

The number of days to keep logs for. Log dates will be parsed according to the nameFormat option, and any logs older than the specified number of days will be deleted once per day.

trace

Setting trace: true in the options will enable debug messages from the logger. These go to the console.

onAzureStorageError

This is not a required option. A function to receive and handle azure Storage Error's. If set this function will be called with two arguments error and block. The block might be a string(log messages) or undefined depending on if its passed or not. A sample error object looks like the following

{
  "name": "StorageError",
  "message": "Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.\nRequestId:0c5ea7a2e-601e-0150-5624-5dbfee000000\nTime:2018-08-27T22:09:37.8862339Z",
  "code": "AuthenticationFailed",
  "authenticationerrordetail": "Signature fields not well formed.",
  "statusCode": 403,
  "requestId": "0c5f4a2e-601e-0150-5624-5dbfee000000"
}

getAzureBlobSettings

function getAzureBlobSettings(
    config?: Partial<IAzureBlobTransportOptions>,
    appSettings?: IAzureBlobTransportAppSettings
):  AzureBlobTransport | null;

This function detects settings from the node environment within in an azure app service. The environment variables DIAGNOSTICS_AZUREBLOBCONTAINERSASURL, DIAGNOSTICS_AZUREBLOBRETENTIONINDAYS are used for the containerUrl and retention settings respectively. The environment variable WEBSITE_SITE_NAME is used to provide a prefix to the nameFormat settings (in azure storage explorer, this appears as a folder with the same name as the website).

If the environment variables are not found then configuration is taken from appSettings (described below), if provided. If neither method provides an SAS storage url then the function returns null.

The config argument allows passing on any additional options to the AzureBlobTransport constructor. The appSettings argument allows passing a json configuration file on as follows:

const appSettings = require("appsettings.json");
const transport = getAzureBlobSettings({}, appSettings);

With appsettings.json being something like:

{
    "azureBlobContainerSasUrl": "https://mystorage.blob.core.windows.net/errors?sv=2018-03-28&sr=c&sig=x&st=2019-01-01T00:00:00Z&se=2219-01-01T00:00:00Z&sp=rwdl",
    "azureBlobContainerSasFormat": "my-folder/{yyyy}/{MM}/{dd}/{hh}/node.log",
    "azureBlobRetentionInDays": 365
}