Add tracing

Author: tustanivsky

docs/platforms/unreal/tracing/index.mdx

@@ -0,0 +1,42 @@
+---
+title: Set Up Tracing
+description: "Learn how to enable tracing in your app and discover valuable performance insights of your application."
+sidebar_order: 4000
+---
+
+With [tracing](/product/performance/), Sentry tracks your software performance, measuring metrics like throughput and latency, and displaying the impact of errors across multiple systems. Sentry captures distributed traces consisting of transactions and spans, which measure individual services and individual operations within those services. Learn more about our model in [Distributed Tracing](/product/sentry-basics/tracing/distributed-tracing/).
+
+<Note>
+
+If you’re adopting Tracing in a high-throughput environment, we recommend testing prior to deployment to ensure that your service’s performance characteristics maintain expectations.
+
+</Note>
+
+## Configure
+
+First, enable tracing and configure the sample rate for transactions. Set the sample rate for your transactions by either:
+
+- Setting a uniform sample rate for all transactions using the <PlatformIdentifier name="traces-sample-rate" /> option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set <PlatformIdentifier name="traces-sample-rate" /> to `0.2`.)
+- Controlling the sample rate based on the transaction itself and the context in which it's captured, by providing a function to the <PlatformIdentifier name="traces-sampler" /> config option.
+
+The two options are meant to be mutually exclusive. If you set both, <PlatformIdentifier name="traces-sampler" /> will take precedence.
+
+<Alert level="info">
+
+The Unreal Engine SDK doesn't currently support sampling functions on Windows/Linux (<PlatformIdentifier name="traces-sampler" />).
+
+</Alert>
+
+<PlatformContent includePath="performance/configure-sample-rate" />
+
+Learn more about tracing <PlatformLink to="/configuration/options/#tracing-options">options</PlatformLink>, how to use the <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">TracesSampler</PlatformLink> function, or how to <PlatformLink to="/configuration/sampling/#sampling-transaction-events">sample transactions</PlatformLink>.
+
+## Verify
+
+Test out tracing by starting and finishing a transaction, which you _must_ do so transactions can be sent to Sentry. Learn how in our <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> content.
+
+While you're testing, set <PlatformIdentifier name="traces-sample-rate" /> to `1.0`, as that ensures that every transaction will be sent to Sentry. Once testing is complete, you may want to set a lower <PlatformIdentifier name="traces-sample-rate" /> value, or switch to using <PlatformIdentifier name="traces-sampler" /> to selectively sample and filter your transactions, based on contextual data.
+
+## Next Steps
+
+<PageGrid />

docs/platforms/unreal/tracing/instrumentation/custom-instrumentation.mdx

@@ -0,0 +1,19 @@
+---
+title: Custom Instrumentation
+description: "Learn how to capture performance data on any action in your app."
+sidebar_order: 20
+---
+
+<Note>
+
+To capture transactions and spans customized to your organization's needs, you must first <PlatformLink to="/tracing/">set up tracing.</PlatformLink>
+
+</Note>
+
+<PlatformContent includePath="performance/enable-manual-instrumentation" />
+
+<PlatformContent includePath="performance/add-spans-example" />
+
+## Distributed Tracing
+
+In order to use distributed tracing with the Native SDK, follow the <PlatformLink to="/tracing/trace-propagation/custom-instrumentation/">custom instrumentation</PlatformLink> steps.

docs/platforms/unreal/tracing/instrumentation/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Instrumentation
+description: "Learn how to instrument tracing in your app."
+sidebar_order: 20
+---
+
+<PageGrid />

docs/platforms/unreal/tracing/trace-propagation/custom-instrumentation/index.mdx

@@ -0,0 +1,6 @@
+---
+title: Custom Instrumentation
+sidebar_order: 40
+---
+
+<PlatformContent includePath="distributed-tracing/custom-instrumentation/" />

docs/platforms/unreal/tracing/trace-propagation/dealing-with-cors-issues/index.mdx

@@ -0,0 +1,10 @@
+---
+title: Dealing with CORS Issues
+sidebar_order: 80
+---
+
+If your frontend and backend are hosted on different domains (for example, your frontend is on `https://example.com` and your backend is on `https://api.example.com`), and the frontend does XHR/fetch requests to your backend, you'll need to configure your backend [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) headers to ensure requests aren't blocked.
+
+Configure your backend CORS to allow the `sentry-trace` and `baggage` headers.
+
+Your server's response header configuration might look like: `"Access-Control-Allow-Headers: sentry-trace, baggage"`. Your configuration will be specific to your setup.

docs/platforms/unreal/tracing/trace-propagation/index.mdx

