feat(native): add propagate_traceparent option (#15162)

Vercel previews:
-
[options](https://sentry-docs-git-joshua-featpropagatetraceparentoption.sentry.dev/platforms/native/configuration/options/#propagate-traceparent)
- [trace propagation
example](https://sentry-docs-git-joshua-featpropagatetraceparentoption.sentry.dev/platforms/native/tracing/trace-propagation/custom-instrumentation/)

## DESCRIBE YOUR PR
Documents the changes from
getsentry/sentry-native#1394

## 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:*

- [ ] 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

@@ -64,6 +64,12 @@ Whether Crashpad should delay application shutdown until the upload of the crash
 
 </ConfigKey>
 
+<ConfigKey name="propagate-traceparent">
+
+Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` header for [distributed tracing](https://docs.sentry.io/platforms/native/tracing/trace-propagation/custom-instrumentation/). This option defaults to `false`.
+
+</ConfigKey>
+
 ## Hooks
 
 These options can be used to hook the SDK in various ways to customize the reporting of events.

platform-includes/distributed-tracing/custom-instrumentation/native.mdx

@@ -2,6 +2,14 @@ On this page you will learn how to manually propagate trace information into and
 
 To obtain trace headers from a transaction, use `sentry_transaction_iter_headers()`. For a span, use `sentry_span_iter_headers()`. Pass the returned value to the downstream service. If communication happens over HTTP, we recommend you attach all headers to the outgoing HTTP request.
 
+By default, only the `sentry-trace` header is generated. To also generate W3C `traceparent` headers for interoperability with other tracing systems, enable traceparent propagation:
+
+```c
+sentry_options_set_propagate_traceparent(options, 1);
+```
+
+When enabled, both `sentry-trace` and `traceparent` headers will be generated with the same trace and span information.
+
 Continuing a trace from an upstream service requires using `sentry_transaction_context_update_from_header()`. Before starting a transaction, pass its transaction context into the previous function along with the `sentry-trace` header. The transaction started with the transaction context will contain everything needed to continue the trace.
 
 To obtain headers from a transaction so it can be continued from a downstream service, define a function which merges the headers into some aggregate object. Use the function in `sentry_transaction_iter_headers()` as a callback. The following example uses `sentry_value_t` as the aggregate object:
@@ -14,18 +22,42 @@ copy_headers_to(const char *key, const char *value, void *userdata) {
 }
 
 int main(int argc, char **argv) {
+    sentry_options_t *options = sentry_options_new();
+    sentry_options_set_dsn(options, "___PUBLIC_DSN___");
+
+    // Enable traceparent propagation for W3C compatibility
+    sentry_options_set_propagate_traceparent(options, 1);
+
+    sentry_init(options);
+
     // Transaction to continue off of
-	sentry_transaction_context_t *tx_ctx = sentry_transaction_context_new(
+    sentry_transaction_context_t *tx_ctx = sentry_transaction_context_new(
         "honk",
         NULL
     );
     sentry_transaction_t *tx = sentry_transaction_start(tx_ctx, sentry_value_new_null());
 
-	sentry_value_t headers = sentry_value_new_object();
+    sentry_value_t headers = sentry_value_new_object();
     sentry_transaction_iter_headers(tx, copy_headers_to, (void *) &headers);
+
+    // The headers object now contains both "sentry-trace" and "traceparent"
+    // (if traceparent propagation is enabled)
+    // Example values:
+    // - "sentry-trace": "2674eb52d5874b13b560236d6c79ce8a-a0f9fdf04f1a63df-1"
+    // - "traceparent": "00-2674eb52d5874b13b560236d6c79ce8a-a0f9fdf04f1a63df-01"
+
+    sentry_transaction_finish(tx);
+    sentry_close();
 }
 ```
 
+The key differences in the generated headers are:
+- `sentry-trace`: Uses Sentry's format with sampling flag as "0" or "1"
+- `traceparent`: Uses W3C format with version "00" and sampling flag as "00" or "01"
+
+Both headers contain the same trace ID and span ID, ensuring compatibility across different tracing systems.
+
+
 To create a transaction as a continuation of a trace retrieved from an upstream service, pass an iterator of the incoming headers to the transaction context:
 
 ```c