feat(tracing): add tracing extension

[Litarnus]

Introducing the initial version of the Sentry tracing extension.

This extension will just produce measurements for registered functions or methods, it is not used to create Spans or manage a trace in any way, that will be handled by the SDK which can set proper start and end callbacks. This will allow interoperability between regular SDK instrumentation and spans created by the callbacks without having to sync anything between extension state and SDK.

The API surface is reasonable small:

Register functions to be instrumented

Functions can be instrumented using \Sentry\instrument or adding the #[\Sentry\Trace] attribute.

\Sentry\instrument("MyClass", "work");

#[\Sentry\Trace]
function work(): int {
    return 10;
}

Register callbacks

// will be called before any instrumented function is invoked
\Sentry\setStartCallback(static function (array $data) {
     return "context-data"
});

// will be called after any instrumented function is invoked
// values returned in start callback are passed in as second parameter
// In this example, $userData === "context-data"
\Sentry\setEndCallback(static function (array $data, $userData) {
    // do something with the result
});

Metadata

It's possible to add metadata to each instrumented function, either by specifying the 3rd parameter in \Sentry\instrument or by adding an array in #[\Sentry\Trace].

\Sentry\instrument("MyClass", "dbQuery", ['op' => 'sentry.sql.query']);

#[\Sentry\Trace(['op' => 'sentry.sql.query'])
function dbQuery(): void {
   // do some DB query stuff
}

Not in scope of this PR

• Unregistering instrumented functions. It's not possible to stop instrumenting functions during execution.
• Callbacks per function: The initial version only allows to set global callbacks

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8366836. Configure here.}