Custom Instrumentation

On this page you will learn how to manually propagate trace information into and out of your Native application.

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.

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:

static void
copy_headers_to(const char *key, const char *value, void *userdata) {
    sentry_value_t *headers = (sentry_value_t *)userdata;
    sentry_value_set_by_key(*headers, key, sentry_value_new_string(value));
}

int main(int argc, char **argv) {
    // Transaction to continue off of
	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_transaction_iter_headers(tx, copy_headers_to, (void *) &headers);
}

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:

	sentry_transaction_context_t *tx_ctx = sentry_transaction_context_new(
        "honk",
        NULL
    );
    sentry_transaction_context_update_from_header(
        tx_ctx,
        "sentry-trace",
        "41c74c2ea9f2bfb184f86939de5b97aa-399b3e5cc8b83494-1"
    );

The format of the sentry-trace header should follow the one defined in the telemetry docs. It should consist of a 32 character hexadecimal string for the traceId, followed by a 16 character hexadecimal string for the spanId and an optional single character for the sampled flag. If the given string doesn't match this format, the update is ignored and the values in the transaction context will remain unchanged.