Merge branch 'master' into add-context-functions

Author: blakeroberts-wk

.github/CODEOWNERS

@@ -2,4 +2,4 @@
 # This file controls who is tagged for review for any given pull request.
 
  # For anything not explicitly taken by someone else:
-* @Workiva/observability @evanweible-wf @dustinlessard-wf
+* @blakeroberts-wk @evanweible-wf

lib/src/api/common/semantic_attributes.dart

@@ -16,6 +16,10 @@ class SemanticAttributes {
   /// representation is to be determined and documented by each language SIG.
   static const String exceptionStacktrace = 'exception.stacktrace';
 
+  /// Set to true if the exception event is recorded at a point where it is
+  /// known that the exception is escaping the scope of the span.
+  static const String exceptionEscaped = 'exception.escaped';
+
   /// HTTP request method.
   static const String httpMethod = 'http.method';
 

lib/src/api/trace/nonrecording_span.dart

@@ -38,7 +38,10 @@ class NonRecordingSpan implements api.Span {
   api.SpanContext get spanContext => _spanContext;
 
   @override
-  void recordException(dynamic exception, {StackTrace? stackTrace}) {}
+  void recordException(dynamic exception,
+      {bool escaped = false,
+      StackTrace? stackTrace,
+      List<api.Attribute>? attributes}) {}
 
   @override
   void addEvent(String name,

lib/src/api/trace/span.dart

@@ -66,6 +66,7 @@ abstract class Span {
   /// Marks the end of this span's execution.
   void end({Int64 endTime});
 
-  /// Records a [api.SpanEvent] about the given exception.
-  void recordException(dynamic exception, {StackTrace stackTrace});
+  /// Record metadata about an exception occurring during this span.
+  void recordException(dynamic exception,
+      {bool escaped, StackTrace stackTrace, List<api.Attribute> attributes});
 }

lib/src/sdk/trace/span.dart

@@ -3,6 +3,7 @@
 
 import 'package:fixnum/fixnum.dart';
 import 'package:meta/meta.dart';
+import 'package:opentelemetry/api.dart';
 
 import '../../../api.dart' as api;
 import '../../../sdk.dart' as sdk;
@@ -138,16 +139,18 @@ class Span implements sdk.ReadWriteSpan {
 
   @override
   void recordException(dynamic exception,
-      {StackTrace stackTrace = StackTrace.empty}) {
-    // ignore: todo
-    // TODO: O11Y-1531: Consider integration of Events here.
-    setAttributes([
-      api.Attribute.fromString(api.SemanticAttributes.exceptionType,
+      {bool escaped = true,
+      StackTrace stackTrace = StackTrace.empty,
+      List<api.Attribute> attributes = const []}) {
+    addEvent('exception', attributes: [
+      Attribute.fromString(api.SemanticAttributes.exceptionType,
           exception.runtimeType.toString()),
-      api.Attribute.fromString(
+      Attribute.fromString(
           api.SemanticAttributes.exceptionMessage, exception.toString()),
-      api.Attribute.fromString(
+      Attribute.fromString(
           api.SemanticAttributes.exceptionStacktrace, stackTrace.toString()),
+      Attribute.fromBoolean(api.SemanticAttributes.exceptionEscaped, escaped),
+      ...attributes
     ]);
   }
 

test/integration/open_telemetry_test.dart

@@ -6,6 +6,7 @@ import 'dart:async';
 
 import 'package:opentelemetry/api.dart' as api;
 import 'package:opentelemetry/sdk.dart' as sdk;
+import 'package:opentelemetry/src/api/trace/span_event.dart';
 import 'package:opentelemetry/src/sdk/trace/span.dart';
 import 'package:opentelemetry/src/sdk/trace/tracer.dart';
 import 'package:test/test.dart';
@@ -74,10 +75,14 @@ void main() {
     expect(span.endTime, isNotNull);
     expect(span.status.code, equals(api.StatusCode.error));
     expect(span.status.description, equals('Exception: Oh noes!'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionType),
-        equals('_Exception'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionMessage),
-        equals('Exception: Oh noes!'));
+    expect(span.events, [
+      hasExceptionEvent({
+        api.SemanticAttributes.exceptionType: '_Exception',
+        api.SemanticAttributes.exceptionMessage: 'Exception: Oh noes!',
+        api.SemanticAttributes.exceptionStacktrace: anything,
+        api.SemanticAttributes.exceptionEscaped: true,
+      })
+    ]);
   });
 
   test('trace asynchronous execution', () async {
@@ -145,10 +150,14 @@ void main() {
     expect(span.endTime, isNotNull);
     expect(span.status.code, equals(api.StatusCode.error));
     expect(span.status.description, equals('Exception: Oh noes!'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionType),
-        equals('_Exception'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionMessage),
-        equals('Exception: Oh noes!'));
+    expect(span.events, [
+      hasExceptionEvent({
+        api.SemanticAttributes.exceptionType: '_Exception',
+        api.SemanticAttributes.exceptionMessage: 'Exception: Oh noes!',
+        api.SemanticAttributes.exceptionStacktrace: anything,
+        api.SemanticAttributes.exceptionEscaped: true,
+      })
+    ]);
   });
 
   test('trace asynchronous execution completes with error', () async {
@@ -173,9 +182,22 @@ void main() {
     expect(span.endTime, isNotNull);
     expect(span.status.code, equals(api.StatusCode.error));
     expect(span.status.description, equals('Exception: Oh noes!'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionType),
-        equals('_Exception'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionMessage),
-        equals('Exception: Oh noes!'));
+    expect(span.events, [
+      hasExceptionEvent({
+        api.SemanticAttributes.exceptionType: '_Exception',
+        api.SemanticAttributes.exceptionMessage: 'Exception: Oh noes!',
+        api.SemanticAttributes.exceptionStacktrace: anything,
+        api.SemanticAttributes.exceptionEscaped: true,
+      })
+    ]);
   });
 }
+
+Matcher hasExceptionEvent(Map<String, Object> attributes) =>
+    isA<SpanEvent>().having(
+        (e) => e.attributes,
+        'attributes',
+        isA<Iterable<api.Attribute>>().having(
+            (a) => a.map((e) => [e.key, e.value]),
+            'attributes',
+            containsAll(attributes.entries.map((e) => [e.key, e.value]))));

test/integration/sdk/span_test.dart

@@ -210,9 +210,22 @@ void main() {
       span.recordException(e, stackTrace: s);
     }
 
-    expect(span.attributes.get(api.SemanticAttributes.exceptionType),
-        equals('_Exception'));
-    expect(span.attributes.get(api.SemanticAttributes.exceptionMessage),
-        equals('Exception: Oh noes!'));
+    expect(span.events, [
+      hasExceptionEvent({
+        api.SemanticAttributes.exceptionType: '_Exception',
+        api.SemanticAttributes.exceptionMessage: 'Exception: Oh noes!',
+        api.SemanticAttributes.exceptionStacktrace: anything,
+        api.SemanticAttributes.exceptionEscaped: true,
+      })
+    ]);
   });
 }
+
+Matcher hasExceptionEvent(Map<String, Object> attributes) =>
+    isA<api.SpanEvent>().having(
+        (e) => e.attributes,
+        'attributes',
+        isA<Iterable<api.Attribute>>().having(
+            (a) => a.map((e) => [e.key, e.value]),
+            'attributes',
+            containsAll(attributes.entries.map((e) => [e.key, e.value]))));