feat: adding possibility of recording exception (open-telemetry#1372)

* feat: adding possibility of recording exception

* chore: copy

* chore: copy

* chore: linting

* chore: reviews

* chore: updating exception type

* chore: reviews

* chore: reviews

* chore: fixing test when waiting for files to be loaded

Author: obecny

api/src/common/Exception.ts

@@ -0,0 +1,47 @@
+/*
+ * 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.
+ */
+
+interface ExceptionWithCode {
+  code: string;
+  name?: string;
+  message?: string;
+  stack?: string;
+}
+
+interface ExceptionWithMessage {
+  code?: string;
+  message: string;
+  name?: string;
+  stack?: string;
+}
+
+interface ExceptionWithName {
+  code?: string;
+  message?: string;
+  name: string;
+  stack?: string;
+}
+
+/**
+ * Defines Exception.
+ *
+ * string or an object with one of (message or name or code) and optional stack
+ */
+export type Exception =
+  | ExceptionWithCode
+  | ExceptionWithMessage
+  | ExceptionWithName
+  | string;

api/src/index.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+export * from './common/Exception';
 export * from './common/Logger';
 export * from './common/Time';
 export * from './context/propagation/getter';

api/src/trace/NoopSpan.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { Exception } from '../common/Exception';
 import { TimeInput } from '../common/Time';
 import { Attributes } from './attributes';
 import { Span } from './span';
@@ -76,6 +77,9 @@ export class NoopSpan implements Span {
   isRecording(): boolean {
     return false;
   }
+
+  // By default does nothing
+  recordException(exception: Exception, time?: TimeInput): void {}
 }
 
 export const NOOP_SPAN = new NoopSpan();

api/src/trace/span.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { Exception } from '../common/Exception';
 import { Attributes } from './attributes';
 import { SpanContext } from './span_context';
 import { Status } from './status';
@@ -114,4 +115,12 @@ export interface Span {
    *     with the `AddEvent` operation and attributes using `setAttributes`.
    */
   isRecording(): boolean;
+
+  /**
+   * Sets exception as a span event
+   * @param exception the exception the only accepted values are string or Error
+   * @param [time] the time to set as Span's event time. If not provided,
+   *     use the current time.
+   */
+  recordException(exception: Exception, time?: TimeInput): void;
 }