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

$3

Install gc-logger using npm.

``sh
npm install @nbn23/gc-logger
`

> Note: gc-logger assumes a TypeScript environment

$3

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

`ts
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

`ts
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

`ts
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

`ts
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

`ts
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

`ts
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:

`ts
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:

`ts
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:

`ts
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");
``