logs take ownership of custom attributes

Author: JoshuaMoelans

examples/example.c

@@ -524,20 +524,23 @@ main(int argc, char **argv)
             sentry_value_new_object(), "no");
         // TODO add test that shows we still keep default attributes if
         //  passed-in value is accidentally not an object
+        //  + (not) overwriting default attributes
         sentry_log_warn("logging with %s custom attributes",
             sentry_value_new_null(), "new_null as");
         sentry_value_t param_attributes = sentry_value_new_object();
         sentry_value_t param_attr = sentry_value_new_attribute(
             sentry_value_new_string("parameter"), NULL);
         sentry_value_set_by_key(
             param_attributes, "message.parameter.0", param_attr);
+        // incref because we want to use it twice
+        sentry_value_incref(param_attributes);
+        sentry_value_incref(param_attributes);
         sentry_log_fatal(
             "logging with a custom parameter attributes", param_attributes);
-        sentry_value_t param_attributes_2 = sentry_value_new_object();
-        sentry_value_t param_attr_2 = sentry_value_new_attribute(
-            sentry_value_new_string("parameter"), NULL);
         sentry_log_fatal("logging with a custom parameter %s attributes",
             param_attributes, "and format-string");
+        sentry_log_warn("logging once again with a custom parameter attribute",
+            param_attributes);
     }
 
     if (has_arg(argc, argv, "attachment")) {

include/sentry.h

@@ -2006,17 +2006,27 @@ SENTRY_EXPERIMENTAL_API int sentry_options_get_propagate_traceparent(
 
 /**
  * Enables or disables the structured logging feature.
- * When disabled, all calls to sentry_logger_X() are no-ops.
+ * When disabled, all calls to `sentry_log_X()` are no-ops.
  */
 SENTRY_EXPERIMENTAL_API void sentry_options_set_enable_logs(
     sentry_options_t *opts, int enable_logs);
 SENTRY_EXPERIMENTAL_API int sentry_options_get_enable_logs(
     const sentry_options_t *opts);
 
+/**
+ * Enables or disables custom attributes parsing for structured logging.
+ *
+ * When enabled, all `sentry_log_X()` functions expect a `sentry_value_t` object
+ * as the first variadic argument for custom log attributes. Remaining
+ * arguments are used for format string substitution.
+ *
+ * Disabled by default.
+ */
 SENTRY_EXPERIMENTAL_API void sentry_options_set_logs_with_attributes(
     sentry_options_t *opts, int logs_with_attributes);
 SENTRY_EXPERIMENTAL_API int sentry_options_get_logs_with_attributes(
     const sentry_options_t *opts);
+
 /**
  * The potential returns of calling any of the sentry_log_X functions
  * - Success means a log was enqueued
@@ -2054,6 +2064,15 @@ typedef enum {
  *
  * Flags, width, and precision specifiers are parsed but currently ignored for
  * parameter extraction purposes.
+ *
+ * When the option `logs_with_attributes` is enabled, the first varg is parsed
+ * as a `sentry_value_t` object containing the initial attributes for the log.
+ * You can pass `sentry_value_new_null()` to logs which don't need attributes.
+ * TODO Default log attributes will (currently) overwrite passed-in attributes.
+ * Ownership of the attributes is transferred to the log function.
+ *
+ * To re-use the same attributes, call `sentry_value_incref` on it
+ * before passing the attributes to the log function.
  */
 SENTRY_EXPERIMENTAL_API log_return_value_t sentry_log_trace(
     const char *message, ...);

src/sentry_logs.c

@@ -687,11 +687,14 @@ construct_log(sentry_level_t level, const char *message, va_list args)
             va_end(args_copy);
             if (sentry_value_get_type(custom_attributes)
                 == SENTRY_VALUE_TYPE_OBJECT) {
-                SENTRY_DEBUG("Discarded custom attributes on log: non-object "
-                             "sentry_value_t passed in");
+                // TODO do we want to inspect that the object is attribute-like?
                 sentry_value_decref(attributes);
                 attributes = sentry__value_clone(custom_attributes);
+            } else {
+                SENTRY_DEBUG("Discarded custom attributes on log: non-object "
+                             "sentry_value_t passed in");
             }
+            sentry_value_decref(custom_attributes);
         }
 
         // Format the message with remaining args (or all args if not using