feat: Add support for capturing events with local scopes (#1248)

* wip: local scopes

* merge breadcrumbs

* add sentry_scope_set_trace

* add sentry_scope_set_fingerprints()

* check fingerprints value type

* document sentry_scope_set_fingerprints() expected type

* Revert sentry_scope_set_trace/transaction

> Transactions/spans do not make sense in this setup since they aren't
> cloned and cannot be retrieved to create children.

* sentry_malloc -> SENTRY_MAKE

* fix comparing null timestamps when merging breadcrumbs

* take ownership

* update example

* partial revert of unit test changes in a48fea

don't assume any specific order for breadcrumbs with missing breadcrumbs

* warn once if any breadcrumbs were missing timestamps

* error handling for sentry_value_append()

Author: jpnurmi

CHANGELOG.md

@@ -10,6 +10,7 @@
 **Features**:
 
 - Provide `before_send_transaction` callback. ([#1236](https://github.com/getsentry/sentry-native/pull/1236))
+- Add support for capturing events with local scopes. ([#1248](https://github.com/getsentry/sentry-native/pull/1248))
 
 **Fixes**:
 

CONTRIBUTING.md

@@ -184,6 +184,7 @@ The example currently supports the following commands:
 - `attach-view-hierarchy`: Adds a `view-hierarchy.json` attachment file, giving it the proper `attachment_type` and `content_type`.
  This file can be found in `./tests/fixtures/view-hierachy.json`.
 - `set-trace`: Sets the scope `propagation_context`'s trace data to the given `trace_id="aaaabbbbccccddddeeeeffff00001111"` and `parent_span_id=""f0f0f0f0f0f0f0f0"`.
+- `capture-with-scope`: Captures an event with a local scope.
 
 Only on Linux using crashpad:
 - `crashpad-wait-for-upload`: Couples application shutdown to complete the upload in the `crashpad_handler`.

examples/example.c

@@ -220,6 +220,30 @@ trigger_stack_overflow()
     trigger_stack_overflow();
 }
 
+static sentry_value_t
+create_debug_crumb(const char *message)
+{
+    sentry_value_t debug_crumb = sentry_value_new_breadcrumb("http", message);
+    sentry_value_set_by_key(
+        debug_crumb, "category", sentry_value_new_string("example!"));
+    sentry_value_set_by_key(
+        debug_crumb, "level", sentry_value_new_string("debug"));
+
+    // extend the `http` crumb with (optional) data properties as documented
+    // here:
+    // https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/#breadcrumb-types
+    sentry_value_t http_data = sentry_value_new_object();
+    sentry_value_set_by_key(http_data, "url",
+        sentry_value_new_string("https://example.com/api/1.0/users"));
+    sentry_value_set_by_key(
+        http_data, "method", sentry_value_new_string("GET"));
+    sentry_value_set_by_key(
+        http_data, "status_code", sentry_value_new_int32(200));
+    sentry_value_set_by_key(http_data, "reason", sentry_value_new_string("OK"));
+    sentry_value_set_by_key(debug_crumb, "data", http_data);
+    return debug_crumb;
+}
+
 int
 main(int argc, char **argv)
 {
@@ -359,27 +383,7 @@ main(int argc, char **argv)
             = sentry_value_new_breadcrumb(NULL, "default level is info");
         sentry_add_breadcrumb(default_crumb);
 
-        sentry_value_t debug_crumb
-            = sentry_value_new_breadcrumb("http", "debug crumb");
-        sentry_value_set_by_key(
-            debug_crumb, "category", sentry_value_new_string("example!"));
-        sentry_value_set_by_key(
-            debug_crumb, "level", sentry_value_new_string("debug"));
-
-        // extend the `http` crumb with (optional) data properties as documented
-        // here:
-        // https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/#breadcrumb-types
-        sentry_value_t http_data = sentry_value_new_object();
-        sentry_value_set_by_key(http_data, "url",
-            sentry_value_new_string("https://example.com/api/1.0/users"));
-        sentry_value_set_by_key(
-            http_data, "method", sentry_value_new_string("GET"));
-        sentry_value_set_by_key(
-            http_data, "status_code", sentry_value_new_int32(200));
-        sentry_value_set_by_key(
-            http_data, "reason", sentry_value_new_string("OK"));
-        sentry_value_set_by_key(debug_crumb, "data", http_data);
-
+        sentry_value_t debug_crumb = create_debug_crumb("debug crumb");
         sentry_add_breadcrumb(debug_crumb);
 
         sentry_value_t nl_crumb
@@ -407,6 +411,22 @@ main(int argc, char **argv)
         }
     }
 
+    if (has_arg(argc, argv, "capture-with-scope")) {
+        sentry_scope_t *scope = sentry_local_scope_new();
+
+        sentry_value_t event = sentry_value_new_message_event(
+            SENTRY_LEVEL_INFO, NULL, "Hello Scope!");
+
+        sentry_value_t default_crumb
+            = sentry_value_new_breadcrumb(NULL, "default level is info");
+        sentry_scope_add_breadcrumb(scope, default_crumb);
+
+        sentry_value_t debug_crumb = create_debug_crumb("scoped crumb");
+        sentry_scope_add_breadcrumb(scope, debug_crumb);
+
+        sentry_capture_event_with_scope(event, scope);
+    }
+
     if (has_arg(argc, argv, "capture-multiple")) {
         for (size_t i = 0; i < 10; i++) {
             char buffer[10];

include/sentry.h

@@ -1402,7 +1402,7 @@ SENTRY_API uint64_t sentry_options_get_shutdown_timeout(sentry_options_t *opts);
 SENTRY_API void sentry_options_set_backend(
     sentry_options_t *opts, sentry_backend_t *backend);
 
-/* -- Global APIs -- */
+/* -- Global/Scope APIs -- */
 
 /**
  * Initializes the Sentry SDK with the specified options.
@@ -1502,6 +1502,19 @@ SENTRY_API void sentry_user_consent_reset(void);
  */
 SENTRY_API sentry_user_consent_t sentry_user_consent_get(void);
 
+/**
+ * A sentry Scope.
+ *
+ * See https://develop.sentry.dev/sdk/telemetry/scopes/
+ */
+struct sentry_scope_s;
+typedef struct sentry_scope_s sentry_scope_t;
+
+/**
+ * Creates a local scope.
+ */
+SENTRY_API sentry_scope_t *sentry_local_scope_new(void);
+
 /**
  * Sends a sentry event.
  *
@@ -1511,6 +1524,14 @@ SENTRY_API sentry_user_consent_t sentry_user_consent_get(void);
  */
 SENTRY_API sentry_uuid_t sentry_capture_event(sentry_value_t event);
 
+/**
+ * Sends a sentry event with a local scope.
+ *
+ * Takes ownership of `scope`.
+ */
+SENTRY_API sentry_uuid_t sentry_capture_event_with_scope(
+    sentry_value_t event, sentry_scope_t *scope);
+
 /**
  * Allows capturing independently created minidumps.
  *
@@ -1555,11 +1576,15 @@ SENTRY_EXPERIMENTAL_API void sentry_handle_exception(
  * Adds the breadcrumb to be sent in case of an event.
  */
 SENTRY_API void sentry_add_breadcrumb(sentry_value_t breadcrumb);
+SENTRY_API void sentry_scope_add_breadcrumb(
+    sentry_scope_t *scope, sentry_value_t breadcrumb);
 
 /**
  * Sets the specified user.
  */
 SENTRY_API void sentry_set_user(sentry_value_t user);
+SENTRY_API void sentry_scope_set_user(
+    sentry_scope_t *scope, sentry_value_t user);
 
 /**
  * Removes a user.
@@ -1572,6 +1597,10 @@ SENTRY_API void sentry_remove_user(void);
 SENTRY_API void sentry_set_tag(const char *key, const char *value);
 SENTRY_API void sentry_set_tag_n(
     const char *key, size_t key_len, const char *value, size_t value_len);
+SENTRY_API void sentry_scope_set_tag(
+    sentry_scope_t *scope, const char *key, const char *value);
+SENTRY_API void sentry_scope_set_tag_n(sentry_scope_t *scope, const char *key,
+    size_t key_len, const char *value, size_t value_len);
 
 /**
  * Removes the tag with the specified key.
@@ -1585,6 +1614,10 @@ SENTRY_API void sentry_remove_tag_n(const char *key, size_t key_len);
 SENTRY_API void sentry_set_extra(const char *key, sentry_value_t value);
 SENTRY_API void sentry_set_extra_n(
     const char *key, size_t key_len, sentry_value_t value);
+SENTRY_API void sentry_scope_set_extra(
+    sentry_scope_t *scope, const char *key, sentry_value_t value);
+SENTRY_API void sentry_scope_set_extra_n(sentry_scope_t *scope, const char *key,
+    size_t key_len, sentry_value_t value);
 
 /**
  * Removes the extra with the specified key.
@@ -1598,6 +1631,10 @@ SENTRY_API void sentry_remove_extra_n(const char *key, size_t key_len);
 SENTRY_API void sentry_set_context(const char *key, sentry_value_t value);
 SENTRY_API void sentry_set_context_n(
     const char *key, size_t key_len, sentry_value_t value);
+SENTRY_API void sentry_scope_set_context(
+    sentry_scope_t *scope, const char *key, sentry_value_t value);
+SENTRY_API void sentry_scope_set_context_n(sentry_scope_t *scope,
+    const char *key, size_t key_len, sentry_value_t value);
 
 /**
  * Removes the context object with the specified key.
@@ -1614,6 +1651,18 @@ SENTRY_API void sentry_remove_context_n(const char *key, size_t key_len);
 SENTRY_API void sentry_set_fingerprint(const char *fingerprint, ...);
 SENTRY_API void sentry_set_fingerprint_n(
     const char *fingerprint, size_t fingerprint_len, ...);
+SENTRY_API void sentry_scope_set_fingerprint(
+    sentry_scope_t *scope, const char *fingerprint, ...);
+SENTRY_API void sentry_scope_set_fingerprint_n(sentry_scope_t *scope,
+    const char *fingerprint, size_t fingerprint_len, ...);
+
+/**
+ * Sets the event fingerprints.
+ *
+ * This accepts a list of fingerprints created with `sentry_value_new_list`.
+ */
+SENTRY_API void sentry_scope_set_fingerprints(
+    sentry_scope_t *scope, sentry_value_t fingerprints);
 
 /**
  * Removes the fingerprint.
@@ -1640,6 +1689,8 @@ SENTRY_API void sentry_set_transaction_n(
  * Sets the event level.
  */
 SENTRY_API void sentry_set_level(sentry_level_t level);
+SENTRY_API void sentry_scope_set_level(
+    sentry_scope_t *scope, sentry_level_t level);
 
 /**
  * Sets the maximum number of spans that can be attached to a

src/backends/sentry_backend_breakpad.cpp

@@ -143,7 +143,7 @@ breakpad_backend_callback(const google_breakpad::MinidumpDescriptor &descriptor,
 
         if (should_handle) {
             sentry_envelope_t *envelope = sentry__prepare_event(
-                options, event, nullptr, !options->on_crash_func);
+                options, event, nullptr, !options->on_crash_func, NULL);
             sentry_session_t *session = sentry__end_current_session_with_status(
                 SENTRY_SESSION_STATUS_CRASHED);
             sentry__envelope_add_session(envelope, session);

src/backends/sentry_backend_inproc.c

@@ -589,7 +589,7 @@ handle_ucontext(const sentry_ucontext_t *uctx)
 
         if (should_handle) {
             sentry_envelope_t *envelope = sentry__prepare_event(
-                options, event, NULL, !options->on_crash_func);
+                options, event, NULL, !options->on_crash_func, NULL);
             // TODO(tracing): Revisit when investigating transaction flushing
             //                during hard crashes.