@@ -0,0 +1,34 @@
+---
+title: Trace Propagation
+description: "Learn how to connect events across applications/services."
+sidebar_order: 3000
+---
+
+If the overall application landscape that you want to observe with Sentry consists of more than just a single service or application, distributed tracing can add a lot of value.
+
+## What is Distributed Tracing?
+
+In the context of tracing events across a distributed system, distributed tracing acts as a powerful debugging tool. Imagine your application as a vast network of interconnected parts. For example, your system might be spread across different servers or your application might split into different backend and frontend services, each potentially having their own technology stack.
+
+When an error or performance issue occurs, it can be challenging to pinpoint the root cause due to the complexity of such a system. Distributed tracing helps you follow the path of an event as it travels through this intricate web, recording every step it takes. By examining these traces, you can reconstruct the sequence of events leading up to the event of interest, identify the specific components involved, and understand their interactions. This detailed visibility enables you to diagnose and resolve issues more effectively, ultimately improving the reliability and performance of your distributed system.
+
+## Basic Example
+
+Here's an example showing a distributed trace in Sentry:
+
+<Include name="common-imgs/distributed-trace-in-sentry" />
+
+This distributed trace shows a Vue app's `pageload` making a request to a Python backend, which then calls the `/api` endpoint of a Ruby microservice.
+
+What happens in the background is that Sentry uses reads and further propagates two HTTP headers between your applications:
+
+- `sentry-trace`
+- `baggage`
+
+If you run any JavaScript applications in your distributed system, make sure that those two headers are added to your CORS allowlist and won't be blocked or stripped by your proxy servers, gateways, or firewalls.
+
+## How to Use Distributed Tracing?
+
+<PlatformContent includePath="distributed-tracing/how-to-use/" />
+
+Remember that in order to propagate trace information through your whole distributed system, you have to use Sentry in all of the involved services and applications. Take a look at the respective SDK documentation to learn how distributed tracing can be enabled for each platform.

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

@@ -0,0 +1,19 @@
+On this page you will learn how to manually propagate trace information into and out of your Unreal Engine game.
+
+Continuing a trace from an upstream service requires using `ContinueTrace()` that will create a transaction context with the provided `sentry-trace` header. The transaction started with the transaction context will contain everything needed to continue the trace.
+
+```cpp
+// Get incoming tracing information
+const FString inTrace = ...
+TArray<FString>() inBaggage = ...
+
+USentryTransactionContext* transactionContext =
+    SentrySubsystem->ContinueTrace(inTrace, inBaggage);
+
+USentryTransaction* transaction =
+    SentrySubsystem->StartTransactionWithContext(transactionContext);
+```
+
+To obtain trace header from a transaction or span, use `GetTrace()`. Pass the returned value to the downstream service. If communication happens over HTTP, we recommend you attach this header to the outgoing HTTP request.
+
+The format of the `sentry-trace` header should follow the one defined in [the telemetry docs](https://develop.sentry.dev/sdk/telemetry/traces/#header-sentry-trace). 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.

platform-includes/distributed-tracing/how-to-use/unreal.mdx

@@ -0,0 +1 @@
+In order to use distributed tracing with the Native SDK, follow the <PlatformLink to="/tracing/trace-propagation/custom-instrumentation/">custom instrumentation</PlatformLink> steps.

platform-includes/performance/add-spans-example/unreal.mdx

@@ -0,0 +1,42 @@
+For example, if you want to create a transaction for a user interaction in your application:
+
+```cpp
+// Let's say this method is called in a background thread when a user clicks on the checkout button.
+void perform_checkout() {
+    USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
+
+    // This will create a new Transaction for you
+    USentryTransactionContext* transactionContext = NewObject<USentryTransactionContext>();
+    transactionContext->Initialize(
+        TEXT("checkout"),
+        TEXT("perform-checkout")
+    );
+
+    USentryTransaction* transaction =
+        SentrySubsystem->StartTransactionWithContext(transactionContext);
+
+    // Validate the cart
+    USentrySpan* validationSpan = transaction->StartChild(
+        TEXT("validation"),
+        TEXT("validating shopping cart")
+    );
+
+    validate_shopping_cart(); // Some long process, maybe a sync http request.
+
+    validationSpan->Finish();
+
+    // Process the order
+    SentrySpan* processSpan = transaction->StartChild(
+        TEXT("process"),
+        TEXT("processing shopping cart")
+    );
+
+    process_shopping_cart(); // Another time consuming process.
+
+    processSpan->Finish();
+
+    transaction->Finish();
+}
+```
+
+This example will send a transaction named `checkout` to Sentry. The transaction will contain a `validation` span that measures how long `validate_shopping_cart()` took and a `process` span that measures `process_shopping_cart()`. Finally, the `transaction->Finish()` call will finish the transaction and send it to Sentry.

platform-includes/performance/configure-sample-rate/unreal.mdx

@@ -0,0 +1,17 @@
+```cpp {diff}
+#include "SentrySettings.h"
+
+FConfigureSettingsDelegate SettingsDelegate;
+SettingsDelegate.BindDynamic(this, &USomeClass::ConfigureSettingsDelegate);
+
+void USomeClass::ConfigureSettingsDelegate(USentrySettings* Settings)
+{
+    Settings->TracesSampleRate = 0.2f;
+}
+
+...
+
+USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem<USentrySubsystem>();
+
+SentrySubsystem->InitializeWithSettings(SettingsDelegate);
+```