feat(api): Integrate @opentelemetry/api-logs package into @opentelemetry/api as experimental

.gitignore

@@ -2,8 +2,8 @@
 
 version.ts
 
-# Logs
-logs
+# Logs in root
+/logs
 *.log
 npm-debug.log*
 yarn-debug.log*

api/CHANGELOG.md

@@ -9,6 +9,8 @@ All notable changes to this project will be documented in this file.
 
 ### :rocket: (Enhancement)
 
+* feat(api): Integrate @opentelemetry/api-logs package into @opentelemetry/api as experimental [#4862](https://github.com/open-telemetry/opentelemetry-js/pull/4862) @hectorhdzg
+
 ### :bug: (Bug Fix)
 
 ### :books: (Refine Doc)

api/src/experimental/logs/NoopLogger.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { Logger } from './types/Logger';
+import { LogRecord } from './types/LogRecord';
+
+export class NoopLogger implements Logger {
+  emit(_logRecord: LogRecord): void {}
+}
+
+export const NOOP_LOGGER = new NoopLogger();

api/src/experimental/logs/NoopLoggerProvider.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { LoggerProvider } from './types/LoggerProvider';
+import { Logger } from './types/Logger';
+import { LoggerOptions } from './types/LoggerOptions';
+import { NoopLogger } from './NoopLogger';
+
+export class NoopLoggerProvider implements LoggerProvider {
+  getLogger(
+    _name: string,
+    _version?: string | undefined,
+    _options?: LoggerOptions | undefined
+  ): Logger {
+    return new NoopLogger();
+  }
+}
+
+export const NOOP_LOGGER_PROVIDER = new NoopLoggerProvider();

api/src/experimental/logs/api/logs.ts

@@ -0,0 +1,77 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { LoggerProvider } from '../types/LoggerProvider';
+import { NOOP_LOGGER_PROVIDER } from '../NoopLoggerProvider';
+import { Logger } from '../types/Logger';
+import { LoggerOptions } from '../types/LoggerOptions';
+import {
+  getGlobal,
+  registerGlobal,
+  unregisterGlobal,
+} from '../../../internal/global-utils';
+import { DiagAPI } from '../../../api/diag';
+
+const API_NAME = 'logs';
+
+export class LogsAPI {
+  private static _instance?: LogsAPI;
+
+  private constructor() {}
+
+  public static getInstance(): LogsAPI {
+    if (!this._instance) {
+      this._instance = new LogsAPI();
+    }
+
+    return this._instance;
+  }
+
+  /**
+   * Set the current global logger provider.
+   * Returns true if the logger provider was successfully registered, else false.
+   */
+  public setGlobalLoggerProvider(provider: LoggerProvider): boolean {
+    return registerGlobal(API_NAME, provider, DiagAPI.instance());
+  }
+
+  /**
+   * Returns the global logger provider.
+   *
+   * @returns LoggerProvider
+   */
+  public getLoggerProvider(): LoggerProvider {
+    return getGlobal(API_NAME) || NOOP_LOGGER_PROVIDER;
+  }
+
+  /**
+   * Returns a logger from the global logger provider.
+   *
+   * @returns Logger
+   */
+  public getLogger(
+    name: string,
+    version?: string,
+    options?: LoggerOptions
+  ): Logger {
+    return this.getLoggerProvider().getLogger(name, version, options);
+  }
+
+  /** Remove the global logger provider */
+  public disable(): void {
+    unregisterGlobal(API_NAME, DiagAPI.instance());
+  }
+}

api/src/experimental/logs/index.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 * from './types/Logger';
+export * from './types/LoggerProvider';
+export * from './types/LogRecord';
+export * from './types/LoggerOptions';
+export * from './types/AnyValue';
+export * from './NoopLogger';
+export * from './NoopLoggerProvider';
+
+import { LogsAPI } from './api/logs';
+export { LogsAPI };
+export const logs = LogsAPI.getInstance();

api/src/experimental/logs/types/AnyValue.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { AttributeValue } from '../../../common/Attributes';
+
+/**
+ * AnyValueMap is a map from string to AnyValue (attribute value or a nested map)
+ */
+export interface AnyValueMap {
+  [attributeKey: string]: AnyValue | undefined;
+}
+
+/**
+ * AnyValue is a either an attribute value or a map of AnyValue(s)
+ */
+export type AnyValue = AttributeValue | AnyValueMap;

api/src/experimental/logs/types/LogRecord.ts

@@ -0,0 +1,87 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { Attributes } from '../../../common/Attributes';
+import { TimeInput } from '../../../common/Time';
+import { Context } from '../../../context/types';
+import { AnyValue } from './AnyValue';
+
+export type LogBody = AnyValue;
+
+export enum SeverityNumber {
+  UNSPECIFIED = 0,
+  TRACE = 1,
+  TRACE2 = 2,
+  TRACE3 = 3,
+  TRACE4 = 4,
+  DEBUG = 5,
+  DEBUG2 = 6,
+  DEBUG3 = 7,
+  DEBUG4 = 8,
+  INFO = 9,
+  INFO2 = 10,
+  INFO3 = 11,
+  INFO4 = 12,
+  WARN = 13,
+  WARN2 = 14,
+  WARN3 = 15,
+  WARN4 = 16,
+  ERROR = 17,
+  ERROR2 = 18,
+  ERROR3 = 19,
+  ERROR4 = 20,
+  FATAL = 21,
+  FATAL2 = 22,
+  FATAL3 = 23,
+  FATAL4 = 24,
+}
+
+export interface LogRecord {
+  /**
+   * The time when the log record occurred as UNIX Epoch time in nanoseconds.
+   */
+  timestamp?: TimeInput;
+
+  /**
+   * Time when the event was observed by the collection system.
+   */
+  observedTimestamp?: TimeInput;
+
+  /**
+   * Numerical value of the severity.
+   */
+  severityNumber?: SeverityNumber;
+
+  /**
+   * The severity text.
+   */
+  severityText?: string;
+
+  /**
+   * A value containing the body of the log record.
+   */
+  body?: LogBody;
+
+  /**
+   * Attributes that define the log record.
+   */
+  attributes?: Attributes;
+
+  /**
+   * The Context associated with the LogRecord.
+   */
+  context?: Context;
+}

api/src/experimental/logs/types/Logger.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 './LogRecord';
+
+export interface Logger {
+  /**
+   * Emit a log record. This method should only be used by log appenders.
+   *
+   * @param logRecord
+   */
+  emit(logRecord: LogRecord): void;
+}

api/src/experimental/logs/types/LoggerOptions.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { Attributes } from '../../../common/Attributes';
+
+export interface LoggerOptions {
+  /**
+   * The schemaUrl of the tracer or instrumentation library
+   * @default ''
+   */
+  schemaUrl?: string;
+
+  /**
+   * The instrumentation scope attributes to associate with emitted telemetry
+   */
+  scopeAttributes?: Attributes;
+
+  /**
+   * Specifies whether the Trace Context should automatically be passed on to the LogRecords emitted by the Logger.
+   * @default true
+   */
+  includeTraceContext?: boolean;
+}

api/src/experimental/logs/types/LoggerProvider.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed 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
+ *
+ *      https://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 { Logger } from './Logger';
+import { LoggerOptions } from './LoggerOptions';
+
+/**
+ * A registry for creating named {@link Logger}s.
+ */
+export interface LoggerProvider {
+  /**
+   * Returns a Logger, creating one if one with the given name, version, and
+   * schemaUrl pair is not already created.
+   *
+   * @param name The name of the logger or instrumentation library.
+   * @param version The version of the logger or instrumentation library.
+   * @param options The options of the logger or instrumentation library.
+   * @returns Logger A Logger with the given name and version
+   */
+  getLogger(name: string, version?: string, options?: LoggerOptions): Logger;
+}