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.

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