@getcircuit/server-logging

@getcircuit/server-logging

Logging

This is a logging library to be used by Circuit Backend Services.

In its essence it is a wrapper for some other logging library with a common logging interface, so we can easily change how it works without having to update the same code in all services.

Currently, we are using Pino as our logging library of choice.

Usage

This example will use an approach of having a singleton logger instance for a whole service, but this library does not enforce a single logger instance, if needed you can spawn other instances.

To use this library we need to first initialize a logger.

// logger.ts

import { createLogger } from '@getcircuit/server-logging'

export const logger = createLogger({
  level: 'info',
  pretty: true,
  enabled: true,
})

And then we can use it anywhere:

We can log a simple message

logger.info('Starting server')

Or we can log a message with extra details

logger.info('Starting server', { address: '127.0.0.1:8080' })

Or even, if we get an error, we can use the special 'error' key to automatically spread all the error properties

try {
  // try starting the server
} catch (error) {
  logger.error('Error starting server', {
    error,
    /* ...otherProperties */
  })
}

[!NOTE] This is necessary as errors in JavaScript are objects with non-enumerable properties and so JSON.stringify does not stringify the error properly if not explicitly telling it which keys to use.

Tracing

This library includes a tracing instrumentation for the logger in order to be provided to the @getcircuit/server-tracing library.

Remember that as opentelemetry instrumentations work by intercepting imports and changing them, the tracing needs to be set-up before ever importing the logging library itself.

That is why the tracing is provided in a separate export path: @getcircuit/server-logging/tracing

An example of how to use it with @getcircuit/server-tracing:

import { setupTracing } from '@getcircuit/server-tracing'
import { getLoggerTracingInstrumentation } from '@getcircuit/server-logging/tracing'

import { tracingOptionsBase } from '@Config/tracing'

setupTracing({
  ...tracingOptionsBase,
  extraInstrumentationOptions: [getLoggerTracingInstrumentation()],
})

TypeORM

This library also includes a TypeORM logger that can be used to log the queries that are being executed by TypeORM.

All queries are logged with the debug level, slow queries with the warn level, and errors with the error level.

To use it, you need to pass the logger to the createTypeORMLogger function when setting up the TypeORM connection:

import { DataSource } from 'typeorm'
import { createTypeORMLogger } from '@getcircuit/server-logging/typeorm'

import { postgres } from '$/config'
import { logger } from '$/logger'

export const sqlDataSource = new DataSource({
  type: 'postgres',
  host: postgres.host,
  port: postgres.port,
  username: postgres.username,
  password: postgres.password,
  database: postgres.database,
  entities: [
    // ...
  ],
  synchronize: false,
  logger: createTypeORMLogger(logger),
})