pino-logflare

pino-logflare

A transport for Pino that sends messages to Logflare.

Features

• Supports all Pino log levels
• Automatic batching of logs
• Custom payload transformation
• Vercel Edge Runtime support
• Error handling
• TypeScript support

[!NOTE]
pino-logflare v0.5.0 and above is Pino +v7 compatible and remains backwards compatible.

Installation

npm install pino pino-logflare

Usage

Pino +v7 compatible transport.

const pino = require("pino")
const transport = pino.transport({
  target: "pino-logflare",
  options: {
    apiKey: "your-api-key",
    sourceToken: "your-source-token",
  },
})
const logger = pino(transport)

logger.info("Hello Logflare!")

Package Functions

The default import should be used for all pino +v7 transport usage.

createWriteStream (deprecated)

The createWriteStream function creates a writestream. This is deprecated in favour of the default import of the package which is pino +v7 compatible.

Example usage of contentWriteStream

Example:

const writeStream = createWriteStream({
  apiKey: "API_KEY",
  sourceToken: "49e4f31e-f7e9-4f42-8c1e-xxxxxxxxxx",
})

To handle ingestion errors, add in the following option:

const writeStream = createWriteStream({
  apiKey: "API_KEY",
  sourceToken: "49e4f31e-f7e9-4f42-8c1e-xxxxxxxxxx"
  // optional callback, callback be invoked on each error raised
  onError: (payload, err)=> {
    // do something with the ingestion payload that would have been sent to Logflare.
  }
});

To customize the payload, use the the onPreparePayload option:

import { defaultPreparePayload } from "pino-logflare"

const writeStream = createWriteStream({
  ...,
  // optional callback, by default, the received object will be nested under the `metadata` key
  onPreparePayload: (payload, meta)=> {
    // the `meta` arg contains cleaned information of raw payload
    // You can add in top-level keys via this callback, or completely disable `metadata` key nesting by passing the payload as is, as shown below.
    const item = defaultPreparePayload(payload, meta)
    item["my_custom_key"] = "some value'
    return item
  }
});

createPinoBrowserSend

The createPinoBrowserSend function creates a writestream to send log events from the browser.

Example:

const send = createPinoBrowserSend({
  apiKey: "API_KEY",
  sourceToken: "49e4f31e-f7e9-4f42-8c1e-xxxxxxxxxx",
})

Library Configuration Options

Option	Type	Description
apiKey	Required, string	Your Logflare API key
sourceToken	Required, string	Your Logflare source token
apiBaseUrl	Optional, string	Custom API endpoint (defaults to Logflare's API)
size	Optional, number	Number of logs to batch before sending (defaults to 1)
onPreparePayload	Optional, callback	Function to transform log payloads before sending
onError	Optional, Object	Object with a module and method to be invoked on the worker thread.errors
batchSize	Optional, number	Number of logs to batch before sending (defaults to 100)
batchTimeout	Optional, number	Time in milliseconds to wait before sending partial batch (defaults to 1000)

Note: batchSize and batchTimeout options are available only for Pino +v7.

⚠️ Deprecated Options

The following options are deprecated and will be removed in a future version:

Option	Status	Migration
transforms	Deprecated	Server-side transforms are no longer supported.
endpoint	Deprecated	Use apiBaseUrl instead
fromBrowser	Deprecated	This option is no longer necessary for the HTTP Client.

CLI

# install pino-logflare globally
$ npm install -g pino-logflare

# pipe text to be logged
$ echo "this is a test" | pino-logflare --key YOUR_KEY --source YOUR_SOURCE_ID

# with custom API URL
$ echo "this is a test" | pino-logflare --key YOUR_KEY --source YOUR_SOURCE_ID --url https://custom.logflare.app

Example with node script

Given an application index.js that logs via pino, you would use pino-logflare like so:

// index.js
const logger = require("pino")()

logger.info("hello world")

const child = logger.child({ property: "value" })
child.info("hello child!")

$ node index.js | pino-logflare --key YOUR_KEY --source YOUR_SOURCE_ID

CLI Options

You can pass the following options via cli arguments or use the environment variable associated:

Short command	Full command	Environment variable	Description
-k	--key <apikey>	LOGFLARE_API_KEY	The API key that can be found in your Logflare account
-s	--source <source>	LOGFLARE_SOURCE_TOKEN	Default source for the logs
-u	--url <url>	LOGFLARE_URL	Custom Logflare API URL (optional)

Vercel

To use pino-logflare in your Vercel project you have to configure:

• Logflare Vercel integration that will handle serverless functions log events
• Pino browser send function to handle log events from the browser client

Example:

import pino from "pino"
import { logflarePinoVercel } from "pino-logflare"

// create pino-logflare console stream for serverless functions and send function for browser logs
const { stream, send } = logflarePinoVercel({
  apiKey: "YOUR_KEY",
  sourceToken: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
})

// create pino logger
const logger = pino(
  {
    browser: {
      transmit: {
        level: "info",
        send: send,
      },
    },
    level: "debug",
    base: {
      env: process.env.VERCEL_ENV,
      revision: process.env.VERCEL_GITHUB_COMMIT_SHA,
    },
  },
  stream,
)

Development

Setup

npm i
npm run build
npm test
npm run test.watch

# e2e tests
npm run start:api
npm run test:e2e

License

MIT