feat(diag-logger): part 2 - breaking changes - remove api.Logger, api… (

#1925)

README.md

@@ -244,6 +244,53 @@ To request automatic tracing support for a module not on this list, please [file
 
 ## Upgrade guidelines
 
+### 0.17.0 to ???
+
+[PR-1880](https://github.com/open-telemetry/opentelemetry-js/pull/1880) feat(diag-logger): introduce a new global level api.diag for internal diagnostic logging
+
+[PR-1925](https://github.com/open-telemetry/opentelemetry-js/pull/1925) feat(diag-logger): part 2 - breaking changes - remove api.Logger, api.NoopLogger, core.LogLevel, core.ConsoleLogger
+
+- These PR's remove the previous ```Logger``` and ```LogLevel``` implementations and change the way you should use the replacement ```DiagLogger``` and ```DiagLogLevel```, below are simple examples of how to change your existing usages.
+
+#### Setting the global diagnostic logger
+
+The new global [```api.diag```](https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-api/src/api/diag.ts#L32) provides the ability to set the global diagnostic logger ```setLogger()``` and logging level ```setLogLevel()```, it is also a ```DiagLogger``` implementation and should be directly to log diagnostic messages.
+
+All included logger references have been removed in preference to using the global ```api.diag``` directly, so you no longer need to pass around the logger instance via function parameters or included as part of the configuration for a component.
+
+```javascript
+// Setting the default Global logger to use the Console
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+diag.setLogger(new DiagConsoleLogger())
+
+// And optionally change the logging level (Defaults to INFO)
+diag.setLogLevel(DiagLogLevel.ERROR);
+```
+
+#### Using the logger anywhere in the code
+
+```typescript
+import { diag } from "@opentelemetry/api";
+
+// Remove or make optional the parameter and don't use it.
+export function MyFunction() {
+  diag.debug("...");
+  diag.info("...");
+  diag.warn("...");
+  diag.error("...");
+  diag.verbose("..");
+}
+
+```
+
+#### Setting the logger back to a noop
+
+```typescript
+import { diag } from "@opentelemetry/api";
+diag.setLogger();
+
+```
+
 ### 0.16.0 to 0.17.0
 
 [PR-1855](https://github.com/open-telemetry/opentelemetry-js/pull/1855) Use instrumentation loader to load plugins and instrumentations

benchmark/tracer.js

@@ -4,7 +4,8 @@ const benchmark = require('./benchmark');
 const opentelemetry = require('../packages/opentelemetry-api');
 const { BasicTracerProvider, BatchSpanProcessor, InMemorySpanExporter, SimpleSpanProcessor } = require('../packages/opentelemetry-tracing');
 
-const diagLogger = opentelemetry.createNoopDiagLogger();
+// Clear any previous global logger
+opentelemetry.diag.setLogger();
 
 const setups = [
   {
@@ -13,7 +14,7 @@ const setups = [
   },
   {
     name: 'BasicTracerProvider',
-    provider: new BasicTracerProvider({ logger: diagLogger })
+    provider: new BasicTracerProvider()
   },
   {
     name: 'BasicTracerProvider with SimpleSpanProcessor',
@@ -63,7 +64,7 @@ for (const setup of setups) {
   suite.run({ async: false });
 }
 function getProvider(processor) {
-  const provider = new BasicTracerProvider({ logger: diagLogger });
+  const provider = new BasicTracerProvider();
   provider.addSpanProcessor(processor);
   return provider;
 }

examples/collector-exporter-node/metrics.js

@@ -6,13 +6,13 @@ const { CollectorMetricExporter } = require('@opentelemetry/exporter-collector')
 // const { CollectorMetricExporter } = require('@opentelemetry/exporter-collector-proto');
 const { MeterProvider } = require('@opentelemetry/metrics');
 
+// Optional and only needed to see the internal diagnostic logging (during development)
 diag.setLogger(new DiagConsoleLogger());
 diag.setLogLevel(DiagLogLevel.DEBUG);
 
 const metricExporter = new CollectorMetricExporter({
   serviceName: 'basic-metric-service',
   // url: 'http://localhost:55681/v1/metrics',
-  logger: diag,
 });
 
 const meter = new MeterProvider({

examples/metrics/metrics/observer.js

@@ -1,9 +1,13 @@
 'use strict';
 
 const { MeterProvider } = require('@opentelemetry/metrics');
-const { DiagConsoleLogger, DiagLogLevel, diagLogLevelFilter } = require('@opentelemetry/api');
+const { DiagConsoleLogger, DiagLogLevel, diag } = require('@opentelemetry/api');
 const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
 
+// Optional and only needed to see the internal diagnostic logging (during development)
+diag.setLogger(new DiagConsoleLogger());
+diag.setLogLevel(DiagLogLevel.DEBUG);
+
 const exporter = new PrometheusExporter(
   {
     startServer: true,
@@ -61,7 +65,6 @@ meter.createBatchObserver((observerBatchResult) => {
     });
   }, {
     maxTimeoutUpdateMS: 500,
-    logger: diagLogLevelFilter(DiagLogLevel.DEBUG, new DiagConsoleLogger())
   },
 );
 

examples/tracer-web/examples/metrics/index.js

@@ -1,12 +1,15 @@
 'use strict';
 
-const { DiagConsoleLogger, DiagLogLevel, diagLogLevelFilter } = require('@opentelemetry/api');
+const { DiagConsoleLogger, DiagLogLevel, diag } = require('@opentelemetry/api');
 const { CollectorMetricExporter } = require('@opentelemetry/exporter-collector');
 const { MeterProvider } = require('@opentelemetry/metrics');
 
+// Optional and only needed to see the internal diagnostic logging (during development)
+diag.setLogger(new DiagConsoleLogger());
+diag.setLogLevel(DiagLogLevel.DEBUG);
+
 const metricExporter = new CollectorMetricExporter({
   serviceName: 'basic-metric-service',
-  logger: diagLogLevelFilter(DiagLogLevel.DEBUG, new DiagConsoleLogger()),
 });
 
 let interval;

getting-started/traced-example/tracing.js

@@ -1,12 +1,11 @@
 "use strict";
 
-const { LogLevel } = require("@opentelemetry/core");
 const { NodeTracerProvider } = require("@opentelemetry/node");
 const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
 const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin");
 const { registerInstrumentations } = require('@opentelemetry/instrumentation');
 
-const provider = new NodeTracerProvider({ logLevel: LogLevel.ERROR });
+const provider = new NodeTracerProvider();
 
 provider.addSpanProcessor(
   new SimpleSpanProcessor(

getting-started/ts-example/traced-example/tracing.ts

@@ -1,17 +1,14 @@
-import { LogLevel } from '@opentelemetry/core';
 import { NodeTracerProvider } from '@opentelemetry/node';
- 
+
 import { SimpleSpanProcessor } from '@opentelemetry/tracing';
 import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';
 // For Jaeger, use the following line instead:
 // import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
-
-const provider: NodeTracerProvider = new NodeTracerProvider({
-  logLevel: LogLevel.ERROR,
-});
-
+
+const provider: NodeTracerProvider = new NodeTracerProvider();
+
 provider.register();
- 
+
 provider.addSpanProcessor(
   new SimpleSpanProcessor(
     new ZipkinExporter({
@@ -24,5 +21,5 @@ provider.addSpanProcessor(
     }),
   ),
 );
- 
+
 console.log('tracing initialized');

packages/opentelemetry-api-metrics/src/types/Metric.ts

@@ -19,7 +19,6 @@ import {
   BoundCounter,
   BoundValueRecorder,
 } from './BoundInstrument';
-import { Logger } from '@opentelemetry/api';
 
 /**
  * Options needed for metric creation
@@ -55,11 +54,6 @@ export interface MetricOptions {
    */
   valueType?: ValueType;
 
-  /**
-   * User provided logger.
-   */
-  logger?: Logger;
-
   /**
    * Boundaries optional for histogram
    */
@@ -71,11 +65,6 @@ export interface BatchObserverOptions {
    * Indicates how long the batch metric should wait to update before cancel
    */
   maxTimeoutUpdateMS?: number;
-
-  /**
-   * User provided logger.
-   */
-  logger?: Logger;
 }
 
 /** The Type of value. It describes how the data is reported. */

packages/opentelemetry-api/src/api/diag.ts

@@ -99,9 +99,9 @@ export class DiagAPI implements DiagLogger {
       return _logger;
     };
 
-    self.setLogger = (logger: DiagLogger): DiagLogger => {
+    self.setLogger = (logger?: DiagLogger): DiagLogger => {
       const prevLogger = _logger;
-      if (prevLogger !== logger && logger !== self) {
+      if (!logger || logger !== self) {
         // Simple special case to avoid any possible infinite recursion on the logging functions
         _logger = logger || createNoopDiagLogger();
         _filteredLogger = createLogLevelDiagLogger(_logLevel, _logger);
@@ -133,10 +133,10 @@ export class DiagAPI implements DiagLogger {
 
   /**
    * Set the DiagLogger instance
-   * @param logger - The DiagLogger instance to set as the default logger
+   * @param logger - [Optional] The DiagLogger instance to set as the default logger, if not provided it will set it back as a noop
    * @returns The previously registered DiagLogger
    */
-  public setLogger!: (logger: DiagLogger) => DiagLogger;
+  public setLogger!: (logger?: DiagLogger) => DiagLogger;
 
   /** Set the default maximum diagnostic logging level */
   public setLogLevel!: (maxLogLevel: DiagLogLevel) => void;
@@ -146,8 +146,5 @@ export class DiagAPI implements DiagLogger {
   public debug!: DiagLogFunction;
   public info!: DiagLogFunction;
   public warn!: DiagLogFunction;
-  public startupInfo!: DiagLogFunction;
   public error!: DiagLogFunction;
-  public critical!: DiagLogFunction;
-  public terminal!: DiagLogFunction;
 }

packages/opentelemetry-api/src/diag/consoleLogger.ts

@@ -17,20 +17,17 @@
 import { DiagLogger, DiagLogFunction } from './logger';
 
 const consoleMap: { n: keyof DiagLogger; c: keyof Console }[] = [
-  { n: 'terminal', c: 'error' },
-  { n: 'critical', c: 'error' },
   { n: 'error', c: 'error' },
   { n: 'warn', c: 'warn' },
   { n: 'info', c: 'info' },
   { n: 'debug', c: 'debug' },
   { n: 'verbose', c: 'trace' },
-  { n: 'startupInfo', c: 'info' },
 ];
 
 /**
  * A simple Immutable Console based diagnostic logger which will output any messages to the Console.
  * If you want to limit the amount of logging to a specific level or lower use the
- * {@link diagLogLevelFilter}
+ * {@link createLogLevelDiagLogger}
  */
 export class DiagConsoleLogger implements DiagLogger {
   constructor() {
@@ -58,28 +55,9 @@ export class DiagConsoleLogger implements DiagLogger {
     }
   }
 
-  /**
-   * Log a terminal situation that would cause the API to completely fail to initialize,
-   * if this type of message is logged functionality of the API is not expected to be functional.
-   */
-  public terminal!: DiagLogFunction;
-
-  /**
-   * Log a critical error that NEEDS to be addressed, functionality of the component that emits
-   * this log detail may non-functional. While the overall API may be.
-   */
-  public critical!: DiagLogFunction;
-
   /** Log an error scenario that was not expected and caused the requested operation to fail. */
   public error!: DiagLogFunction;
 
-  /**
-   * Logs a general informational message that is used for logging component startup and version
-   * information without causing additional general informational messages when the logging level
-   * is set to DiagLogLevel.WARN or lower.
-   */
-  public startupInfo!: DiagLogFunction;
-
   /**
    * Log a warning scenario to inform the developer of an issues that should be investigated.
    * The requested operation may or may not have succeeded or completed.