From f220965c3e3885b8479c37ec880e43315e1a2373 Mon Sep 17 00:00:00 2001 From: shunto <34291913+superherobtf1985@users.noreply.github.com> Date: Mon, 14 Oct 2024 02:36:28 +0900 Subject: [PATCH] docs -> #2061 Alphabetize transport list and reorder sections in documentation (#2062) --- docs/transports.md | 660 ++++++++++++++++++++++----------------------- 1 file changed, 329 insertions(+), 331 deletions(-) diff --git a/docs/transports.md b/docs/transports.md index 83d052030..7e0295476 100644 --- a/docs/transports.md +++ b/docs/transports.md @@ -410,24 +410,24 @@ PRs to this document are welcome for any new transports! ### Pino v7+ Compatible ++ [@axiomhq/pino](#@axiomhq/pino) + [@logtail/pino](#@logtail/pino) -+ [pino-elasticsearch](#pino-elasticsearch) -+ [pino-pretty](#pino-pretty) -+ [pino-loki](#pino-loki) -+ [pino-seq-transport](#pino-seq-transport) -+ [pino-sentry-transport](#pino-sentry-transport) ++ [@macfja/pino-fingers-crossed](#macfja-pino-fingers-crossed) + [pino-airbrake-transport](#pino-airbrake-transport) -+ [pino-datadog-transport](#pino-datadog-transport) -+ [pino-slack-webhook](#pino-slack-webhook) + [pino-axiom](#pino-axiom) -+ [pino-opentelemetry-transport](#pino-opentelemetry-transport) -+ [@axiomhq/pino](#@axiomhq/pino) ++ [pino-datadog-transport](#pino-datadog-transport) + [pino-discord-webhook](#pino-discord-webhook) ++ [pino-elasticsearch](#pino-elasticsearch) ++ [pino-hana](#pino-hana) + [pino-logfmt](#pino-logfmt) ++ [pino-loki](#pino-loki) ++ [pino-opentelemetry-transport](#pino-opentelemetry-transport) ++ [pino-pretty](#pino-pretty) ++ [pino-seq-transport](#pino-seq-transport) ++ [pino-sentry-transport](#pino-sentry-transport) ++ [pino-slack-webhook](#pino-slack-webhook) + [pino-telegram-webhook](#pino-telegram-webhook) + [pino-yc-transport](#pino-yc-transport) -+ [@macfja/pino-fingers-crossed](#macfja-pino-fingers-crossed) -+ [pino-hana](#pino-hana) ### Legacy @@ -455,6 +455,34 @@ PRs to this document are welcome for any new transports! + [pino-websocket](#pino-websocket) + +### @axiomhq/pino + +[@axiomhq/pino](https://www.npmjs.com/package/@axiomhq/pino) is the official [Axiom](https://axiom.co/) transport for Pino, using [axiom-js](https://github.com/axiomhq/axiom-js). + +```javascript +import pino from 'pino'; + +const logger = pino( + { level: 'info' }, + pino.transport({ + target: '@axiomhq/pino', + options: { + dataset: process.env.AXIOM_DATASET, + token: process.env.AXIOM_TOKEN, + }, + }), +); +``` + +then you can use the logger as usual: + +```js +logger.info('Hello from pino!'); +``` + +For further examples, head over to the [examples](https://github.com/axiomhq/axiom-js/tree/main/examples/pino) directory. + ### @logtail/pino @@ -462,6 +490,56 @@ The [@logtail/pino](https://www.npmjs.com/package/@logtail/pino) NPM package is [Quick start guide ⇗](https://betterstack.com/docs/logs/javascript/pino) + +### @macfja/pino-fingers-crossed + +[@macfja/pino-fingers-crossed](https://github.com/MacFJA/js-pino-fingers-crossed) is a Pino v7+ transport that holds logs until a log level is reached, allowing to only have logs when it matters. + +```js +const pino = require('pino'); +const { default: fingersCrossed, enable } = require('@macfja/pino-fingers-crossed') + +const logger = pino(fingersCrossed()); + +logger.info('Will appear immedialty') +logger.error('Will appear immedialty') + +logger.setBindings({ [enable]: 50 }) +logger.info('Will NOT appear immedialty') +logger.info('Will NOT appear immedialty') +logger.error('Will appear immedialty as well as the 2 previous messages') // error log are level 50 +logger.info('Will NOT appear') +logger.info({ [enable]: false }, 'Will appear immedialty') +logger.info('Will NOT appear') +``` + + +### pino-airbrake-transport + +[pino-airbrake-transport][pino-airbrake-transport] is a Pino v7+ compatible transport to forward log events to [Airbrake][Airbrake] +from a dedicated worker: + +```js +const pino = require('pino') +const transport = pino.transport({ + target: 'pino-airbrake-transport', + options: { + airbrake: { + projectId: 1, + projectKey: "REPLACE_ME", + environment: "production", + // additional options for airbrake + performanceStats: false, + }, + }, + level: "error", // minimum log level that should be sent to airbrake +}) +pino(transport) +``` + +[pino-airbrake-transport]: https://github.com/enricodeleo/pino-airbrake-transport +[Airbrake]: https://airbrake.io/ + ### pino-applicationinsights The [pino-applicationinsights](https://www.npmjs.com/package/pino-applicationinsights) module is a transport that will forward logs to [Azure Application Insights](https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview). @@ -474,6 +552,24 @@ $ node foo | pino-applicationinsights --key blablabla For full documentation of command line switches read [README](https://github.com/ovhemert/pino-applicationinsights#readme) + +### pino-axiom + +[pino-axiom](https://www.npmjs.com/package/pino-axiom) is a transport that will forward logs to [Axiom](https://axiom.co). + +```javascript +const pino = require('pino') +const transport = pino.transport({ + target: 'pino-axiom', + options: { + orgId: 'YOUR-ORG-ID', + token: 'YOUR-TOKEN', + dataset: 'YOUR-DATASET', + }, +}) +pino(transport) +``` + ### pino-azuretable The [pino-azuretable](https://www.npmjs.com/package/pino-azuretable) module is a transport that will forward logs to the [Azure Table Storage](https://azure.microsoft.com/en-us/services/storage/tables/). @@ -522,6 +618,87 @@ $ node foo | pino-datadog --key blablabla For full documentation of command line switches read [README](https://github.com/ovhemert/pino-datadog#readme) + +### pino-datadog-transport + +[pino-datadog-transport][pino-datadog-transport] is a Pino v7+ compatible transport to forward log events to [Datadog][Datadog] +from a dedicated worker: + +```js +const pino = require('pino') +const transport = pino.transport({ + target: 'pino-datadog-transport', + options: { + ddClientConf: { + authMethods: { + apiKeyAuth: + } + }, + }, + level: "error", // minimum log level that should be sent to datadog +}) +pino(transport) +``` + +[pino-datadog-transport]: https://github.com/theogravity/pino-datadog-transport +[Datadog]: https://www.datadoghq.com/ + +#### Logstash + +The [pino-socket][pino-socket] module can also be used to upload logs to +[Logstash][logstash] via: + +``` +$ node app.js | pino-socket -a 127.0.0.1 -p 5000 -m tcp +``` + +Assuming logstash is running on the same host and configured as +follows: + +``` +input { + tcp { + port => 5000 + } +} + +filter { + json { + source => "message" + } +} + +output { + elasticsearch { + hosts => "127.0.0.1:9200" + } +} +``` + +See to learn +how to setup [Kibana][kibana]. + +For Docker users, see +https://github.com/deviantony/docker-elk to setup an ELK stack. + + +### pino-discord-webhook + +[pino-discord-webhook](https://github.com/fabulousgk/pino-discord-webhook) is a Pino v7+ compatible transport to forward log events to a [Discord](http://discord.com) webhook from a dedicated worker. + +```js +import pino from 'pino' + +const logger = pino({ + transport: { + target: 'pino-discord-webhook', + options: { + webhookUrl: 'https://discord.com/api/webhooks/xxxx/xxxx', + } + } +}) +``` + ### pino-elasticsearch @@ -572,6 +749,31 @@ $ node your-app.js | pino-gelf log [gelf]: https://docs.graylog.org/en/2.1/pages/gelf.html [graylog]: https://www.graylog.org/ + +### pino-hana +[pino-hana](https://github.com/HiImGiovi/pino-hana) is a Pino v7+ transport that save pino logs to a SAP HANA database. +```js +const pino = require('pino') +const logger = pino({ + transport: { + target: 'pino-hana', + options: { + connectionOptions: { + host: , + port: , + user: , + password: , + }, + schema: , + table: , + }, + }, +}) + +logger.info('hi') // this log will be saved into SAP HANA +``` +For more detailed information about its usage please check the official [documentation](https://github.com/HiImGiovi/pino-hana#readme). + ### pino-http-send @@ -611,33 +813,20 @@ Tags and other metadata can be included using the available command line options $ node index.js | pino-logflare --key YOUR_KEY --source YOUR_SOURCE ``` - -### pino-mq - -The `pino-mq` transport will take all messages received on `process.stdin` and send them over a message bus using JSON serialization. - -This is useful for: - -* moving backpressure from application to broker -* transforming messages pressure to another component - -``` -node app.js | pino-mq -u "amqp://guest:guest@localhost/" -q "pino-logs" -``` - -Alternatively, a configuration file can be used: + +### pino-logfmt -``` -node app.js | pino-mq -c pino-mq.json -``` +[pino-logfmt](https://github.com/botflux/pino-logfmt) is a Pino v7+ transport that formats logs into [logfmt](https://brandur.org/logfmt). This transport can output the formatted logs to stdout or file. -A base configuration file can be initialized with: +```js +import pino from 'pino' +const logger = pino({ + transport: { + target: 'pino-logfmt' + } +}) ``` -pino-mq -g -``` - -For full documentation of command line switches and configuration see [the `pino-mq` README](https://github.com/itavy/pino-mq#readme) ### pino-loki @@ -661,24 +850,33 @@ pino(transport) For full documentation and configuration, see the [README](https://github.com/Julien-R44/pino-loki). - -### pino-papertrail -pino-papertrail is a transport that will forward logs to the [papertrail](https://papertrailapp.com) log service through an UDPv4 socket. + +### pino-mq -Given an application `foo` that logs via pino, and a papertrail destination that collects logs on port UDP `12345` on address `bar.papertrailapp.com`, you would use `pino-papertrail` -like so: +The `pino-mq` transport will take all messages received on `process.stdin` and send them over a message bus using JSON serialization. + +This is useful for: + +* moving backpressure from application to broker +* transforming messages pressure to another component ``` -node yourapp.js | pino-papertrail --host bar.papertrailapp.com --port 12345 --appname foo +node app.js | pino-mq -u "amqp://guest:guest@localhost/" -q "pino-logs" ``` +Alternatively, a configuration file can be used: -for full documentation of command line switches read [README](https://github.com/ovhemert/pino-papertrail#readme) +``` +node app.js | pino-mq -c pino-mq.json +``` - -### pino-pg -[pino-pg](https://www.npmjs.com/package/pino-pg) stores logs into PostgreSQL. -Full documentation in the [README](https://github.com/Xstoudi/pino-pg). +A base configuration file can be initialized with: + +``` +pino-mq -g +``` + +For full documentation of command line switches and configuration see [the `pino-mq` README](https://github.com/itavy/pino-mq#readme) ### pino-mysql @@ -699,6 +897,48 @@ For full documentation and command line switches read the [README][pino-mysql]. [MariaDB]: https://mariadb.org/ [JSONDT]: https://dev.mysql.com/doc/refman/8.0/en/json.html + +### pino-opentelemetry-transport + +[pino-opentelemetry-transport](https://www.npmjs.com/package/pino-opentelemetry-transport) is a transport that will forward logs to an [OpenTelemetry log collector](https://opentelemetry.io/docs/collector/) using [OpenTelemetry JS instrumentation](https://opentelemetry.io/docs/instrumentation/js/). + +```javascript +const pino = require('pino') + +const transport = pino.transport({ + target: 'pino-opentelemetry-transport', + options: { + resourceAttributes: { + 'service.name': 'test-service', + 'service.version': '1.0.0' + } + } +}) + +pino(transport) +``` + +Documentation on running a minimal example is available in the [README](https://github.com/Vunovati/pino-opentelemetry-transport#minimalistic-example). + + +### pino-papertrail +pino-papertrail is a transport that will forward logs to the [papertrail](https://papertrailapp.com) log service through an UDPv4 socket. + +Given an application `foo` that logs via pino, and a papertrail destination that collects logs on port UDP `12345` on address `bar.papertrailapp.com`, you would use `pino-papertrail` +like so: + +``` +node yourapp.js | pino-papertrail --host bar.papertrailapp.com --port 12345 --appname foo +``` + + +for full documentation of command line switches read [README](https://github.com/ovhemert/pino-papertrail#readme) + + +### pino-pg +[pino-pg](https://www.npmjs.com/package/pino-pg) stores logs into PostgreSQL. +Full documentation in the [README](https://github.com/Xstoudi/pino-pg). + ### pino-redis @@ -725,6 +965,27 @@ For full documentation of command line switches see the [pino-sentry README](htt [pino-sentry]: https://www.npmjs.com/package/pino-sentry [Sentry]: https://sentry.io/ + +### pino-sentry-transport + +[pino-sentry-transport][pino-sentry-transport] is a Pino v7+ compatible transport to forward log events to [Sentry][Sentry] +from a dedicated worker: + +```js +const pino = require('pino') +const transport = pino.transport({ + target: 'pino-sentry-transport', + options: { + sentry: { + dsn: 'https://******@sentry.io/12345', + } + } +}) +pino(transport) +``` + +[pino-sentry-transport]: https://github.com/tomer-yechiel/pino-sentry-transport +[Sentry]: https://sentry.io/ ### pino-seq @@ -756,55 +1017,32 @@ pino(transport) [pino-seq-transport]: https://github.com/autotelic/pino-seq-transport [Seq]: https://datalust.co/seq - -### pino-sentry-transport + +### pino-slack-webhook -[pino-sentry-transport][pino-sentry-transport] is a Pino v7+ compatible transport to forward log events to [Sentry][Sentry] +[pino-slack-webhook][pino-slack-webhook] is a Pino v7+ compatible transport to forward log events to [Slack][Slack] from a dedicated worker: ```js const pino = require('pino') const transport = pino.transport({ - target: 'pino-sentry-transport', + target: '@youngkiu/pino-slack-webhook', options: { - sentry: { - dsn: 'https://******@sentry.io/12345', - } + webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx', + channel: '#pino-log', + username: 'webhookbot', + icon_emoji: ':ghost:' } }) pino(transport) ``` -[pino-sentry-transport]: https://github.com/tomer-yechiel/pino-sentry-transport -[Sentry]: https://sentry.io/ - - - -### pino-airbrake-transport - -[pino-airbrake-transport][pino-airbrake-transport] is a Pino v7+ compatible transport to forward log events to [Airbrake][Airbrake] -from a dedicated worker: +[pino-slack-webhook]: https://github.com/youngkiu/pino-slack-webhook +[Slack]: https://slack.com/ -```js -const pino = require('pino') -const transport = pino.transport({ - target: 'pino-airbrake-transport', - options: { - airbrake: { - projectId: 1, - projectKey: "REPLACE_ME", - environment: "production", - // additional options for airbrake - performanceStats: false, - }, - }, - level: "error", // minimum log level that should be sent to airbrake -}) -pino(transport) -``` +[pino-pretty]: https://github.com/pinojs/pino-pretty -[pino-airbrake-transport]: https://github.com/enricodeleo/pino-airbrake-transport -[Airbrake]: https://airbrake.io/ +For full documentation of command line switches read the [README](https://github.com/abeai/pino-websocket#readme). ### pino-socket @@ -828,69 +1066,6 @@ Logs from the application should be observed on both consoles. [pino-socket]: https://www.npmjs.com/package/pino-socket - -### pino-datadog-transport - -[pino-datadog-transport][pino-datadog-transport] is a Pino v7+ compatible transport to forward log events to [Datadog][Datadog] -from a dedicated worker: - -```js -const pino = require('pino') -const transport = pino.transport({ - target: 'pino-datadog-transport', - options: { - ddClientConf: { - authMethods: { - apiKeyAuth: - } - }, - }, - level: "error", // minimum log level that should be sent to datadog -}) -pino(transport) -``` - -[pino-datadog-transport]: https://github.com/theogravity/pino-datadog-transport -[Datadog]: https://www.datadoghq.com/ - -#### Logstash - -The [pino-socket][pino-socket] module can also be used to upload logs to -[Logstash][logstash] via: - -``` -$ node app.js | pino-socket -a 127.0.0.1 -p 5000 -m tcp -``` - -Assuming logstash is running on the same host and configured as -follows: - -``` -input { - tcp { - port => 5000 - } -} - -filter { - json { - source => "message" - } -} - -output { - elasticsearch { - hosts => "127.0.0.1:9200" - } -} -``` - -See to learn -how to setup [Kibana][kibana]. - -For Docker users, see -https://github.com/deviantony/docker-elk to setup an ELK stack. - ### pino-stackdriver The [pino-stackdriver](https://www.npmjs.com/package/pino-stackdriver) module is a transport that will forward logs to the [Google Stackdriver](https://cloud.google.com/logging/) log service through its API. @@ -926,147 +1101,6 @@ Example output for the "hello world" log: [rfc3164]: https://tools.ietf.org/html/rfc3164 [logstash]: https://www.elastic.co/products/logstash - - -### pino-websocket - -[pino-websocket](https://www.npmjs.com/package/@abeai/pino-websocket) is a transport that will forward each log line to a websocket server. - -```sh -$ node app.js | pino-websocket -a my-websocket-server.example.com -p 3004 -``` - -For full documentation of command line switches read the [README](https://github.com/abeai/pino-websocket#readme). - - -### pino-slack-webhook - -[pino-slack-webhook][pino-slack-webhook] is a Pino v7+ compatible transport to forward log events to [Slack][Slack] -from a dedicated worker: - -```js -const pino = require('pino') -const transport = pino.transport({ - target: '@youngkiu/pino-slack-webhook', - options: { - webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx', - channel: '#pino-log', - username: 'webhookbot', - icon_emoji: ':ghost:' - } -}) -pino(transport) -``` - -[pino-slack-webhook]: https://github.com/youngkiu/pino-slack-webhook -[Slack]: https://slack.com/ - -[pino-pretty]: https://github.com/pinojs/pino-pretty - -For full documentation of command line switches read the [README](https://github.com/abeai/pino-websocket#readme). - - -### pino-axiom - -[pino-axiom](https://www.npmjs.com/package/pino-axiom) is a transport that will forward logs to [Axiom](https://axiom.co). - -```javascript -const pino = require('pino') -const transport = pino.transport({ - target: 'pino-axiom', - options: { - orgId: 'YOUR-ORG-ID', - token: 'YOUR-TOKEN', - dataset: 'YOUR-DATASET', - }, -}) -pino(transport) -``` - - -### pino-opentelemetry-transport - -[pino-opentelemetry-transport](https://www.npmjs.com/package/pino-opentelemetry-transport) is a transport that will forward logs to an [OpenTelemetry log collector](https://opentelemetry.io/docs/collector/) using [OpenTelemetry JS instrumentation](https://opentelemetry.io/docs/instrumentation/js/). - -```javascript -const pino = require('pino') - -const transport = pino.transport({ - target: 'pino-opentelemetry-transport', - options: { - resourceAttributes: { - 'service.name': 'test-service', - 'service.version': '1.0.0' - } - } -}) - -pino(transport) -``` - -Documentation on running a minimal example is available in the [README](https://github.com/Vunovati/pino-opentelemetry-transport#minimalistic-example). - - -### @axiomhq/pino - -[@axiomhq/pino](https://www.npmjs.com/package/@axiomhq/pino) is the official [Axiom](https://axiom.co/) transport for Pino, using [axiom-js](https://github.com/axiomhq/axiom-js). - -```javascript -import pino from 'pino'; - -const logger = pino( - { level: 'info' }, - pino.transport({ - target: '@axiomhq/pino', - options: { - dataset: process.env.AXIOM_DATASET, - token: process.env.AXIOM_TOKEN, - }, - }), -); -``` - -then you can use the logger as usual: - -```js -logger.info('Hello from pino!'); -``` - -For further examples, head over to the [examples](https://github.com/axiomhq/axiom-js/tree/main/examples/pino) directory. - - -### pino-discord-webhook - -[pino-discord-webhook](https://github.com/fabulousgk/pino-discord-webhook) is a Pino v7+ compatible transport to forward log events to a [Discord](http://discord.com) webhook from a dedicated worker. - -```js -import pino from 'pino' - -const logger = pino({ - transport: { - target: 'pino-discord-webhook', - options: { - webhookUrl: 'https://discord.com/api/webhooks/xxxx/xxxx', - } - } -}) -``` - - -### pino-logfmt - -[pino-logfmt](https://github.com/botflux/pino-logfmt) is a Pino v7+ transport that formats logs into [logfmt](https://brandur.org/logfmt). This transport can output the formatted logs to stdout or file. - -```js -import pino from 'pino' - -const logger = pino({ - transport: { - target: 'pino-logfmt' - } -}) -``` - ### pino-telegram-webhook @@ -1094,6 +1128,17 @@ logger.error('test log!'); The `extra` parameter is optional. Parameters that the method [`sendMessage`](https://core.telegram.org/bots/api#sendmessage) supports can be passed to it. + +### pino-websocket + +[pino-websocket](https://www.npmjs.com/package/@abeai/pino-websocket) is a transport that will forward each log line to a websocket server. + +```sh +$ node app.js | pino-websocket -a my-websocket-server.example.com -p 3004 +``` + +For full documentation of command line switches read the [README](https://github.com/abeai/pino-websocket#readme). + ### pino-yc-transport @@ -1121,53 +1166,6 @@ logger.error(new Error("error")); logger.fatal("fatal"); ``` - -### @macfja/pino-fingers-crossed - -[@macfja/pino-fingers-crossed](https://github.com/MacFJA/js-pino-fingers-crossed) is a Pino v7+ transport that holds logs until a log level is reached, allowing to only have logs when it matters. - -```js -const pino = require('pino'); -const { default: fingersCrossed, enable } = require('@macfja/pino-fingers-crossed') - -const logger = pino(fingersCrossed()); - -logger.info('Will appear immedialty') -logger.error('Will appear immedialty') - -logger.setBindings({ [enable]: 50 }) -logger.info('Will NOT appear immedialty') -logger.info('Will NOT appear immedialty') -logger.error('Will appear immedialty as well as the 2 previous messages') // error log are level 50 -logger.info('Will NOT appear') -logger.info({ [enable]: false }, 'Will appear immedialty') -logger.info('Will NOT appear') -``` - -### pino-hana -[pino-hana](https://github.com/HiImGiovi/pino-hana) is a Pino v7+ transport that save pino logs to a SAP HANA database. -```js -const pino = require('pino') -const logger = pino({ - transport: { - target: 'pino-hana', - options: { - connectionOptions: { - host: , - port: , - user: , - password: , - }, - schema: , - table:
, - }, - }, -}) - -logger.info('hi') // this log will be saved into SAP HANA -``` -For more detailed information about its usage please check the official [documentation](https://github.com/HiImGiovi/pino-hana#readme). - ## Communication between Pino and Transports Here we discuss some technical details of how Pino communicates with its [worker threads](https://nodejs.org/api/worker_threads.html).