README.md

Cloud Pine

Pino Transport that abstracts Google Cloud Logging implementation underneath.

Description

This library executes a thin abstraction of the @google-cloud/logging client library. The goal is to provide a clean support over Google Cloud Logging service for the Pino ecosystem using the Transport feature of Pino itself.

Usage

How to use it?

The library can be used either by piping logs using the pipe operator on Linux, or programatically by installing it as part of your dependencies in you project.

Within your Dependencies

Using it programatically, is easy as just install the library as part for your dependencies in any of the following ways:

• npm: npm install cloud-pine

• yarn: yarn add cloud-pine

• pnpm: pnpm install cloud-pine

Once installed, is necessary to set it up as part of of your Pino transport configuration, an example can be:

const Pino = require('pino')
const logger = Pino({
   transport: {
      target: 'cloud-pine',
      options: {
         cloudLoggingOptions: {
            skipInit: true,
            sync: true,
         }
      }
   }
})


logger.info('hello world')
logger.error({ oops: 'hello!' }, 'error')

or in TypeScript

import Pino from ('pino')

const logger = Pino({
   transport: {
      target: 'cloud-pine',
      options: {
         cloudLoggingOptions: {
            skipInit: true,
            sync: true,
         }
      }
   }
})


logger.info('hello world')
logger.error({ oops: 'hello!' }, 'error')

NOTE: The projectId string and resource object on the Logging instance are detected and set automatically 🎉

Configuration Cloud-Pine supports the following configuration:

const cloudPine = {
    logName: 'cloud-pine', // Name of the logging agent. Default to 'cloud-pine'
    cloudLoggingOptions: {
        googleCloudOptions: {}, // Configuration Object for establishing connection with Google Cloud Logging. Default to undefined. Ref: https://cloud.google.com/nodejs/docs/reference/logging/latest/logging/loggingoptions

        resourceSettings: {}, // Resource settings hash, default to `{ type: 'global' }`. The hash is persisted across logs and inferred based on the API `Logging#setDetectedResource` result. Ref: https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource

        defaultLabels: {}, // Labels hash, default to `{ logger: 'pino', agent: 'cloud_pine' }`. The hash is persisted across logs. Ref: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry,

        logOptions: {}, // Configuration object that is passed to the Log/LogSync instance. Default to undefined. Ref: https://cloud.google.com/nodejs/docs/reference/logging/latest/logging/log and https://cloud.google.com/nodejs/docs/reference/logging/latest/logging/logsync

        skipInit: false, // Indicates wheter to skip the automatic inferr of `projectId` and `MonitoredResource` metadata. Default to `false`.

        sync: false, // Indicates wheter to use a Log or LogSync instance. Default to false.
    }
}

For more information about the sync and async diference, please take a look at the section Sync or Async

CLI

When using it in CLI mode, all the logs are ingested automatically from stdin. In case exists some malformed log, the library will automatically dispatch an log with severity to error to Google Cloud Logging.

Usage

See the following description for usage:

Usage: cat log | cloud-pine --projectid someprojectid -l something=else -l service=http

  Flags
  -h  | --help              Display Help

  -v  | --version           Display Version

  -n  | --name              Log Name. Default to Cloud_Pine

  -s  | --sync              Cloud Logging Mode. Sync will print to `stdout`
                            meanwhile async will forward logs to Cloud Logging.
                            Default to true.

  -p  | --projectid         Google Cloud Project ID. Default to automatic
                            detected resource or
                            `GOOGLE_APPLICATION_CREDENTIALS`

  -k  | --key               Path to key file

  -l  | --labels            Custom labels to be attached to the logging labels.
                            Should be in the format `label=value`.
                            Can be used one or more times.

  -r  | --resource          Monitoring Resource type. Default to `type=global`
                            or Monitored Resource detected.

  -rs  | --resource-labels   Monitoring Resource#Labels that will be attached
                            to the resource by default.
                            Follows same pattern as `--labels`.

  -i  | --skip-init         Skips identification of monitored resource, which
                            will infer things like `project-id` and Monitored
                            Resource settings. Default to false.

TypeScript Interface

type CloudPineOptions = {
  logName?: string;
  cloudLoggingOptions: {
    googleCloudOptions?: LoggingOptions;
    resourceSettings?: {
      type?: string;
      labels: Record<string, string>;
    };
    defaultLabels?: Record<string, string>;
    skipInit?: boolean;
    sync?: boolean;
    logOptions?: ConstructorParameters<typeof Log> | ConstructorParameters<typeof LogSync>;
  };

Sync or Async

The library can be used in either of two modes, sync or async.

The default mode for the CLI usage is sync meaning that all logs will be directly streamed to stdout, meanwhile the default mode for the Transport usage is async, where all the logs will be streamed directly to Google Cloud Logging service.

For more information about when to use one or another please take a look at the following documentation: Writting to stdout.