@nbn23/gc-logger v3.0.0

Google Cloud Logger

gc-logger is a library for managing logs from software components (containers, functions and virtual machines) running in Google Cloud. Based on bunyan, it offers additional features as trace support and log labelling for better traceability.

Getting Started

Installation

Install gc-logger using npm.

npm install @nbn23/gc-logger

Note: gc-logger assumes a TypeScript environment

Usage

Basic usage

Create a Google Cloud logger and log to Stackdriver logs with priority higher or equal to info

import { GoogleCloudLogger, SEVERITY_INFO } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({ thresholdLevel: SEVERITY_INFO });

logger.debug("This log is NOT being published (severity debug is under default severity threshold)");
logger.info("This log is being published (severity info is equal to the default severity threshold)");
logger.warn("This log is being published (severity warn, ie, warning is above default severity threshold)");
logger.error("This log is being published (severity error is above default severity threshold)");

Logging to both Stackdriver and console

Create a Google Cloud logger and log to Stackdriver logs with priority higher or equal to info, and send to the console logs with priority higher or equal to debug

import { GoogleCloudLogger, SEVERITY_INFO, SEVERITY_DEBUG } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    consoleThresholdLevel: SEVERITY_DEBUG
});

logger.debug("This log is being published only in the console (severity debug is equal to the default severity threshold)");
logger.info("This log is being published in Stackdriver and the console");

Logging a JSON payload

Create a Google Cloud logger and log to Stackdriver logs a message plus a JSON payload

import { GoogleCloudLogger, SEVERITY_INFO } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO
});

logger.info(
    "This log is being published in Stackdriver with an extra 'jsonPayload' field containing JSON data", 
    { 
        myStringProperty: "This is the first property of the JSON data being logged", 
        myNumericProperty: 1,
        myBooleanProperty: true,
        myObjectProperty: {
            foo: "bar"
        }
    }
);

Log labels

Use a default list of labels that will be associated to all the logs

import { GoogleCloudLogger, SEVERITY_INFO, SEVERITY_DEBUG } from "@nbn23/gc-logger;

const myLabels = { transactionId = "MyTransactionId", foo = "bar"};
const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    consoleThresholdLevel: SEVERITY_DEBUG,
    labels: myLabels
});

logger.info("This log is being published in Stackdriver and the labels will be set in the log property labels");

Use a default list of labels that will be associated to all the logs, but log some info overriding them

import { GoogleCloudLogger, SEVERITY_INFO, SEVERITY_DEBUG } from "@nbn23/gc-logger;

const myLabels = {
    transactionId : "MyTransactionId",
    foo : "bar"
};
const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    consoleThresholdLevel: SEVERITY_DEBUG,
    labels: myLabels
});

logger.info("This log is being published in Stackdriver with specific entry labels", undefined, { myCustomLabel: "myCustomLabelValue" });

Use a default list of labels that will be associated to all the logs, but log some info expanding them

import { GoogleCloudLogger, SEVERITY_INFO, SEVERITY_DEBUG } from "@nbn23/gc-logger;

const myLabels = {
    transactionId: "MyTransactionId",
    foo: "bar"
};
const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    consoleThresholdLevel: SEVERITY_DEBUG,
    labels: myLabels
});

const myCustomLabels = {
    customLabel : "myCustomLabelValue"
};
logger.info("This log is being published in Stackdriver with specific entry labels", undefined, { ...logger.getLabels(), ... myCustomLabels});

Log traces

Use a custom Strackdriver Trace trace id

At object instance level:

import { GoogleCloudLogger, SEVERITY_INFO } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    customTraceKey: "ThisIsMyCustomTraceKey"
});

logger.info("This log is being published with traceId set to 'ThisIsMyCustomTraceKey'");

At log level:

import { GoogleCloudLogger, SEVERITY_INFO } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO
});

logger.info("This log is being published with traceId set to 'ThisIsMyCustomTraceKey'", undefined, undefined, "ThisIsMyCustomTraceKey");

Using both, with log level trace id taking precedence over object instance level trace id:

import { GoogleCloudLogger, SEVERITY_INFO } from "@nbn23/gc-logger;

const logger = new GoogleCloudLogger({
    thresholdLevel: SEVERITY_INFO,
    customTraceKey: "ThisIsMyDEFAULTCustomTraceKey"
});

logger.info("This log is being published with traceId set to 'ThisIsMyDEFAULTCustomTraceKey'...");
logger.info("...whereas this is being published with traceId set to 'ThisIsMyCustomTraceKey'", undefined, undefined, "ThisIsMyCustomTraceKey");