From 33ea093d163becba096720a77426cf758065f423 Mon Sep 17 00:00:00 2001 From: Joshua Wise Date: Tue, 24 Oct 2023 04:48:49 -0700 Subject: [PATCH] updated docs and tests --- docs/readers.md | 18 +++++++++--------- docs/writers.md | 8 ++++---- test/21.master-logger.js | 10 +++++----- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/readers.md b/docs/readers.md index 739dc17..8fcba71 100644 --- a/docs/readers.md +++ b/docs/readers.md @@ -27,7 +27,7 @@ - [enum `Lifecycle`](#enum-lifecycle) - [enum `HttpMethod`](#enum-httpmethod) -# *class* LogReader +## *class* LogReader This class is the primary interface used to read logs. Logs are stored in an efficient binary format, so they can't be read as plain text. @@ -163,7 +163,7 @@ for await (const chunk of reader.bulkRangeReversed(Date.now() - DAY, Date.now()) } ``` -# *class* LogEntry +## *class* LogEntry This class represents individual log entries. Every LogEntry has the following properties: @@ -245,7 +245,7 @@ Returns an object that describes an exception that was thrown. The object will e Returns a JSON-compatible representation of the LogEntry. -# *namespace* BulkParser +## *namespace* BulkParser ### BulkParser.read(chunks) @@ -292,7 +292,7 @@ for await (const block of BulkParser.read(rawChunks)) { } ``` -# *class* LogDirectorySource +## *class* LogDirectorySource Every [LogReader](#class-logreader) needs a source from which to read logs. The most common source is simply the filesystem directory that the logs were written to. LogDirectorySource does exactly that; it allows you to read log files from a directory on the filesystem. This class is not available in the browser. @@ -323,13 +323,13 @@ for await (const log of reader.tail(Date.now())) { } ``` -# *class* Vfs +## *class* Vfs Instead of using [LogDirectorySource][LogDirectorySource], you can read logs from any arbitrary source by creating your own implementation of Vfs. For example, this could allow you to read raw binary logs in a browser. To learn how to implement a Vfs, see the [source code](../src/shared/vfs.js). -# *enum* LogType +## *enum* LogType - `LogType.REQUEST`: This log indicates that an HTTP request was received. This log is only concerned with the HTTP request's "head"; the request body may still be pending. - `LogType.REQUEST_META`: This log contains application-specific metadata that was associated with an HTTP request. @@ -339,7 +339,7 @@ To learn how to implement a Vfs, see the [source code](../src/shared/vfs.js). - `LogType.LIFECYCLE`: This log indicates that a lifecycle event occured within the [server cluster's](https://nodejs.org/api/cluster.html) master process or one of its worker processes. - `LogType.UNCAUGHT_EXCEPTION`: This log indicates that an uncaught exception was thrown within the [server cluster's](https://nodejs.org/api/cluster.html) master process or one of its worker processes. -# *enum* LogLevel +## *enum* LogLevel - `LogType.CRITICAL`: This log represents a critical error that prevented the application from functioning even at a basic level. - `LogType.ERROR`: This log represents an unexpected error that prevented a user action from being satisfied. @@ -351,7 +351,7 @@ Note that there's no DEBUG level. That's because DEBUG logs are only *conditiona > Currently, there are three log types capable of containing error information (and thus containing DEBUG logs): `RESPONSE`, `RESPONSE_FINISHED`, and `UNCAUGHT_EXCEPTION`. -# *enum* Lifecycle +## *enum* Lifecycle All logs that have `log.type === LogType.LIFECYCLE` additionally have an `event` property, indicating the lifecycle event that has occured: @@ -370,7 +370,7 @@ All logs that have `log.type === LogType.LIFECYCLE` additionally have an `event` - `Lifecycle.MASTER_PING`: Used internally. - `Lifecycle.WORKER_PING`: Used internally. -# *enum* HttpMethod +## *enum* HttpMethod - `HttpMethod.GET` - `HttpMethod.HEAD` diff --git a/docs/writers.md b/docs/writers.md index 1c2c4ad..f7a443d 100644 --- a/docs/writers.md +++ b/docs/writers.md @@ -28,7 +28,7 @@ - [`requestLogger.closed`](#requestloggerclosed) - [`requestLogger.requestId`](#requestloggerrequestid) -# *class* LogManager +## *class* LogManager This class faciliates log rotation. It should be used within the master process of your [server cluster](https://nodejs.org/api/cluster.html). It keeps track of log files within a directory, detects when the log files get too big or too old, and deletes the oldest files when necessary. It also provides the filenames that your loggers should write to. @@ -81,7 +81,7 @@ The file path of the log directory being managed. The file path of the current log file that all loggers should be writing to. -# *class* MasterLogger +## *class* MasterLogger This is the logger used by the [server cluster's](https://nodejs.org/api/cluster.html) master process. It internally maintains state that is necessary for writing well-formed logs, so only one instance should be used for the entire lifespan of the master process. @@ -136,7 +136,7 @@ Closes the logger, flushing any remaining logs to the filesystem. This happens s Indicates whether or not the logger is closed. -# *class* WorkerLogger +## *class* WorkerLogger This is the logger used by each worker process within a [server cluster](https://nodejs.org/api/cluster.html). Each worker process should only have one WorkerLogger. @@ -194,7 +194,7 @@ Closes the logger, flushing any remaining logs to the filesystem. This happens s Indicates whether or not the logger is closed. -# *class* RequestLogger +## *class* RequestLogger Whenever a worker process receives an HTTP request, you should use the [WorkerLogger][WorkerLogger] to spawn a new RequestLogger, and then use that RequestLogger for all request-related activity. Each HTTP request should have its own associated RequestLogger. diff --git a/test/21.master-logger.js b/test/21.master-logger.js index 613ec2b..afd634d 100644 --- a/test/21.master-logger.js +++ b/test/21.master-logger.js @@ -264,14 +264,14 @@ describe('MasterLogger', function () { }); specify('are written periodically even if other logs are written', async function () { - this.slow(400); - logger = new MasterLogger(util.next(), { pingDelay: 50, compression: false }); + this.slow(500); + logger = new MasterLogger(util.next(), { pingDelay: 100, compression: false }); logger.info('hi'); - await new Promise(r => setTimeout(r, 20)); + await new Promise(r => setTimeout(r, 30)); logger.info('hi'); - await new Promise(r => setTimeout(r, 20)); + await new Promise(r => setTimeout(r, 30)); logger.info('hi'); - await new Promise(r => setTimeout(r, 20)); + await new Promise(r => setTimeout(r, 70)); expect(fs.readFileSync(util.current())).to.deep.equal(new Uint8Array()); logger.flush(); const reader = new Reader(fs.readFileSync(util.current()));