feat(native): add custom log attributes API (#15491)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

Vercel previews
- [options
page](https://sentry-docs-git-joshua-featnativelogscustomattributes.sentry.dev/platforms/native/configuration/options/#logs_with_attributes)
- [logs
page](https://sentry-docs-git-joshua-featnativelogscustomattributes.sentry.dev/platforms/native/logs/#additional-attributes)
- [enriching events >
attributes](https://sentry-docs-git-joshua-featnativelogscustomattributes.sentry.dev/platforms/native/enriching-events/attributes/)

## DESCRIBE YOUR PR
Documents the feature added in
getsentry/sentry-native#1435 (comment)

### ToDo
- [x] add general `attributes` overview explaining how to use the API

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [x] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

Author: JoshuaMoelans

docs/platforms/native/common/configuration/options.mdx

@@ -123,3 +123,9 @@ This option enables the [logging integration](/platforms/native/logs), which all
 This function is called with an SDK-specific log object, and can return a modified log object, or `sentry_value_new_null()` to drop the log.
 
 </SdkOption>
+
+<SdkOption name="logs_with_attributes" type="bool" defaultValue="false">
+
+Whether calls to `sentry_log_X()` expect an attributes object as the second argument, allowing users to pass in custom log attributes. An example can be found on the [Logs page](/platforms/native/logs/#additional-attributes).
+
+</SdkOption>

docs/platforms/native/common/enriching-events/attributes/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Attributes
+description: "Learn how to construct custom attributes to enrich logs."
+---
+
+Attributes are a specific kind of `sentry_value_t` object which contains items with a `value`, `type` and optional `unit` field. The type is inferred from the given `sentry_value_t` value, which can be `bool`, `int32`, `int64`, `uint64`, `double` or `string`.
+
+```c
+sentry_value_t attributes = sentry_value_new_object();
+sentry_value_t attr = sentry_value_new_attribute(sentry_value_new_string("my_attribute"), NULL);
+sentry_value_t attr_2 = sentry_value_new_attribute(sentry_value_new_int64(INT64_MAX), "fermions");
+sentry_value_t attr_3 = sentry_value_new_attribute(sentry_value_new_int64(INT64_MIN), "bosons");
+sentry_value_set_by_key(attributes, "my.custom.attribute", attr);
+sentry_value_set_by_key(attributes, "number.first", attr_2);
+sentry_value_set_by_key(attributes, "number.second", attr_3);
+```
+
+Attributes can currently be used to enrich the following:
+- [Structured logs](/platforms/native/logs/#additional-attributes)

platform-includes/logs/usage/native.mdx

@@ -2,11 +2,47 @@ Once the feature is enabled on the SDK and the SDK is initialized, you can send
 
 The API exposes six methods that you can use to log messages at different log levels: `trace`, `debug`, `info`, `warn`, `error`, and `fatal`.
 
+```c
+sentry_log_info("A simple log message");
+sentry_log_error("A %s log message", "formatted");
+```
+
+### Additional attributes
+
+In case you want to provide additional attributes directly to the logging functions, you must enable the `logs_with_attributes` option. Any `sentry_log_X()` calls will expect a `sentry_value_t` object of attributes as the first `varg` after the log message.
+
 These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.
 
 ```c
-import io.sentry.Sentry;
+sentry_options_set_logs_with_attributes(options, true);
 
-sentry_log_info("A simple log message");
-sentry_log_error("A %s log message", "formatted");
+sentry_value_t attributes = sentry_value_new_object();
+sentry_value_t attr = sentry_value_new_attribute(sentry_value_new_string("my_attribute"), NULL);
+sentry_value_t attr_2 = sentry_value_new_attribute(sentry_value_new_int64(INT64_MAX), "fermions");
+sentry_value_t attr_3 = sentry_value_new_attribute(sentry_value_new_int64(INT64_MIN), "bosons");
+sentry_value_set_by_key(attributes, "my.custom.attribute", attr);
+sentry_value_set_by_key(attributes, "number.first", attr_2);
+sentry_value_set_by_key(attributes, "number.second", attr_3);
+
+sentry_log_debug("logging with %d custom attributes", attributes, 3);
+
+// if the option is enabled, but you want no additional attributes on a log, pass in an empty sentry_value_new_object()
+sentry_log_debug("logging with %s custom attributes", sentry_value_new_object(), "no");
+```
+
+<Alert level="warning">
+For now, logs can only take `bool`, `double`, `string` and signed `int` attributes. If you want to send unsigned integer values, you should convert these to strings before creating the attribute.
+</Alert>
+
+These additional attributes take precedence over the default attributes, except for `sentry.message.parameter.X` values; if you pass in a string with format specifiers, these are used for the message parameter values.
+
+```c
+sentry_value_t param_attributes = sentry_value_new_object();
+sentry_value_t param_attr = sentry_value_new_attribute(sentry_value_new_string("custom parameter"), NULL);
+sentry_value_t param_attr_2 = sentry_value_new_attribute(sentry_value_new_string("custom-sdk-name"), NULL);
+sentry_value_set_by_key(param_attributes, "sentry.message.parameter.0", param_attr);
+sentry_value_set_by_key(param_attributes, "sentry.sdk.name", param_attr_2);
+
+// will only have "custom-sdk-name" as an attribute value, but not "custom parameter" which gets overwritten by "and format-string"
+sentry_log_fatal("logging with a custom parameter %s attributes", param_attributes, "and format-string");
 ```