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

``bash
npm install pino pino-logflare
`

Usage

Pino +v7 compatible transport.

`javascript
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.

$3

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:

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

To handle ingestion errors, add in the following option:

`js
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:

`js
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
}
});
`

$3

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

Example:

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

$3

| 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.

$3

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

`bash


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
`

$3

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

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

logger.info("hello world")

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

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

$3

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:

`js
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

$3

`bash
npm i
npm run build
npm test
npm run test.watch

e2e tests


npm run start:api
npm run test:e2e
``

License

MIT

[pino]: https://www.npmjs.com/package/pino
[logflare]: https://logflare.app/