feat: Added sentry_set_trace

[bitsandfoxes]

Motivation

Looking at it from one of the upstream SDKs (i.e. Android SDK, Unity SDK) there is currently no way to connect errors and events from their environment with the events sent by sentry-native.
The idea is to provide a way for those SDKs to propagate their trace to be used and applied to events. The trace ID can then be used to link those events across multiple SDKs, languages, and layers.

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 2a9c423

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.81%. Comparing base (2577cfc) to head (2a9c423).
Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1137      +/-   ##
==========================================
+ Coverage   82.66%   82.81%   +0.15%     
==========================================
  Files          53       53              
  Lines        7954     7973      +19     
  Branches     1246     1247       +1     
==========================================
+ Hits         6575     6603      +28     
+ Misses       1266     1256      -10     
- Partials      113      114       +1     

[supervacuus]

Besides a changelog, I missed a basic test for the interaction with transactions. Something like this in test_tracing.c:

void
apply_scope_and_check_trace_context(
    sentry_options_t *options, const char *trace_id, const char *parent_span_id)
{
    // simulate scope application onto an event
    sentry_value_t event = sentry_value_new_object();
    SENTRY_WITH_SCOPE (scope) {
        sentry__scope_apply_to_event(scope, options, event, SENTRY_SCOPE_NONE);
    }

    // check that the event has a trace context
    sentry_value_t event_contexts = sentry_value_get_by_key(event, "contexts");
    TEST_CHECK(!sentry_value_is_null(event_contexts));
    TEST_CHECK(
        sentry_value_get_type(event_contexts) == SENTRY_VALUE_TYPE_OBJECT);

    sentry_value_t event_trace_context
        = sentry_value_get_by_key(event_contexts, "trace");
    TEST_CHECK(!sentry_value_is_null(event_trace_context));
    TEST_CHECK(
        sentry_value_get_type(event_trace_context) == SENTRY_VALUE_TYPE_OBJECT);

    // check trace context content
    const char *event_trace_id = sentry_value_as_string(
        sentry_value_get_by_key(event_trace_context, "trace_id"));
    TEST_CHECK_STRING_EQUAL(event_trace_id, trace_id);

    const char *event_trace_parent_span_id = sentry_value_as_string(
        sentry_value_get_by_key(event_trace_context, "parent_span_id"));
    TEST_CHECK_STRING_EQUAL(event_trace_parent_span_id, parent_span_id);

    sentry_uuid_t event_trace_span_id = sentry__value_as_uuid(
        sentry_value_get_by_key(event_trace_context, "span_id"));
    TEST_CHECK(!sentry_uuid_is_nil(&event_trace_span_id));

    sentry_value_decref(event);
}

SENTRY_TEST(set_trace_id_with_txn)
{
    // initialize SDK so we have a scope
    sentry_options_t *options = sentry_options_new();
    sentry_options_set_traces_sample_rate(options, 1.0);
    sentry_options_set_sample_rate(options, 1.0);
    sentry_init(options);

    // inject a trace via trace-header into a transaction
    const char *trace_header
        = "2674eb52d5874b13b560236d6c79ce8a-a0f9fdf04f1a63df-1";
    const char *txn_trace_id = "2674eb52d5874b13b560236d6c79ce8a";
    const char *txn_parent_span_id = "a0f9fdf04f1a63df";
    sentry_transaction_context_t *tx_ctx
        = sentry_transaction_context_new("wow!", NULL);
    sentry_transaction_context_update_from_header(
        tx_ctx, "sentry-trace", trace_header);
    sentry_transaction_t *tx
        = sentry_transaction_start(tx_ctx, sentry_value_new_null());

    // set the direct trace first
    const char *direct_trace_id = "aaaabbbbccccddddeeeeffff00001111";
    const char *direct_parent_span_id = "f0f0f0f0f0f0f0f0";
    sentry_set_trace(direct_trace_id, direct_parent_span_id);

    // events should get that trace applied
    apply_scope_and_check_trace_context(
        options, direct_trace_id, direct_parent_span_id);

    // now set a scoped transaction
    sentry_set_transaction_object(tx);

    // events should get the transaction's trace applied
    apply_scope_and_check_trace_context(
        options, txn_trace_id, txn_parent_span_id);

    sentry_transaction_finish(tx);

    // after finishing the transaction, the direct trace should hit again
    apply_scope_and_check_trace_context(
        options, direct_trace_id, direct_parent_span_id);

    sentry_close();
}

[markushi]

Looks good to me, especially the Java part 🤓
You probably need to apply the code formatter + .api file generator using
./gradlew spotlessApply + ./gradlew :sentry-native-ndk:apiDump to make CI happier.

[supervacuus]

If downstream, y'all are also happy, let's do this.

Because @supervacuus is fine with it!