From a1ca5902f8d7d004ea2e17e25751043d4506f1a5 Mon Sep 17 00:00:00 2001
From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>
Date: Wed, 12 Nov 2025 16:17:24 +0100
Subject: [PATCH 1/3] add native custom log attributes API docs
---
.../native/common/configuration/options.mdx | 6 +++
platform-includes/logs/usage/native.mdx | 38 +++++++++++++++++--
2 files changed, 41 insertions(+), 3 deletions(-)
diff --git a/docs/platforms/native/common/configuration/options.mdx b/docs/platforms/native/common/configuration/options.mdx
index 2b2172dd4dd14..e60e160595bc2 100644
--- a/docs/platforms/native/common/configuration/options.mdx
+++ b/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.
+
+
+
+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).
+
+
diff --git a/platform-includes/logs/usage/native.mdx b/platform-includes/logs/usage/native.mdx
index 043121b1cb51f..ba2cfe380da7f 100644
--- a/platform-includes/logs/usage/native.mdx
+++ b/platform-includes/logs/usage/native.mdx
@@ -2,11 +2,43 @@ 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");
+```
+
+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");
```
From 4f73dae1a0b4eafe51cf09e7554efe9fc7676942 Mon Sep 17 00:00:00 2001
From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>
Date: Wed, 12 Nov 2025 17:03:19 +0100
Subject: [PATCH 2/3] add 'attributes' page for native
---
.../enriching-events/attributes/index.mdx | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)
create mode 100644 docs/platforms/native/common/enriching-events/attributes/index.mdx
diff --git a/docs/platforms/native/common/enriching-events/attributes/index.mdx b/docs/platforms/native/common/enriching-events/attributes/index.mdx
new file mode 100644
index 0000000000000..8b82a5322a89e
--- /dev/null
+++ b/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)
From 6bd495a6ca75fc4dc64a34cfd446e093545f03d9 Mon Sep 17 00:00:00 2001
From: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>
Date: Thu, 13 Nov 2025 10:19:22 +0100
Subject: [PATCH 3/3] add warning for uint64 log attributes
---
.../native/common/enriching-events/attributes/index.mdx | 2 +-
platform-includes/logs/usage/native.mdx | 4 ++++
2 files changed, 5 insertions(+), 1 deletion(-)
diff --git a/docs/platforms/native/common/enriching-events/attributes/index.mdx b/docs/platforms/native/common/enriching-events/attributes/index.mdx
index 8b82a5322a89e..b8c9d1669f292 100644
--- a/docs/platforms/native/common/enriching-events/attributes/index.mdx
+++ b/docs/platforms/native/common/enriching-events/attributes/index.mdx
@@ -16,4 +16,4 @@ 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)
+- [Structured logs](/platforms/native/logs/#additional-attributes)
diff --git a/platform-includes/logs/usage/native.mdx b/platform-includes/logs/usage/native.mdx
index ba2cfe380da7f..c5cd0f8949cf9 100644
--- a/platform-includes/logs/usage/native.mdx
+++ b/platform-includes/logs/usage/native.mdx
@@ -30,6 +30,10 @@ sentry_log_debug("logging with %d custom attributes", attributes, 3);
sentry_log_debug("logging with %s custom attributes", sentry_value_new_object(), "no");
```
+
+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.
+
+
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