pino-gcp-transport

Convert pino stdout logging to structured json suitable for google cloud logging.

• Google Cloud Logging
• Trace context

Api

Exported as ESM and commonjs.

• compose() Compose transport to get google structured log
• middleware() Express middleware to collect tracing
• fastifyHook() Fastify hook to collect tracing
• getTraceHeadersAsObject() Get collected tracing headers as object to forward to downstream calls
• logger.js Logger example
• SpanContext
• Examples Middleware and logging examples

compose([options[, Transformation = StructuredTransformation]])

Compose transport to get structured log. Default and named export.

Arguments:

• options: optional structured transport options
  • ignoreKeys: optional list of pino ignore keys, filters what log line keys are sent to jsonPayload, defaults to ['hostname', 'pid', 'level', 'time', 'msg']
  • destination: optional integer or string, integer 1 = stdout which is default, if a string is used the destination will be considered a log file, e.g. ./logs/test.log
  • append: optional boolean, set to false if you want file test logging to be reset between test runs, passed to sonic-boom
  • [key]: any other options that can be passed to sonic-boom
• Transformation: optional transformation stream type, defaults to builtin StructuredTransformation stream type, will be called with new. Can be used to override with extended StructuredTransformation type

1import pino from 'pino';
2import compose, { getLogTrace } from '@aller/pino-gcp-transport';
3
4export const logger = pino(
5  {
6    mixin() {
7      return { ...getLogTrace(process.env.MYAPP_projectId) };
8    },
9  },
10  compose({
11    ignoreKeys: ['message', 'hostname', 'pid', 'level', 'time', 'msg'],
12  })
13);

middleware()

Function to create express middleware that collects Opentelemetry headers if any.

1import express from 'express';
2import { middleware } from '@aller/pino-gcp-transport';
3
4const app = express();
5
6app.use(middleware());

fastifyHook()

Function to create fastify hook that collects Opentelemetry headers if any.

1import fastify from 'fastify';
2import { fastifyHook } from '@aller/pino-gcp-transport';
3
4const app = fastify();
5
6app.addHook('onRequest', fastifyHook());

getLogTrace(projectId)

Used in mixin to get trace context logging params. Named export.

Arguments:

• projectId: required string google project id

Returns

Object with structured log keys logging.googleapis.com/trace and logging.googleapis.com/spanId.

1import { getLogTrace } from '@aller/pino-gcp-transport';
2import pino from 'pino';
3
4export const logger = pino({
5  mixin() {
6    return { ...getLogTrace(process.env.MYAPP_projectId) };
7  },
8});

getTraceHeaders([flags = 0])

Used to forward tracing to donwstream calls. Named export.

Arguments:

• flags: optional positive integer, below 256, tracing flag, 0 = not sampled, 1 = sampled

Returns

Map with trace headers traceparent and legacy x-cloud-trace-context.

1import pino from 'pino';
2import compose, { getTraceHeaders, getLogTrace } from '@aller/pino-gcp-transport';
3
4export const logger = pino(
5  {
6    mixin() {
7      return { ...getLogTrace(process.env.MYAPP_projectId) };
8    },
9  },
10  compose()
11);
12
13await fetch('http://localhost:11434/get', {
14  headers: Object.fromEntries(getTraceHeaders()),
15}).catch((err) => {
16  logger.error(err);
17});

getTraceHeadersAsObject([flags = 0])

Same as getTraceHeaders but returns object.

Setup example

Express middleware

1import pino from 'pino';
2import express from 'express';
3import request from 'supertest';
4
5import compose, { middleware, getLogTrace, getTraceHeadersAsObject } from '@aller/pino-gcp-transport';
6
7const logger = pino(
8  {
9    level: 'trace',
10    mixin() {
11      return { ...getLogTrace('aller-project-1') };
12    },
13  },
14  compose()
15);
16
17const app = express();
18
19app.use(middleware());
20
21app.get('/downstream', async (req, res, next) => {
22  try {
23    logger.debug('foo');
24    // pass your tracing headers to a downstream service
25    await request('https://example.com')
26      .get('/')
27      .set(getTraceHeadersAsObject(req.query.flags ? Number(req.query.flags) : undefined));
28    res.send({});
29  } catch (err) {
30    next(err);
31  }
32});
33
34app.use('/log/request', (req, res) => {
35  logger.info(req);
36  res.send({});
37});
38
39app.get('/log/error', (req, res) => {
40  logger.error(new Error(req.query.message ?? 'expected'));
41  res.send({});
42});
43
44app.use((err, _req, res, next) => {
45  if (!(err instanceof Error)) return next();
46
47  logger.error(err);
48  res.status(500).send({ message: err.message });
49});
50
51// For testing
52await request(app).get('/log/request').expect(200);

