feat(diag-logger): replace logger with diag logger

README.md

@@ -244,6 +244,156 @@ 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.
+
+#### New Usage patterns
+
+- **Global Diagnostic Logging with no passed logger**
+
+The new global [```api.diag```](https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-api/src/api/diag.ts#L32) not only provides the ability to set a global diagnostic logger ```setLogger()``` and logging level ```setLogLevel()```, it is also a ```DiagLogger``` implementation and can be used 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.
+
+- **Using and setting the global diagnostic logger**
+
+```javascript
+// Previously (Not supported)
+
+// Now
+import { diag } from "@opentelemetry/api";
+
+diag.debug("...");
+
+// Setting the default Global logger to use the Console
+import { diag, DiagConsoleLogger } from "@opentelemetry/api";
+diag.setLogger(new DiagConsoleLogger())
+
+// Setting the log level limit applied to the global logger
+import { diag, DiagLogLevel } from "@opentelemetry/api";
+diag.setLogLevel(DiagLogLevel.ERROR);
+```
+
+#### Direct update path for existing code
+
+Without refactoring your existing code to use ```api.diag``` (recommended path), below is how you would directly upgrade to the newer version so you can get compiling and running.
+
+- **api.Logger**
+
+The api.Logger has been renamed for clarity to highlight that this is for internal (OpenTelemetry and supporting components) diagnostic level logging and not for usage by a consuming application to send telemetry out of the executing environment.
+
+The new ```DiagLogger``` provides the same set of functions as the previous Logger interface plus an additional verbose level, so direct replacement of the Logger is a simple case of changing to the new (renamed) type which is also exported by api.
+
+```typescript
+// Previously
+import { Logger } from "@opentelemetry/api";
+
+// As above you should refactor any code like this to just use the api.diag global logger
+export function MyFunction(myLogger: Logger) {
+  myLogger.debug("...");
+  myLogger.info("...");
+  myLogger.warn("...");
+  myLogger.error("...");
+}
+
+// Now
+import { DiagLogger } from "@opentelemetry/api";
+export function MyFunction(myLogger: DiagLogger) {
+  myLogger.debug("...");
+  myLogger.info("...");
+  myLogger.warn("...");
+  myLogger.error("...");
+  myLogger.verbose("..");
+}
+
+// Recommended usage
+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("..");
+}
+
+```
+
+- **api.NoopLogger**
+
+To support minification the NoopLogger class has been removed in favor of a factory method and generally direct usage should no longer be required as components should use the new ```api.diag```.
+
+```typescript
+// Previous direct creation
+import { NoopLogger } from "@opentelemetry/api";
+let myLogger = new NoopLogger();
+
+// Now
+import { createNoopDiagLogger } from "@opentelemetry/api";
+let noopLogger = createNoopDiagLogger();
+
+// Recommended usage -- avoid and just use the global diag instance
+import { diag } from "@opentelemetry/api";
+diag.debug("...");
+
+```
+
+- **core.LogLevel**
+
+The core.LogLevel enumeration has been moved to the api package and renamed for clarity as with the ```api.DiagLogger``` to highlight its usage for diagnostic logging.
+
+Note: Numeric compatibility of each enum value (DEBUG, INFO, WARN, ERROR) has NOT preserved.
+
+```javascript
+// Previously
+import { LogLevel } from "@opentelemetry/core";
+
+let logLevel = LogLevel.DEBUG;
+LogLevel.ERROR === 0 // true
+LogLevel.WARN === 1 // true
+LogLevel.INFO === 2 // true
+LogLevel.DEBUG === 3 // true
+
+// Now
+import { DiagLogLevel } from "@opentelemetry/api";
+
+let logLevel = DiagLogLevel.DEBUG;
+DiagLogLevel.ERROR !== 0 // true
+DiagLogLevel.WARN !== 1 // true
+DiagLogLevel.INFO !== 2 // true
+DiagLogLevel.DEBUG !== 3 // true
+```
+
+Usage of the ```getEnv().OTEL_LOG_LEVEL``` now returns a ```api.DiagLogLevel```, the environment setting continues to support conversion from ```string``` case-insensitive values to the new Enum equivalent, but explicitly does not support initializing via a numeric value (or string version i.e. "30").
+
+- **core.ConsoleLogger**
+
+As with the ```core.LogLevel``` this has been moved to the ```api``` package and renamed to ```DiagConsoleLogger```.
+
+Note: The previous version of the ```ConsoleLogger``` supported a LogLevel "limit", this functionality has been extracted into a helper wrapper sink ```createLogLevelDiagLogger()``` and you should not need to use it directly, but it can be applied to any DiagLogger implementation.
+
+```javascript
+// Previously
+import { ConsoleLogger } from "@opentelemetry/core";
+let myLogger = new ConsoleLogger(LogLevel.ERROR);
+
+// Now
+import { DiagLogLevel, DiagConsoleLogger, createLogLevelDiagLogger } from "@opentelemetry/api";
+let myLogger = createLogLevelDiagLogger(DiagLogLevel.ERROR, new DiagConsoleLogger());
+
+// Recommended approach
+import { DiagLogLevel, DiagConsoleLogger, diag } from "@opentelemetry/api";
+diag.setLogger(new DiagConsoleLogger());
+diag.setLogLevel(DiagLogLevel.ERROR);
+```
+
 ### 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(null);
 
 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,12 @@
 "use strict";
 
-const { LogLevel } = require("@opentelemetry/core");
+const { DiagLogLevel } = require("@opentelemetry/api");
 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({ diagLogLevel: DiagLogLevel.ERROR });
 
 provider.addSpanProcessor(
   new SimpleSpanProcessor(

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

@@ -1,17 +1,17 @@
-import { LogLevel } from '@opentelemetry/core';
+import { DiagLogLevel } from '@opentelemetry/api';
 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,
+  diagLogLevel: DiagLogLevel.ERROR,
 });
- 
+
 provider.register();
- 
+
 provider.addSpanProcessor(
   new SimpleSpanProcessor(
     new ZipkinExporter({
@@ -24,5 +24,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

@@ -101,7 +101,7 @@ export class DiagAPI implements 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);
@@ -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;
 }