Google Cloud Logging Transport for LogLayer

Implements the Google Cloud Logging library for use with the LogLayer logging library.

This transport sends logs to Google Cloud Logging (formerly known as Stackdriver Logging).

Installation

npm install @loglayer/transport-google-cloud-logging @google-cloud/logging serialize-error

Notes

This transport uses log.entry(metadata, data) as described in the library documentation.

• The metadata portion is not the data from withMetadata() or withContext(). See the rootLevelData and rootLevelMetadataFields options for this transport on how to modify this value.
• The data portion is actually the jsonPayload is what the transport uses for all LogLayer data.
• The message data is stored in jsonPayload.message

For more information, see Structured Logging, specifically LogEntry.

Usage

import { LogLayer } from "loglayer";
import { GoogleCloudLoggingTransport } from "@loglayer/transport-google-cloud-logging";
import { Logging } from '@google-cloud/logging';
import { serializeError } from "serialize-error";

// Create the logging client
const logging = new Logging({ projectId: "GOOGLE_CLOUD_PLATFORM_PROJECT_ID" });
const log = logging.log('my-log');

// Create LogLayer instance with the transport
const logger = new LogLayer({
  errorSerializer: serializeError,
  transport: new GoogleCloudLoggingTransport({
    logger: log,
  })
});

// The logs will include the default metadata
logger.info("Hello from Cloud Run!");

Configuration Options

rootLevelData

The root level metadata to include for all log entries. This value is merged with metadata provided using withContext().

The rootLevelData option accepts any valid Google Cloud LogEntry fields except for severity, timestamp, and jsonPayload which are managed by the transport.

const logger = new LogLayer({
  transport: new GoogleCloudLoggingTransport({
    logger: log,
    rootLevelData: {
      resource: {
        type: "cloud_run_revision",
        labels: {
          project_id: "my-project",
          service_name: "my-service",
          revision_name: "my-revision",
        },
      },
      labels: {
        environment: "production",
        version: "1.0.0",
      },
    },
  }),
});

rootLevelMetadataFields

By default, withMetadata() fields are forwarded as part of jsonPayload of the LogEntry.

The rootLevelMetadataFields option accepts an array of field names to pluck from metadata and shallow merge with rootLevelData. This allows you to dynamically specify the metadata portion of a log entry.

const logger = new LogLayer({
  transport: new GoogleCloudLoggingTransport({
    logger: log,
    rootLevelMetadataFields: ["labels"],
    rootLevelData: {
      labels: {
        environment: "production",
        location: "west",
      },
    },
  }),
});

// This will overwrite `labels` in root level data.
// `customField` is still sent as part of `jsonPayload`.
logger
  .withMetadata({ labels: { location: "east" }, customField: "example" })
  .info("example")

To allow mapping to every supported LogEntry metadata field, the following list is recommended:

const logger = new LogLayer({
  transport: new GoogleCloudLoggingTransport({
    logger: log,
    rootLevelMetadataFields: [
      "logName",
      "resource",
      "insertId",
      "httpRequest",
      "labels",
      "operation",
      "trace",
      "spanId",
      "traceSampled",
      "sourceLocation",
      "split",
    ],
  }),
});

Log Level Mapping

LogLayer log levels are mapped to Google Cloud Logging severity levels as follows:

Documentation

For more details, visit https://loglayer.dev/transports/google-cloud-logging