Fastify hook

1import pino from 'pino';
2import fastify from 'fastify';
3
4import compose, { fastifyHook, getLogTrace, getTraceHeadersAsObject } from '@aller/pino-gcp-transport';
5
6const logOptions = {
7  level: 'trace',
8  mixin() {
9    return { ...getLogTrace('aller-project-1') };
10  },
11};
12
13const logger = pino(logOptions, compose());
14
15const app = fastify({
16  logger: logOptions,
17  logInstance: logger,
18});
19
20app.addHook('onRequest', fastifyHook());
21
22app.get('/', (request, reply) => {
23  request.log.info('hello world');
24  reply.send({ hello: 'world' });
25});
26
27app.get('/downstream', async (request, reply) => {
28  logger.debug('foo');
29  const res = await fetch('https://example.com', {
30    method: 'GET',
31    headers: {
32      ...getTraceHeadersAsObject(request.query.flags ? Number(request.query.flags) : undefined),
33    },
34  });
35
36  logger.info({ ok: res.ok }, 'bar');
37
38  reply.send({});
39});
40
41app.get('/log/request', (request, reply) => {
42  logger.info(request, 'foo');
43  reply.send({});
44});
45
46app.get('/log/error', (request, reply) => {
47  logger.error(new Error(request.query.message ?? 'expected'));
48  reply.send({});
49});
50
51// For testing
52await app.inject().get('/log/request');

Logger example

1import config from 'exp-config';
2import { pino } from 'pino';
3
4import { getLogTrace } from '@aller/pino-gcp-transport';
5
6const destination = config.logging?.target === 'file' ? `./logs/${config.envName}.log` : 1;
7
8const targets = [];
9if (config.logging.prettify) {
10  targets.push({
11    target: 'pino-pretty',
12    options: {
13      colorize: true,
14      ignore: 'pid,hostname',
15      translateTime: "yyyy-mm-dd'T'HH:MM:ss.l",
16      destination,
17      append: false,
18    },
19  });
20} else {
21  targets.push({
22    target: '@aller/pino-gcp-transport',
23    options: {
24      destination,
25      append: false,
26    },
27  });
28}
29
30const transport = pino.transport({ targets });
31
32export default pino(
33  {
34    level: config.logging?.level || 'debug',
35    mixin() {
36      return { ...getLogTrace(config.projectId) };
37    },
38  },
39  transport
40);

Span Context

Execute in an existing tracing context.

1import pino from 'pino';
2import compose, { SpanContext, getTraceHeadersAsObject, getLogTrace } from '@aller/pino-gcp-transport';
3
4const logger = pino(
5  {
6    level: 'trace',
7    mixin() {
8      return { ...getLogTrace('aller-project-1') };
9    },
10  },
11  compose()
12);
13
14await new SpanContext('b657b24860f0a4390698ba907685c88d', 'e29221ca9e364975', 0).runInNewSpanContext(function track(foo) {
15  return new Promise((resolve) => {
16    logger.info(getTraceHeadersAsObject(), 'called with argument %s', foo);
17    resolve();
18  });
19}, 'bar');

Execute in a new tracing context.

1import { SpanContext, getTraceHeadersAsObject } from '@aller/pino-gcp-transport';
2
3await new SpanContext().runInNewSpanContext(function track(foo) {
4  return new Promise((resolve) => {
5    console.log(foo, getTraceHeadersAsObject());
6    resolve();
7  });
8}, 'baz');

The projectId

To be able to log trace the google project id needs to be passed to the mixin function getLogTrace(projectId). Undefined is returned if called without project id.

The project id is used to format the log parameter logging.googleapis.com/trace formatted as projects/${projectId.trim()}/traces/${traceId}

If deploying with terraform you can pick the id from your project resource, e.g:

1locals {
2  env_pfx = "MYAPP_"
3}
4
5resource "google_cloud_run_v2_service" "myapp" {
6  template {
7    containers {
8      image = "gcr.io/cloudrun/hello"
9
10      ports {
11        container_port = 3000
12      }
13
14      env {
15        name  = "NODE_ENV"
16        value = var.environment
17      }
18      env {
19        name  = "ENV_PREFIX"
20        value = local.env_pfx
21      }
22      env {
23        name  = "INTERPRET_CHAR_AS_DOT"
24        value = "_"
25      }
26
27      # The google project eventually picked up by exp-config as config.projectId, or just use as process.env.MYAPP_projectId
28      env {
29        name  = "${local.env_pfx}projectId"
30        value = google_project.default.project_id
31      }