@wbce/projen-d9 0.0.28 → 0.1.0

package/node_modules/pino/docs/ecosystem.md

@@ -0,0 +1,87 @@
+# Pino Ecosystem
+
+This is a list of ecosystem modules that integrate with `pino`.
+
+Modules listed under [Core](#core) are maintained by the Pino team. Modules
+listed under [Community](#community) are maintained by independent community
+members.
+
+Please send a PR to add new modules!
+
+<a id="core"></a>
+## Core
+
+### Frameworks
++ [`express-pino-logger`](https://github.com/pinojs/express-pino-logger): use
+Pino to log requests within [express](https://expressjs.com/).
++ [`koa-pino-logger`](https://github.com/pinojs/koa-pino-logger): use Pino to
+log requests within [Koa](https://koajs.com/).
++ [`restify-pino-logger`](https://github.com/pinojs/restify-pino-logger): use
+Pino to log requests within [restify](http://restify.com/).
++ [`rill-pino-logger`](https://github.com/pinojs/rill-pino-logger): use Pino as
+the logger for the [Rill framework](https://rill.site/).
+
+### Utilities
++ [`pino-arborsculpture`](https://github.com/pinojs/pino-arborsculpture): change
+log levels at runtime.
++ [`pino-caller`](https://github.com/pinojs/pino-caller): add callsite to the log line.
++ [`pino-clf`](https://github.com/pinojs/pino-clf): reformat Pino logs into
+Common Log Format.
++ [`pino-console`](https://github.com/pinojs/pino-console): adapter for the [WHATWG Console](https://console.spec.whatwg.org/) spec. 
++ [`pino-debug`](https://github.com/pinojs/pino-debug): use Pino to interpret
+[`debug`](https://npm.im/debug) logs.
++ [`pino-elasticsearch`](https://github.com/pinojs/pino-elasticsearch): send
+Pino logs to an Elasticsearch instance.
++ [`pino-eventhub`](https://github.com/pinojs/pino-eventhub): send Pino logs
+to an [Event Hub](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-what-is-event-hubs).
++ [`pino-filter`](https://github.com/pinojs/pino-filter): filter Pino logs in
+the same fashion as the [`debug`](https://npm.im/debug) module.
++ [`pino-gelf`](https://github.com/pinojs/pino-gelf): reformat Pino logs into
+GELF format for Graylog.
++ [`pino-hapi`](https://github.com/pinojs/hapi-pino): use Pino as the logger
+for [Hapi](https://hapijs.com/).
++ [`pino-http`](https://github.com/pinojs/pino-http): easily use Pino to log
+requests with the core `http` module.
++ [`pino-http-print`](https://github.com/pinojs/pino-http-print): reformat Pino
+logs into traditional [HTTPD](https://httpd.apache.org/) style request logs.
++ [`pino-mongodb`](https://github.com/pinojs/pino-mongodb): store Pino logs
+in a MongoDB database.
++ [`pino-multi-stream`](https://github.com/pinojs/pino-multi-stream): send
+logs to multiple destination streams (slow!).
++ [`pino-noir`](https://github.com/pinojs/pino-noir): redact sensitive information
+in logs.
++ [`pino-pretty`](https://github.com/pinojs/pino-pretty): basic prettifier to
+make log lines human-readable.
++ [`pino-socket`](https://github.com/pinojs/pino-socket): send logs to TCP or UDP
+destinations.
++ [`pino-std-serializers`](https://github.com/pinojs/pino-std-serializers): the
+core object serializers used within Pino.
++ [`pino-syslog`](https://github.com/pinojs/pino-syslog): reformat Pino logs
+to standard syslog format.
++ [`pino-tee`](https://github.com/pinojs/pino-tee): pipe Pino logs into files
+based upon log levels.
++ [`pino-test`](https://github.com/pinojs/pino-test): a set of utilities for 
+verifying logs generated by the Pino logger.
++ [`pino-toke`](https://github.com/pinojs/pino-toke): reformat Pino logs
+according to a given format string.
+
+
+<a id="community"></a>
+## Community
+
++ [`@google-cloud/pino-logging-gcp-config`](https://www.npmjs.com/package/@google-cloud/pino-logging-gcp-config): Config helper and formatter to output [Google Cloud Platform Structured Logging](https://cloud.google.com/logging/docs/structured-logging)
++ [`@newrelic/pino-enricher`](https://github.com/newrelic/newrelic-node-log-extensions/blob/main/packages/pino-log-enricher): a log customization to add New Relic context to use [Logs In Context](https://docs.newrelic.com/docs/logs/logs-context/logs-in-context/)
++ [`@sentry/node`](https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/pino/): Sentry SDK with native pinoIntegration for direct Pino instrumentation and error tracking.
++ [`cloud-pine`](https://github.com/metcoder95/cloud-pine): transport that provides abstraction and compatibility with [`@google-cloud/logging`](https://www.npmjs.com/package/@google-cloud/logging).
++ [`cls-proxify`](https://github.com/keenondrums/cls-proxify): integration of pino and [CLS](https://github.com/jeff-lewis/cls-hooked). Useful for creating dynamically configured child loggers (e.g. with added trace ID) for each request.
++ [`crawlee-pino`](https://github.com/imyelo/crawlee-pino): use Pino to log within Crawlee
++ [`eslint-plugin-pino`](https://github.com/orzarchi/eslint-plugin-pino): linting rules for pino usage, primarly for preventing missing context in logs due to incorrect argument order.
++ [`pino-colada`](https://github.com/lrlna/pino-colada): cute ndjson formatter for pino.
++ [`pino-dev`](https://github.com/dnjstrom/pino-dev): simple prettifier for pino with built-in support for common ecosystem packages.
++ [`pino-fluentd`](https://github.com/davidedantonio/pino-fluentd): send Pino logs to Elasticsearch,
+MongoDB, and many [others](https://www.fluentd.org/dataoutputs) via Fluentd.
++ [`pino-lambda`](https://github.com/FormidableLabs/pino-lambda): log transport for cloudwatch support inside aws-lambda 
++ [`pino-pretty-min`](https://github.com/unjello/pino-pretty-min): a minimal
+prettifier inspired by the [logrus](https://github.com/sirupsen/logrus) logger.
++ [`pino-rotating-file`](https://github.com/homeaway/pino-rotating-file): a hapi-pino log transport for splitting logs into separate, automatically rotating files.
++ [`pino-tiny`](https://github.com/holmok/pino-tiny): a tiny (and extensible?) little log formatter for pino.

package/node_modules/pino/docs/help.md

@@ -0,0 +1,353 @@
+# Help
+
+* [Log rotation](#rotate)
+* [Reopening log files](#reopening)
+* [Saving to multiple files](#multiple)
+* [Log filtering](#filter-logs)
+* [Transports and systemd](#transport-systemd)
+* [Log to different streams](#multi-stream)
+* [Duplicate keys](#dupe-keys)
+* [Log levels as labels instead of numbers](#level-string)
+* [Pino with `debug`](#debug)
+* [Unicode and Windows terminal](#windows)
+* [Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Severity Levels](#stackdriver)
+* [Using Grafana Loki to evaluate pino logs in a kubernetes cluster](#grafana-loki)
+* [Avoid Message Conflict](#avoid-message-conflict)
+* [Best performance for logging to `stdout`](#best-performance-for-stdout)
+* [Testing](#testing)
+
+<a id="rotate"></a>
+## Log rotation
+
+Use a separate tool for log rotation:
+We recommend [logrotate](https://github.com/logrotate/logrotate).
+Consider we output our logs to `/var/log/myapp.log` like so:
+
+```
+$ node server.js > /var/log/myapp.log
+```
+
+We would rotate our log files with logrotate, by adding the following to `/etc/logrotate.d/myapp`:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       copytruncate
+}
+```
+
+The `copytruncate` configuration has a very slight possibility of lost log lines due
+to a gap between copying and truncating - the truncate may occur after additional lines
+have been written. To perform log rotation without `copytruncate`, see the [Reopening log files](#reopening)
+help.
+
+<a id="reopening"></a>
+## Reopening log files
+
+In cases where a log rotation tool doesn't offer copy-truncate capabilities,
+or where using them is deemed inappropriate, `pino.destination`
+can reopen file paths after a file has been moved away.
+
+One way to use this is to set up a `SIGUSR2` or `SIGHUP` signal handler that
+reopens the log file destination, making sure to write the process PID out
+somewhere so the log rotation tool knows where to send the signal.
+
+```js
+// write the process pid to a well known location for later
+const fs = require('node:fs')
+fs.writeFileSync('/var/run/myapp.pid', process.pid)
+
+const dest = pino.destination('/log/file')
+const logger = require('pino')(dest)
+process.on('SIGHUP', () => dest.reopen())
+```
+
+The log rotation tool can then be configured to send this signal to the process
+after a log rotation event has occurred.
+
+Given a similar scenario as in the [Log rotation](#rotate) section a basic
+`logrotate` config that aligns with this strategy would look similar to the following:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       postrotate
+           kill -HUP `cat /var/run/myapp.pid`
+       endscript
+}
+```
+
+<a id="multiple"></a>
+## Saving to multiple files
+
+See [`pino.multistream`](/docs/api.md#pino-multistream).
+
+<a id="filter-logs"></a>
+## Log Filtering
+The Pino philosophy advocates common, preexisting, system utilities.
+
+Some recommendations in line with this philosophy are:
+
+1. Use [`grep`](https://linux.die.net/man/1/grep):
+    ```sh
+    $ # View all "INFO" level logs
+    $ node app.js | grep '"level":30'
+    ```
+1. Use [`jq`](https://stedolan.github.io/jq/):
+    ```sh
+    $ # View all "ERROR" level logs
+    $ node app.js | jq 'select(.level == 50)'
+    ```
+
+<a id="transport-systemd"></a>
+## Transports and systemd
+`systemd` makes it complicated to use pipes in services. One method for overcoming
+this challenge is to use a subshell:
+
+```
+ExecStart=/bin/sh -c '/path/to/node app.js | pino-transport'
+```
+
+<a id="multi-stream"></a>
+## Log to different streams
+
+Pino's default log destination is the singular destination of `stdout`. While
+not recommended for performance reasons, multiple destinations can be targeted
+by using [`pino.multistream`](/docs/api.md#pino-multistream).
+
+In this example, we use `stderr` for `error` level logs and `stdout` as default
+for all other levels (e.g. `debug`, `info`, and `warn`).
+
+```js
+const pino = require('pino')
+var streams = [
+  {level: 'debug', stream: process.stdout},
+  {level: 'error', stream: process.stderr},
+  {level: 'fatal', stream: process.stderr}
+]
+
+const logger = pino({
+  name: 'my-app',
+  level: 'debug', // must be the lowest level of all streams
+}, pino.multistream(streams))
+```
+
+<a id="dupe-keys"></a>
+## How Pino handles duplicate keys
+
+Duplicate keys are possible when a logged object contains a top-level key that
+collides with a Pino field or a key in the child logger's bindings, or when child
+logger bindings collide with parent bindings.
+
+For untrusted data, avoid passing externally supplied objects directly to logging
+methods or child logger bindings. User-controlled top-level keys can conflict
+with Pino fields such as `level`, `time`, or `msg`, as well as application or
+security fields. If untrusted data must be logged, place it under an
+application-controlled key, such as `logger.info({ untrusted })`, and prefer not
+to log untrusted data at all unless necessary.
+
+See the [child logger duplicate keys caveat](/docs/child-loggers.md#duplicate-keys-caveat)
+and [`logger.child()` bindings](/docs/api.md#logger-child-bindings) for more information.
+
+<a id="level-string"></a>
+## Log levels as labels instead of numbers
+Pino log lines are meant to be parsable. Thus, Pino's default mode of operation
+is to print the level value instead of the string name. 
+However, you can use the [`formatters`](/docs/api.md#formatters-object) option 
+with a [`level`](/docs/api.md#level) function to print the string name instead of the level value :
+
+```js
+const pino = require('pino')
+
+const log = pino({
+  formatters: {
+    level: (label) => {
+      return {
+        level: label
+      }
+    }
+  }
+})
+
+log.info('message')
+
+// {"level":"info","time":1661632832200,"pid":18188,"hostname":"foo","msg":"message"}
+```
+
+Although it works, we recommend using one of these options instead if you are able:
+
+1. If the only change desired is the name then a transport can be used. One such
+transport is [`pino-text-level-transport`](https://npm.im/pino-text-level-transport).
+1. Use a prettifier like [`pino-pretty`](https://npm.im/pino-pretty) to make
+the logs human friendly.
+
+<a id="debug"></a>
+## Pino with `debug`
+
+The popular [`debug`](https://npm.im/debug) is used in many modules across the ecosystem.
+
+The [`pino-debug`](https://github.com/pinojs/pino-debug) module
+can capture calls to `debug` loggers and run them
+through `pino` instead. This results in a 10x (20x in asynchronous mode)
+performance improvement - even though `pino-debug` is logging additional
+data and wrapping it in JSON.
+
+To quickly enable this install [`pino-debug`](https://github.com/pinojs/pino-debug)
+and preload it with the `-r` flag, enabling any `debug` logs with the
+`DEBUG` environment variable:
+
+```sh
+$ npm i pino-debug
+$ DEBUG=* node -r pino-debug app.js
+```
+
+[`pino-debug`](https://github.com/pinojs/pino-debug) also offers fine-grain control to map specific `debug`
+namespaces to `pino` log levels. See [`pino-debug`](https://github.com/pinojs/pino-debug)
+for more.
+
+<a id="windows"></a>
+## Unicode and Windows terminal
+
+Pino uses [sonic-boom](https://github.com/mcollina/sonic-boom) to speed
+up logging. Internally, it uses [`fs.write`](https://nodejs.org/dist/latest-v10.x/docs/api/fs.html#fs_fs_write_fd_string_position_encoding_callback) to write log lines directly to a file
+descriptor. On Windows, Unicode output is not handled properly in the
+terminal (both `cmd.exe` and PowerShell), and as such the output could
+be visualized incorrectly if the log lines include utf8 characters. It
+is possible to configure the terminal to visualize those characters
+correctly with the use of [`chcp`](https://ss64.com/nt/chcp.html) by
+executing in the terminal `chcp 65001`. This is a known limitation of
+Node.js.
+
+<a id="stackdriver"></a>
+## Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Severity Levels
+
+Google Cloud Logging uses `severity` levels instead of log levels. As a result, all logs may show as INFO
+level logs while completely ignoring the level set in the pino log. Google Cloud Logging also prefers that
+log data is present inside a `message` key instead of the default `msg` key that Pino uses. Use a technique
+similar to the one below to retain log levels in Google Cloud Logging
+
+```js
+const pino = require('pino')
+
+// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
+const PinoLevelToSeverityLookup = {
+  trace: 'DEBUG',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+};
+
+const defaultPinoConf = {
+  messageKey: 'message',
+  formatters: {
+    level(label, number) {
+      return {
+        severity: PinoLevelToSeverityLookup[label] || PinoLevelToSeverityLookup['info'],
+        level: number,
+      }
+    }
+  },
+}
+
+module.exports = function createLogger(options) {
+  return pino(Object.assign({}, options, defaultPinoConf))
+}
+```
+
+A library that configures Pino for
+[Google Cloud Structured Logging](https://cloud.google.com/logging/docs/structured-logging)
+is available at:
+[@google-cloud/pino-logging-gcp-config](https://www.npmjs.com/package/@google-cloud/pino-logging-gcp-config)
+
+This library has the following features:
+
++ Converts Pino log levels to Google Cloud Logging log levels, as above
++ Uses `message` instead of `msg` for the message key, as above
++ Adds a millisecond-granularity timestamp in the 
+  [structure](https://cloud.google.com/logging/docs/agent/logging/configuration#timestamp-processing)
+  recognised by Google Cloud Logging eg: \
+  `"timestamp":{"seconds":1445470140,"nanos":123000000}`
++ Adds a sequential
+  [`insertId`](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.insert_id)
+  to ensure log messages with identical timestamps are ordered correctly.
++ Logs including an `Error` object have the
+  [`stack_trace`](https://cloud.google.com/error-reporting/docs/formatting-error-messages#log-error)
+  property set so that the error is forwarded to Google Cloud Error Reporting.
++ Includes a
+  [`ServiceContext`](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext)
+  object in the logs for Google Cloud Error Reporting, auto detected from the
+  environment if not specified
++ Maps the OpenTelemetry properties `span_id`, `trace_id`, and `trace_flags`
+  to the equivalent Google Cloud Logging fields.
+
+<a id="grafana-loki"></a>
+## Using Grafana Loki to evaluate pino logs in a kubernetes cluster
+
+To get pino logs into Grafana Loki there are two options:
+
+1. **Push:** Use [pino-loki](https://github.com/Julien-R44/pino-loki) to send logs directly to Loki.
+1. **Pull:** Configure Grafana Promtail to read and properly parse the logs before sending them to Loki.  
+   Similar to Google Cloud logging, this involves remapping the log levels. See this [article](https://medium.com/@janpaepke/structured-logging-in-the-grafana-monitoring-stack-8aff0a5af2f5) for details.
+
+<a id="avoid-message-conflict"></a>
+## Avoid Message Conflict
+
+As described in the [`message` documentation](/docs/api.md#message), when a log
+is written like `log.info({ msg: 'a message' }, 'another message')` then the
+final output JSON will have `"msg":"another message"` and the `'a message'`
+string will be lost. To overcome this, the [`logMethod` hook](/docs/api.md#logmethod)
+can be used:
+
+```js
+'use strict'
+
+const log = require('pino')({
+  level: 'debug',
+  hooks: {
+    logMethod (inputArgs, method) {
+      if (inputArgs.length === 2 && inputArgs[0].msg) {
+       inputArgs[0].originalMsg = inputArgs[0].msg
+      }
+      return method.apply(this, inputArgs)
+    }
+  }
+})
+
+log.info('no original message')
+log.info({ msg: 'mapped to originalMsg' }, 'a message')
+
+// {"level":30,"time":1596313323106,"pid":63739,"hostname":"foo","msg":"no original message"}
+// {"level":30,"time":1596313323107,"pid":63739,"hostname":"foo","msg":"a message","originalMsg":"mapped to originalMsg"}
+```
+
+<a id="best-performance-for-stdout"></a>
+## Best performance for logging to `stdout`
+
+The best performance for logging directly to stdout is _usually_ achieved by using the
+default configuration:
+
+```js
+const log = require('pino')();
+```
+
+You should only have to configure custom transports or other settings
+if you have broader logging requirements.
+
+<a id="testing"></a>
+## Testing
+
+See [`pino-test`](https://github.com/pinojs/pino-test).

package/node_modules/pino/docs/lts.md

@@ -0,0 +1,93 @@
+## Long Term Support
+
+Pino's Long Term Support (LTS) is provided according to the schedule laid
+out in this document:
+
+1. Major releases, "X" release of [semantic versioning][semver] X.Y.Z release
+   versions, are supported for a minimum period of six months from their release
+   date. The release date of any specific version can be found at
+   [https://github.com/pinojs/pino/releases](https://github.com/pinojs/pino/releases).
+
+1. Major releases will receive security updates for an additional six months
+   from the release of the next major release. After this period
+   we will still review and release security fixes as long as they are
+   provided by the community and they do not violate other constraints,
+   e.g. minimum supported Node.js version.
+
+1. Major releases will be tested and verified against all Node.js
+   release lines that are supported by the
+   [Node.js LTS policy](https://github.com/nodejs/Release) within the
+   LTS period of that given Pino release line. This implies that only
+   the latest Node.js release of a given line is supported.
+
+A "month" is defined as 30 consecutive days.
+
+> ## Security Releases and Semver
+>
+> As a consequence of providing long-term support for major releases, there
+> are occasions where we need to release breaking changes as a _minor_
+> version release. Such changes will _always_ be noted in the
+> [release notes](https://github.com/pinojs/pino/releases).
+>
+> To avoid automatically receiving breaking security updates it is possible to use
+> the tilde (`~`) range qualifier. For example, to get patches for the 6.1
+> release, and avoid automatically updating to the 6.1 release, specify
+> the dependency as `"pino": "~6.1.x"`. This will leave your application vulnerable,
+> so please use with caution.
+
+[semver]: https://semver.org/
+
+<a name="supported-nodejs"></a>
+
+### Supported Node.js versions
+
+Pino follows the [Node.js release schedule][node-release]. A Pino release line
+is tested against, and supports, every Node.js release line that is in its
+_current_, _active LTS_, or _maintenance LTS_ phase when the Pino line is
+released, as described above.
+
+Support for a Node.js version is **only dropped in a new Pino major release**. A
+published Pino major will never drop a Node.js release line that it originally
+shipped with, so upgrading within a major line (for example, from `9.1.0` to
+`9.4.0`) will never remove support for a Node.js version you already run on.
+
+Once a Node.js release line reaches its end-of-life, Pino supports it on a
+best-effort basis, with the following caveats:
+
+- End-of-life Node.js versions are not exercised in continuous integration.
+- Some fixes and features cannot be backported to the Pino lines that still
+  support them.
+- Dependencies cannot be kept up to date.
+
+To keep running on an end-of-life Node.js version, pin your dependency to the
+last Pino major line that supported it. The [Schedule](#lts-schedule) below maps
+each Pino release line to the Node.js versions it supports; for example, to stay
+on Node.js 14, install the latest `8.x` release with `"pino": "8.x"`.
+
+[node-release]: https://github.com/nodejs/release#release-schedule
+
+<a name="lts-schedule"></a>
+
+### Schedule
+
+| Version | Release Date | End Of LTS Date | Node.js              |
+| :------ | :----------- | :-------------- | :------------------- |
+| 9.x     | 2024-04-26   | TBD             | 18, 20, 22            |
+| 8.x     | 2022-06-01   | 2024-10-26      | 14, 16, 18, 20        |
+| 7.x     | 2021-10-14   | 2023-06-01      | 12, 14, 16           |
+| 6.x     | 2020-03-07   | 2022-04-14      | 10, 12, 14, 16       |
+
+<a name="supported-os"></a>
+
+### CI tested operating systems
+
+Pino uses GitHub Actions for CI testing, please refer to
+[GitHub's documentation regarding workflow runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
+for further details on what the latest virtual environment is in relation to
+the YAML workflow labels below:
+
+| OS      | YAML Workflow Label    | Node.js      |
+|---------|------------------------|--------------|
+| Linux   | `ubuntu-latest`        | 18, 20, 22   |
+| Windows | `windows-latest`       | 18, 20, 22   |
+| MacOS   | `macos-latest`         | 18, 20, 22   |

package/node_modules/pino/docs/pretty.md

@@ -0,0 +1,38 @@
+# Pretty Printing
+
+By default, Pino log lines are newline delimited JSON (NDJSON). This is perfect
+for production usage and long-term storage. It's not so great for development
+environments. Thus, Pino logs can be prettified by using a Pino prettifier
+module like [`pino-pretty`][pp]:
+
+1. Install a prettifier module as a separate dependency, e.g. `npm install pino-pretty`.
+2. Instantiate the logger with the `transport.target` option set to `'pino-pretty'`:
+  ```js
+  const pino = require('pino')
+  const logger = pino({
+    transport: {
+      target: 'pino-pretty'
+    },
+  })
+
+  logger.info('hi')
+  ```
+3. The transport option can also have an options object containing `pino-pretty` options:
+  ```js
+  const pino = require('pino')
+  const logger = pino({
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true
+      }
+    }
+  })
+
+  logger.info('hi')
+  ```
+
+**Note:** `logger.flush()` does not flush the output of `pino-pretty`. See
+[Flush Limitations with `pino-pretty`](/docs/asynchronous.md) for more details.
+
+  [pp]: https://github.com/pinojs/pino-pretty