move logging types to @kbn/logging

package.json

@@ -140,6 +140,7 @@
     "@kbn/config-schema": "1.0.0",
     "@kbn/i18n": "1.0.0",
     "@kbn/interpreter": "1.0.0",
+    "@kbn/logging": "1.0.0",
     "@kbn/pm": "1.0.0",
     "@kbn/telemetry-tools": "1.0.0",
     "@kbn/test-subj-selector": "0.2.1",

packages/kbn-logging/README.md

@@ -0,0 +1,61 @@
+# kbn-logging
+
+Base types for the kibana platform logging system.
+
+Note that this package currently only contains logging types. The only concrete implementation
+is still in `core`.
+
+- [Loggers, Appenders and Layouts](#loggers-appenders-and-layouts)
+- [Logger hierarchy](#logger-hierarchy)
+- [Log level](#log-level)
+- [Layouts](#layouts)
+
+The way logging works in Kibana is inspired by `log4j 2` logging framework used by [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html#logging).
+The main idea is to have consistent logging behaviour (configuration, log format etc.) across the entire Elastic Stack 
+where possible.
+
+## Loggers, Appenders and Layouts
+
+Kibana logging system has three main components: _loggers_, _appenders_ and _layouts_. These components allow us to log
+messages according to message type and level, and to control how these messages are formatted and where the final logs
+will be displayed or stored.
+
+__Loggers__ define what logging settings should be applied at the particular context.
+
+__Appenders__ define where log messages are displayed (eg. stdout or console) and stored (eg. file on the disk).
+
+__Layouts__ define how log messages are formatted and what type of information they include.
+
+
+## Logger hierarchy
+
+Every logger has its unique name or context that follows hierarchical naming rule. The logger is considered to be an 
+ancestor of another logger if its name followed by a `.` is a prefix of the descendant logger name. For example logger
+with `a.b` context is an ancestor of logger with `a.b.c` context. All top-level loggers are descendants of special
+logger with `root` context that resides at the top of the logger hierarchy. This logger always exists and 
+fully configured.
+
+Developer can configure _log level_ and _appenders_ that should be used within particular context. If logger configuration
+specifies only _log level_ then _appenders_ configuration will be inherited from the ancestor logger. 
+
+__Note:__ in the current implementation log messages are only forwarded to appenders configured for a particular logger 
+context or to appenders of the closest ancestor if current logger doesn't have any appenders configured. That means that
+we __don't support__ so called _appender additivity_ when log messages are forwarded to _every_ distinct appender within
+ancestor chain including `root`.
+
+## Log level
+
+Currently we support the following log levels: _all_, _fatal_, _error_, _warn_, _info_, _debug_, _trace_, _off_.
+Levels are ordered, so _all_ > _fatal_ > _error_ > _warn_ > _info_ > _debug_ > _trace_ > _off_.
+A log record is being logged by the logger if its level is higher than or equal to the level of its logger. Otherwise, 
+the log record is ignored.
+
+The _all_ and _off_ levels can be used only in configuration and are just handy shortcuts that allow developer to log every
+log record or disable logging entirely for the specific context.
+
+## Layouts
+
+Every appender should know exactly how to format log messages before they are written to the console or file on the disk.
+This behaviour is controlled by the layouts and configured through `appender.layout` configuration property for every 
+custom appender (see examples in [Configuration](#configuration)). Currently we don't define any default layout for the
+custom appenders, so one should always make the choice explicitly.

packages/kbn-logging/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@kbn/logging",
+  "version": "1.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "main": "./target/index.js",
+  "scripts": {
+    "build": "tsc",
+    "kbn:bootstrap": "yarn build",
+    "kbn:watch": "yarn build --watch"
+  },
+  "dependencies": {
+    "rxjs": "^6.5.5",
+    "@kbn/config-schema": "1.0.0",
+    "moment-timezone": "^0.5.27"
+  },
+  "devDependencies": {
+    "typescript": "4.0.2"
+  }
+}

packages/kbn-logging/src/appenders.ts

@@ -0,0 +1,39 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { LogRecord } from './log_record';
+
+/**
+ * Entity that can append `LogRecord` instances to file, stdout, memory or whatever
+ * is implemented internally. It's supposed to be used by `Logger`.
+ * @internal
+ */
+export interface Appender {
+  append(record: LogRecord): void;
+}
+
+/**
+ * This interface should be additionally implemented by the `Appender`'s if they are supposed
+ * to be properly disposed. It's intentionally separated from `Appender` interface so that `Logger`
+ * that interacts with `Appender` doesn't have control over appender lifetime.
+ * @internal
+ */
+export interface DisposableAppender extends Appender {
+  dispose: () => void;
+}

packages/kbn-logging/src/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export { LogLevel, LogLevelId } from './log_level';
+export { LogRecord } from './log_record';
+export { Logger, LogMeta } from './logger';
+export { LoggerFactory } from './logger_factory';
+export { Layout } from './layout';
+export { Appender, DisposableAppender } from './appenders';

packages/kbn-logging/src/layout.ts

@@ -0,0 +1,28 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { LogRecord } from './log_record';
+
+/**
+ * Entity that can format `LogRecord` instance into a string.
+ * @internal
+ */
+export interface Layout {
+  format(record: LogRecord): string;
+}

src/core/server/logging/log_level.ts → packages/kbn-logging/src/log_level.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-import { assertNever } from '../../utils';
+import { assertNever } from './utils';
 
 /**
  * Possible log level string values.

packages/kbn-logging/src/logger.ts

@@ -0,0 +1,96 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { LogRecord } from './log_record';
+
+/**
+ * Contextual metadata
+ *
+ * @public
+ */
+export interface LogMeta {
+  [key: string]: any;
+}
+
+/**
+ * Logger exposes all the necessary methods to log any type of information and
+ * this is the interface used by the logging consumers including plugins.
+ *
+ * @public
+ */
+export interface Logger {
+  /**
+   * Log messages at the most detailed log level
+   *
+   * @param message - The log message
+   * @param meta -
+   */
+  trace(message: string, meta?: LogMeta): void;
+
+  /**
+   * Log messages useful for debugging and interactive investigation
+   * @param message - The log message
+   * @param meta -
+   */
+  debug(message: string, meta?: LogMeta): void;
+
+  /**
+   * Logs messages related to general application flow
+   * @param message - The log message
+   * @param meta -
+   */
+  info(message: string, meta?: LogMeta): void;
+
+  /**
+   * Logs abnormal or unexpected errors or messages
+   * @param errorOrMessage - An Error object or message string to log
+   * @param meta -
+   */
+  warn(errorOrMessage: string | Error, meta?: LogMeta): void;
+
+  /**
+   * Logs abnormal or unexpected errors or messages that caused a failure in the application flow
+   *
+   * @param errorOrMessage - An Error object or message string to log
+   * @param meta -
+   */
+  error(errorOrMessage: string | Error, meta?: LogMeta): void;
+
+  /**
+   * Logs abnormal or unexpected errors or messages that caused an unrecoverable failure
+   *
+   * @param errorOrMessage - An Error object or message string to log
+   * @param meta -
+   */
+  fatal(errorOrMessage: string | Error, meta?: LogMeta): void;
+
+  /** @internal */
+  log(record: LogRecord): void;
+
+  /**
+   * Returns a new {@link Logger} instance extending the current logger context.
+   *
+   * @example
+   * ```typescript
+   * const logger = loggerFactory.get('plugin', 'service'); // 'plugin.service' context
+   * const subLogger = logger.get('feature'); // 'plugin.service.feature' context
+   * ```
+   */
+  get(...childContextPaths: string[]): Logger;
+}

packages/kbn-logging/src/utils/assert_never.ts

@@ -0,0 +1,28 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Can be used in switch statements to ensure we perform exhaustive checks, see
+ * https://www.typescriptlang.org/docs/handbook/advanced-types.html#exhaustiveness-checking
+ *
+ * @public
+ */
+export function assertNever(x: never): never {
+  throw new Error(`Unexpected object: ${x}`);
+}

packages/kbn-logging/src/utils/index.ts

@@ -0,0 +1,20 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export { assertNever } from './assert_never';

packages/kbn-logging/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "target",
+    "stripInternal": false,
+    "declaration": true,
+    "declarationMap": true,
+    "types": [
+      "jest",
+      "node"
+    ]
+  },
+  "include": [
+    "./src/**/*.ts"
+  ]
+}

src/core/server/legacy/logging/appenders/legacy_appender.test.ts

@@ -19,8 +19,7 @@
 
 jest.mock('../legacy_logging_server');
 
-import { LogLevel } from '../../../logging/log_level';
-import { LogRecord } from '../../../logging/log_record';
+import { LogRecord, LogLevel } from '../../../logging';
 import { LegacyLoggingServer } from '../legacy_logging_server';
 import { LegacyAppender } from './legacy_appender';
 

src/core/server/legacy/logging/appenders/legacy_appender.ts

@@ -18,8 +18,7 @@
  */
 
 import { schema } from '@kbn/config-schema';
-import { DisposableAppender } from '../../../logging/appenders/appenders';
-import { LogRecord } from '../../../logging/log_record';
+import { DisposableAppender, LogRecord } from '../../../logging';
 import { LegacyLoggingServer } from '../legacy_logging_server';
 import { LegacyVars } from '../../types';
 

src/core/server/legacy/logging/legacy_logging_server.test.ts

@@ -20,7 +20,7 @@
 jest.mock('../../../../legacy/server/config');
 jest.mock('../../../../legacy/server/logging');
 
-import { LogLevel } from '../../logging/log_level';
+import { LogLevel } from '../../logging';
 import { LegacyLoggingServer } from './legacy_logging_server';
 
 test('correctly forwards log records.', () => {

src/core/server/legacy/logging/legacy_logging_server.ts

@@ -23,8 +23,7 @@ import Podium from 'podium';
 import { Config } from '../../../../legacy/server/config';
 // @ts-expect-error: implicit any for JS file
 import { setupLogging } from '../../../../legacy/server/logging';
-import { LogLevel } from '../../logging/log_level';
-import { LogRecord } from '../../logging/log_record';
+import { LogLevel, LogRecord } from '../../logging';
 import { LegacyVars } from '../../types';
 
 export const metadataSymbol = Symbol('log message with metadata');