Fleshed out monitor and logging docs (#78, #27)

benjaminbojko · benjaminbojko · commit 8ef66063e08e · 2022-10-31T12:27:07.000-04:00
diff --git a/.docs/generate.mjs b/.docs/generate.mjs
@@ -36,22 +36,26 @@ const renderSourceDocs = async (sources) => {
 }
 
 const defaults = {
-	"files": "packages/**/lib/*.js",
+	"files": "packages/**/*.js",
 	"heading-depth": 2,
 	"name-format": true,
 	"separators": true,
 	"partial": [
 		".docs/partials/class-members.hbs",
 		".docs/partials/inline-see.hbs"
 	],
-	"helper": [".docs/helpers/helpers.js"],
+	"helper": [
+		".docs/helpers/helpers.js"
+	],
 	"module-index-format": "list",
 	"global-index-format": "list",
 	"param-index-format": "list",
 	"property-index-format": "list",
 	"member-index-format": "grouped"
 };
 
+await renderDocs({...defaults, templatePath: 'packages/launchpad/.docs/hooks.hbs', outputPath: 'packages/launchpad/docs/hooks.md', "heading-depth": 3});
+await renderDocs({...defaults, templatePath: 'packages/launchpad/.docs/logging.hbs', outputPath: 'packages/launchpad/docs/logging.md', "heading-depth": 3});
 await renderDocs({...defaults, templatePath: 'packages/content/README.hbs', outputPath: 'packages/content/README.md'});
 await renderDocs({...defaults, templatePath: 'packages/monitor/README.hbs', outputPath: 'packages/monitor/README.md', "heading-depth": 3});
 await renderSourceDocs(['airtable', 'contentful', 'json', 'sanity', 'strapi']);
diff --git a/.docs/partials/class-members.hbs b/.docs/partials/class-members.hbs
@@ -2,6 +2,9 @@
 {{#class name=name}}
 {{>heading-indent}} {{name}}
 {{#if description}}{{~{escape description}~}}{{/if}}
+
+{{>inline-see}}
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 {{#children inherited=undefined ~}}| <a name="{{{anchorName}}}">{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}}
@@ -15,6 +18,6 @@
 {{#if @suffix}} {{@suffix}}{{/if~}}
 {{{@depClose}~}}
 {{~/sig}}{{/if~}}
-{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} | {{#unless (equal defaultvalue undefined)}} {{#linebreaks-to-br}}<code>{{~{escape defaultvalue}}}</code>{{/linebreaks-to-br}} {{/unless}} | {{#linebreaks-to-br}}{{~{escape description}~}}{{/linebreaks-to-br}}{{#if see~}}<br><br>{{>inline-see}}{{/if}} |
+{{#if virtual}}*{{/if}}{{#with (parentObject)}}{{#if virtual}}*{{/if~}}{{/with~}} | {{#unless (equal defaultvalue undefined)}} {{#linebreaks-to-br}}<code>{{~{escape defaultvalue}~}}</code>{{/linebreaks-to-br}} {{/unless}} | {{#linebreaks-to-br}}{{~{escape description}~}}{{/linebreaks-to-br}}{{#if see~}}<br><br>{{>inline-see}}{{/if}} |
 {{/children~}}
 {{/class}}
diff --git a/.docs/partials/inline-see.hbs b/.docs/partials/inline-see.hbs
@@ -1,12 +1,6 @@
 {{#if see~}}
 
-{{#if (equal see.length 1)~}}
-See: {{{inlineLinks see.[0]}}}
-{{else~}}
-See
+{{#if (equal see.length 1)~}}See: {{{inlineLinks see.[0]}}}{{else~}}
+See: {{#each see}} {{{inlineLinks this}}}{{#unless @last}},{{/unless}}{{/each~}}.{{/if~}}
 
-{{#each see}}- {{{inlineLinks this}}}
-{{/each}}
-
-{{/if~}}
 {{/if~}}
diff --git a/packages/content/README.md b/packages/content/README.md
@@ -105,6 +105,8 @@ Once content is downloaded it can be processed to transform text and images. For
 
 ##  ContentOptions
 Options for all content and media downloads. Each of these settings can also be configured per `ContentSource`.
+
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_launchpad-content/content-options.ContentOptions+sources">`sources`</a> |  <code>Array.&lt;SourceOptions&gt;</code>|  <code>[]</code>  | A list of content source options. This defines which content is downloaded from where. |
diff --git a/packages/content/docs/airtable-source.md b/packages/content/docs/airtable-source.md
@@ -3,6 +3,8 @@
 
 ##  AirtableOptions
 Options for AirtableSource
+
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_airtable-source.AirtableOptions+baseId">`baseId`</a> |  <code>string</code>|  | Airtable base ID. @see https://help.appsheet.com/en/articles/1785063-using-data-from-airtable#:~:text=To%20obtain%20the%20ID%20of,API%20page%20of%20the%20base. |
diff --git a/packages/content/docs/contentful-source.md b/packages/content/docs/contentful-source.md
@@ -5,15 +5,16 @@
 Configuration options for the Contentful ContentSource.
 
 Also supports all fields of the Contentful SDK's config.
+
+See: 'Configuration' under https://contentful.github.io/contentful.js/contentful/9.1.7/
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_contentful-source.ContentfulOptions+space">`space`</a> |  <code>string</code>|  <code>''</code>  | Your Contentful space ID. Note that credentials.json will require an accessToken in addition to this |
 | <a name="module_contentful-source.ContentfulOptions+locale">`locale`</a> |  <code>string</code>|  <code>'en-US'</code>  | Optional. Used to pull localized images. |
 | <a name="module_contentful-source.ContentfulOptions+filename">`filename`</a> |  <code>string</code>|  <code>'content.json'</code>  | Optional. The filename you want to use for where all content (entries and assets metadata) will be stored. |
 | <a name="module_contentful-source.ContentfulOptions+contentTypes">`contentTypes`</a> |  <code>Array.&lt;string&gt;</code>|  | Optionally limit queries to these content types.<br>This will also apply to linked assets.<br>Types that link to other types will include up to 10 levels of child content.<br>E.g. filtering by Story, might also include Chapters and Images.<br>Uses `searchParams['sys.contentType.sys.id[in]']` under the hood. |
 | <a name="module_contentful-source.ContentfulOptions+searchParams">`searchParams`</a> |  <code>Object</code>|  | Optional. Supports anything from https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters |
-| <a name="module_contentful-source.ContentfulOptions+imageParams">`imageParams`</a> |  <code>Object</code>|  | Optional. Applies to all images. Defaults to empty object.<br>\*\*IMPORTANT:\*\* If you change the parameters, you will have to delete all cached images since the modified date of the original image will not have changed.<br><br>See: https://www.contentful.com/developers/docs/references/images-api/#/reference/resizing-&-cropping/specify-focus-area
- |
+| <a name="module_contentful-source.ContentfulOptions+imageParams">`imageParams`</a> |  <code>Object</code>|  | Optional. Applies to all images. Defaults to empty object.<br>\*\*IMPORTANT:\*\* If you change the parameters, you will have to delete all cached images since the modified date of the original image will not have changed.<br><br>See: https://www.contentful.com/developers/docs/references/images-api/#/reference/resizing-&-cropping/specify-focus-area |
 | <a name="module_contentful-source.ContentfulOptions+protocol">`protocol`</a> |  <code>string</code>|  <code>'https'</code>  | Optional |
 | <a name="module_contentful-source.ContentfulOptions+host">`host`</a> |  <code>string</code>|  <code>'cdn.contentful.com'</code>  | Optional |
 | <a name="module_contentful-source.ContentfulOptions+usePreviewApi">`usePreviewApi`</a> |  <code>boolean</code>|  <code>false</code>  | Optional. Set to true if you want to use the preview API instead of the production version to view draft content. |
diff --git a/packages/content/docs/json-source.md b/packages/content/docs/json-source.md
@@ -30,6 +30,8 @@ All images contained in these json files will be downloaded while retaining the
 
 ##  JsonOptions
 
+
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_json-source.JsonOptions+mediaPattern">`mediaPattern`</a> |  <code>RegExp</code>|  <code>(/.+(\.jpg\|\.jpeg\|\.png)/gi\|/.+(\.avi\|\.mov\|\.mp4\|\.mpg\|\.mpeg)/gi)</code>  | Regex for media files that should be downloaded from json sources |
diff --git a/packages/content/docs/sanity-source.md b/packages/content/docs/sanity-source.md
@@ -3,6 +3,8 @@
 
 ##  SanityOptions
 Options for SanitySource
+
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_sanity-source.SanityOptions+apiVersion">`apiVersion`</a> |  <code>string</code>|  <code>'v2021-10-21'</code>  | API Version |
diff --git a/packages/content/docs/strapi-source.md b/packages/content/docs/strapi-source.md
@@ -3,6 +3,8 @@
 
 ##  StrapiOptions
 Options for StrapiSource
+
+
 | Property | Type | Default | Description |
 | - | - | - | - |
 | <a name="module_strapi-source.StrapiOptions+version">`version`</a> |  <code>string</code>|  <code>'3'</code>  | Only version `'3'` is supported currently. |
diff --git a/packages/launchpad/.docs/hooks.hbs b/packages/launchpad/.docs/hooks.hbs
@@ -0,0 +1,38 @@
+# Event Hooks
+
+You can configure Launchpad to execute custom scripts before or after any of the central commands.
+
+## Example
+
+Hooks can be configured in `launchpad.json`. For example:
+
+```json
+{
+	"hooks": {
+		"post-update-content": ["npm run build"],
+		"pre-start-apps": ["taskkill /im chrome.exe /f"]
+	}
+}
+```
+
+Multiple hooks can be passed per event:
+
+```json
+"post-update-content": ["echo one", "echo two"]
+```
+
+## Available Hooks
+
+| Order | Command | Hook | Description |
+| - | - | - | - |
+| 1. | `startup` | `pre-startup` | Before content is updated and apps are launched (config and logger will already be initialized by then). |
+| 2. | `update-content` | `pre-update-content` | Before any content is updated. |
+| 3. | `update-content` | `post-update-content` | After all content has been updated. |
+| 4. | `start-apps` | `pre-start-apps` | Before any app is started. |
+| 5. | `start-apps` | `post-start-apps` | After all apps have been started. |
+| 6. | `startup` | `post-startup` | After content has been updated and apps have been started. |
+| 7. | `shutdown` | `pre-shutdown` | Before launchpad is shut down. |
+| 8. | `stop-apps` | `pre-stop-apps` | Before any apps are stopped. |
+| 9. | `stop-apps` | `post-stop-apps` | After all apps were stopped. |
+| 10. | `shutdown` | `post-shutdown` | After all apps have been stopped and just before launchpad will shutdown. |
+
diff --git a/packages/launchpad/.docs/logging.hbs b/packages/launchpad/.docs/logging.hbs
@@ -0,0 +1,40 @@
+# Logging
+
+All logs are routed to and handled by [Winston](https://www.npmjs.com/package/winston) by the [LogManager](packages\utils\lib\log-manager.js) class.
+
+Logs are funneled to:
+- The console with colorization
+- Launchpad log files for `info`, `error` and `debug` with no colorization
+- App log files for `stdout` and `stderr` with no colorization
+
+## Configuration
+
+To log everything up to the debug level, you can start launchpad with:
+
+```
+npx launchpad --logging.level=debug
+```
+
+Available log levels are: error
+
+0. `error`
+1. `warn`
+2. `info`
+3. `http`
+4. `verbose`
+5. `debug`
+6. `silly`
+
+All settings can be configured via `launchpad.json` or by passing in the appropriate CLI launch flag (e.g. `--logging.fileOptions.dirname=my-logs` to save logs to `my-logs/`).
+
+## Capturing Application Logs
+
+Launchpad routes all the `stdout` and `stderr` logs of all apps to the console and file based the settings [LogManager](packages\utils\lib\log-manager.js). See [Launchpad Monitor](/packages/monitor/README.md#logging-app-output) for more info.
+
+## Advanced Configuration
+
+See below for all available options and settings for logging.
+
+{{>class-members name="LogOptions"}}
+
+{{>class-members name="LogFileOptions"}}
diff --git a/packages/launchpad/docs/logging.md b/packages/launchpad/docs/logging.md
@@ -25,20 +25,38 @@ Available log levels are: error
 5. `debug`
 6. `silly`
 
-All of the below settings can be configured via `launchpad.json` or by passing in the appropriate CLI launch flag (e.g. `--logging.fileOptions.dirname=my-logs` to save logs to `my-logs/`) example with default settings:
-
-```json
-{
-  "logging": {
-    "level": "info",
-    "filename": "%DATE%-%LOG_TYPE%",
-    "fileOptions": {
-      "extension": ".log",
-      "dirname": ".logs",
-      "maxSize": "20m",
-      "maxFiles": "28d",
-      "datePattern": "YYYY-MM-DD",
-    }
-  }
-}
-```
+All settings can be configured via `launchpad.json` or by passing in the appropriate CLI launch flag (e.g. `--logging.fileOptions.dirname=my-logs` to save logs to `my-logs/`).
+
+## Capturing Application Logs
+
+Launchpad routes all the `stdout` and `stderr` logs of all apps to the console and file based the settings [LogManager](packages\utils\lib\log-manager.js). See [Launchpad Monitor](/packages/monitor/README.md#logging-app-output) for more info.
+
+## Advanced Configuration
+
+See below for all available options and settings for logging.
+
+
+###  LogOptions
+Options object passed directly to Winston's constructor, with additional options for Launchpad logging.
+
+See: https://github.com/winstonjs/winston#creating-your-own-logger for all available settings supported by Winston.
+| Property | Type | Default | Description |
+| - | - | - | - |
+| <a name="module_log-manager.LogOptions+filename">`filename`</a> |  <code>string</code>|  <code>`%DATE%-%LOG\_TYPE%`</code>  | Where to save logs to. |
+| <a name="module_log-manager.LogOptions+fileOptions">`fileOptions`</a> |  <code>LogFileOptions</code>|  <code>new LogFileOptions(fileOptions)</code>  | Options for individual files and streams. |
+| <a name="module_log-manager.LogOptions+level">`level`</a> |  <code>string</code>|  <code>'info'</code>  | The maximum log level to display in all default logs. |
+| <a name="module_log-manager.LogOptions+format">`format`</a> |  <code>winston.Logform.Format</code>|  <code>LogOptions.DEFAULT\_LOG\_FORMAT</code>  | The format for how each line is logged. |
+
+
+###  LogFileOptions
+
+
+See: https://github.com/winstonjs/winston-daily-rotate-file#options
+| Property | Type | Default | Description |
+| - | - | - | - |
+| <a name="module_log-manager.LogFileOptions+format">`format`</a> |  <code>winston.Logform.Format</code>|  <code>Uncolorized variant of LogOptions.DEFAULT\_LOG\_FORMAT</code>  | The format used for individual file logs. Uses the default log format but without colorization out of the box. |
+| <a name="module_log-manager.LogFileOptions+extension">`extension`</a> |  <code>string</code>|  <code>'.log'</code>  | File extension. |
+| <a name="module_log-manager.LogFileOptions+dirname">`dirname`</a> |  <code>string</code>|  <code>'.logs'</code>  | The directory under which all logs are saved. |
+| <a name="module_log-manager.LogFileOptions+maxSize">`maxSize`</a> |  <code>string</code>|  <code>'20m'</code>  | The max size of each individual log file. |
+| <a name="module_log-manager.LogFileOptions+maxFiles">`maxFiles`</a> |  <code>string</code>|  <code>'28d'</code>  | The maximum number of files to save per type. |
+| <a name="module_log-manager.LogFileOptions+datePattern">`datePattern`</a> |  <code>string</code>|  <code>'YYYY-MM-DD'</code>  | The date pattern used in file names. |
diff --git a/packages/monitor/README.hbs b/packages/monitor/README.hbs
@@ -66,8 +66,37 @@ The following `launchpad.json` will launch and monitor two apps. The first app w
 }
 ```
 
+## Logging App Output
+
+To capture your apps' logs in Launchpad Monitor you need to ensure that your apps are routing them to `stdout` and `stderr`.
+
+### Unity
+
+To redirect Unity's logs to stdout and stderr, launch your app using the `-logfile -` argument:
+
+```json
+{
+  "monitor": {
+    "apps": [
+      {
+        "name": "unity-app",
+        "script": "UnityPM2Test.exe",
+        "args": "-logfile -"
+      }
+    ]
+  }
+}
+```
+
+### Cinder
+
+- Cinder doesn't route logs directly to `std::cout` and `std::cerr` by default, so this has to be done manually. See [here](https://github.com/bluecadet/Cinder-BluecadetViews/blob/2333604abc44a719e18df67566135ea34d545085/src/bluecadet/core/BaseApp.cpp#L22-L39) for an example for how to create one, and [here](https://github.com/bluecadet/Cinder-BluecadetViews/blob/2333604abc44a719e18df67566135ea34d545085/src/bluecadet/core/BaseApp.cpp#L86) for how to add it.
+- If you use [Cinder-BluecadetViews](https://github.com/bluecadet/Cinder-BluecadetViews), all logs are routed to `stdout`/`stderr` via the `logToStdOut` setting. This is set to `true` by default and can otherwise be configured in `settings.json` or via cli flag: `my-app.exe console=false logToStdOut=true`
+
 ## Adanced Configuration
 
-{{>class-members name="AppLogOptions"}}
+See below for further settings that can be configured globally and on a per-app level.
 
-{{>class-members name="WindowsApiOptions"}}
+{{>class-members name="WindowsApiOptions"}}
+
+{{>class-members name="AppLogOptions"}}
diff --git a/packages/monitor/README.md b/packages/monitor/README.md
diff --git a/packages/monitor/lib/monitor-options.js b/packages/monitor/lib/monitor-options.js
diff --git a/packages/utils/lib/log-manager.js b/packages/utils/lib/log-manager.js
