|
| 1 | +On this page you will learn how to manually propagate trace information into and out of your PHP application. |
| 2 | + |
| 3 | +To set it up manually, all you have to do is to make sure your application extracts incoming headers and to set those headers again when making an outgoing request within your application. |
| 4 | + |
| 5 | +## Step 1) Extract Incoming Tracing Information |
| 6 | + |
| 7 | +Incoming tracing information has to be extracted and stored in memory for later use. Sentry provides the `\Sentry\continueTrace()` function to help you with this. Incoming tracing information can come from different places: |
| 8 | + |
| 9 | +- In a web environment it will be sent via HTTP headers, for example, by another Sentry SDK used in your frontend project. |
| 10 | +- You also can pick up tracing information from environment variables. |
| 11 | + |
| 12 | +Here's an example of how to extract and store incoming tracing information using `\Sentry\continueTrace()`: |
| 13 | + |
| 14 | +```php |
| 15 | +$sentryTraceHeader = $request->getHeaderLine('sentry-trace'); |
| 16 | +$baggageHeader = $request->getHeaderLine('baggage'); |
| 17 | + |
| 18 | +\Sentry\continueTrace($sentryTraceHeader, $baggageHeader); |
| 19 | +``` |
| 20 | + |
| 21 | +Sentry's `\Sentry\continueTrace()` function will extract the given headers, try to find the `sentry-trace` and `baggage` headers, and store them in memory for later use. |
| 22 | + |
| 23 | +## Step 2) Inject Tracing Information to Outgoing Requests |
| 24 | + |
| 25 | +For distributed tracing to work, the two headers `sentry-trace` and `baggage`, must now also be added to outgoing requests. If you pregenerate HTML on the server-side, you might want to take a look at option 2 as well, which describes how to pass on tracing information through HTML meta tags. |
| 26 | + |
| 27 | +### Inject Tracing Information Into HTTP Requests |
| 28 | + |
| 29 | +You can generate this tracing information with the Sentry SDK's `\Sentry\getTraceparent()` and `\Sentry\getBaggage()` functions. Here's an example using Guzzle: |
| 30 | + |
| 31 | +```php |
| 32 | +$client = new GuzzleHttp\Client(); |
| 33 | +$res = $client->request('GET', 'https://example.com', [ |
| 34 | + 'headers' => [ |
| 35 | + 'baggage' => \Sentry\getBaggage(), |
| 36 | + 'sentry-trace' => \Sentry\getTraceparent(), |
| 37 | + ] |
| 38 | +]); |
| 39 | + |
| 40 | +``` |
| 41 | + |
| 42 | +In this example, tracing information is propagated to the project running at `https://example.com`. If this project uses a Sentry SDK, it will extract and save the tracing information for later use. |
| 43 | + |
| 44 | +The two services are now connected with your custom distributed tracing implementation. |
| 45 | + |
| 46 | +### Inject Tracing Information Into Rendered HTML |
| 47 | + |
| 48 | +To propagate tracing information into JavaScript running in rendered HTML you have to inject HTML `meta` tags for `sentry-trace` and `baggage` data into your rendered HTML. Here's an example: |
| 49 | + |
| 50 | +```php |
| 51 | +<!DOCTYPE html> |
| 52 | +<html> |
| 53 | + <head> |
| 54 | + <meta charset="UTF-8"> |
| 55 | + <?= sprintf('<meta name="baggage" content="%s"/>', \Sentry\getBaggage()); ?> |
| 56 | + <?= sprintf('<meta name="sentry-trace" content="%s"/>', \Sentry\getTraceparent()); ?> |
| 57 | + </head> |
| 58 | + <body> |
| 59 | + <p>This is a website.</p> |
| 60 | + </body> |
| 61 | +</html> |
| 62 | +``` |
| 63 | + |
| 64 | +## Verification |
| 65 | + |
| 66 | +If you make outgoing requests from your project to other services, check if the headers `sentry-trace` and `baggage` are present in the request. If so, distributed tracing is working. |
0 commit comments