@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/php/tracing.md

@@ -0,0 +1,516 @@
+# Tracing — Sentry PHP SDK
+
+> Minimum SDK: `sentry/sentry` ^4.0 · `sentry/sentry-laravel` ^4.0 ·
+> `sentry/sentry-symfony` ^5.0
+
+## Configuration
+
+| Option                      | Type       | Default | Purpose                                                                                                                                                                                                                |
+| --------------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `traces_sample_rate`        | `float`    | `null`  | Fraction of transactions to trace (0.0–1.0); `null` disables tracing                                                                                                                                                   |
+| `traces_sampler`            | `callable` | `null`  | Per-transaction sampling function; takes precedence over `traces_sample_rate`                                                                                                                                          |
+| `profiles_sample_rate`      | `float`    | `null`  | Fraction of sampled transactions to profile (relative to `traces_sample_rate`)                                                                                                                                         |
+| `ignore_transactions`       | `array`    | `[]`    | Transaction names to never trace (e.g., `['/up', '/healthz']`)                                                                                                                                                         |
+| `before_send_transaction`   | `callable` | no-op   | Mutate or drop transaction events before sending                                                                                                                                                                       |
+| `strict_trace_continuation` | `bool`     | `false` | Only continue an incoming distributed trace if the `sentry-org_id` baggage matches the SDK’s org ID; prevents trace contamination from third-party services (>=4.21.0). Replaces deprecated `strict_trace_propagation` |
+
+## Code Examples
+
+### Enable tracing
+
+```php
+// Plain PHP — uniform sample rate
+\Sentry\init([
+    'dsn'                => 'https://<key>@<org>.ingest.sentry.io/<project>',
+    'traces_sample_rate' => 0.2,  // trace 20% of requests
+]);
+
+// Laravel — config/sentry.php
+'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE') === null
+    ? null
+    : (float) env('SENTRY_TRACES_SAMPLE_RATE'),
+```
+
+```yaml
+# Symfony — config/packages/sentry.yaml
+sentry:
+  options:
+    traces_sample_rate: 0.2
+```
+
+### Dynamic sampling with `traces_sampler`
+
+```php
+// Plain PHP — closure directly in init()
+\Sentry\init([
+    'dsn' => '...',
+    'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float {
+        $transactionName = $context->getTransactionContext()->getName();
+
+        // Drop health checks
+        if (in_array($transactionName, ['/healthz', '/up', '/ping'])) {
+            return 0.0;
+        }
+
+        // Honour parent sampling decision in distributed traces
+        $parentSampled = $context->getParentSampled();
+        if ($parentSampled !== null) {
+            return (float) $parentSampled;
+        }
+
+        // 50% of HTTP requests, 10% of everything else
+        return str_starts_with($transactionName, 'GET ') || str_starts_with($transactionName, 'POST ')
+            ? 0.5
+            : 0.1;
+    },
+]);
+```
+
+```yaml
+# Symfony — traces_sampler must be wired through the service container (closures can't be serialized)
+sentry:
+  options:
+    traces_sampler: "sentry.callback.traces_sampler"
+
+services:
+  sentry.callback.traces_sampler:
+    class: 'App\Service\Sentry'
+    factory: ['@App\Service\Sentry', "getTracesSampler"]
+```
+
+```php
+// src/Service/Sentry.php
+namespace App\Service;
+
+class Sentry
+{
+    public function getTracesSampler(): callable
+    {
+        return function (\Sentry\Tracing\SamplingContext $context): float {
+            return 0.5;
+        };
+    }
+}
+```
+
+### Custom span API — `TransactionContext` and `SpanContext`
+
+```php
+use Sentry\Tracing\TransactionContext;
+use Sentry\Tracing\SpanContext;
+
+// 1. Build and start a root transaction
+$transactionContext = TransactionContext::make()
+    ->setName('process-order')
+    ->setOp('task');
+
+$transaction = \Sentry\startTransaction($transactionContext);
+
+// 2. Register on the hub so child spans attach to it
+\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);
+
+// 3. Add a child span
+$spanContext = SpanContext::make()
+    ->setOp('db.query')
+    ->setDescription('SELECT * FROM orders WHERE id = ?');
+
+$span = $transaction->startChild($spanContext);
+// ... do work ...
+$span->finish();
+
+// 4. Finish transaction — submits everything to Sentry
+$transaction->finish();
+```
+
+### `\Sentry\trace()` helper (recommended)
+
+Removes boilerplate: starts the span, sets it as current, finishes it automatically.
+
+```php
+$result = \Sentry\trace(
+    function (\Sentry\State\Scope $scope): array {
+        return fetchOrdersFromDatabase();
+    },
+    SpanContext::make()
+        ->setOp('db.query')
+        ->setDescription('fetch-orders')
+);
+```
+
+### Safe manual span pattern (handles no-transaction case)
+
+```php
+function expensiveOperation(): void
+{
+    $parent = \Sentry\SentrySdk::getCurrentHub()->getSpan();
+    $span = null;
+
+    if ($parent !== null) {
+        $context = SpanContext::make()
+            ->setOp('some_operation')
+            ->setDescription('This is a description');
+        $span = $parent->startChild($context);
+        \Sentry\SentrySdk::getCurrentHub()->setSpan($span);
+    }
+
+    try {
+        // ... do work ...
+    } finally {
+        if ($span !== null) {
+            $span->finish();
+            \Sentry\SentrySdk::getCurrentHub()->setSpan($parent);
+        }
+    }
+}
+```
+
+### Span data attributes
+
+```php
+// At creation time
+$spanContext = SpanContext::make()
+    ->setOp('http.client')
+    ->setData([
+        'http.request.method'       => 'GET',
+        'http.response.status_code' => 200,
+    ]);
+
+// On an existing span
+$span->setData(['db.system' => 'postgresql', 'db.table' => 'orders']);
+
+// Read-modify-write
+$span->setData([
+    'counter' => $span->getData('counter', 0) + 1,
+]);
+```
+
+### Span status
+
+```php
+$span->setStatus(\Sentry\Tracing\SpanStatus::createFromHttpStatusCode($response->getStatusCode()));
+$transaction->setStatus(\Sentry\Tracing\SpanStatus::ok());
+$transaction->setStatus(\Sentry\Tracing\SpanStatus::internalError());
+```
+
+### Accessing the active span/transaction
+
+```php
+$transaction = \Sentry\SentrySdk::getCurrentHub()->getTransaction();  // ?Transaction
+$span        = \Sentry\SentrySdk::getCurrentHub()->getSpan();          // ?Span
+
+if ($transaction !== null) {
+    $transaction->setData(['order.type' => 'subscription']);
+}
+```
+
+### Mutating all spans via `before_send_transaction`
+
+```php
+\Sentry\init([
+    'before_send_transaction' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
+        // Drop health-check transactions
+        if (in_array($event->getTransaction(), ['GET /up', 'GET /healthz'])) {
+            return null;
+        }
+
+        // Add data to every span in the transaction
+        foreach ($event->getSpans() as $span) {
+            $span->setData(['server' => 'web-01']);
+        }
+
+        return $event;
+    },
+]);
+```
+
+## Auto-Instrumentation Matrix
+
+### Plain PHP — No automatic instrumentation
+
+The plain PHP SDK provides **zero automatic instrumentation**. Every transaction and
+span must be created manually using the Custom Span API.
+
+### Laravel — Auto-instrumented operations
+
+The `Tracing\Middleware` is auto-prepended and the `Tracing\ServiceProvider` wires all
+listeners automatically.
+
+| Operation                  | Span Op              | Enabled by default                                    |
+| -------------------------- | -------------------- | ----------------------------------------------------- |
+| HTTP request lifecycle     | `http.server`        | ✅ Always                                             |
+| Route handler dispatch     | `http.route`         | ✅ Always                                             |
+| SQL queries                | `db.sql.query`       | ✅ (`tracing.sql_queries`)                            |
+| DB transactions            | `db.transaction`     | ✅ Always                                             |
+| Blade view rendering       | `view.render`        | ✅ (`tracing.views`)                                  |
+| Outgoing HTTP client       | `http.client`        | ✅ (`tracing.http_client_requests`, Laravel ≥ 8.45)   |
+| Cache operations           | `cache.*`            | ✅ (`tracing.cache`, Laravel ≥ 11.11)                 |
+| Queue job processing       | `queue.process`      | ⚙️ `tracing.queue_jobs: true`                         |
+| Queue job as transaction   | `queue.process`      | ⚙️ `tracing.queue_job_transactions: true`             |
+| Redis commands             | (redis spans)        | ⚙️ `tracing.redis_commands: true`                     |
+| Livewire components        | (livewire spans)     | ⚙️ `tracing.livewire: true`                           |
+| Notifications              | (notification spans) | ✅ (`tracing.notifications`)                          |
+| Lighthouse GraphQL         | (graphql spans)      | ✅ When Lighthouse installed                          |
+| Laravel Folio routes       | transaction name     | ✅ When Folio installed                               |
+| Filesystem disk operations | (file spans)         | ⚙️ Opt-in via `Storage\Integration::configureDisks()` |
+
+```php
+// Filesystem disk opt-in (config/filesystems.php)
+'disks' => \Sentry\Laravel\Features\Storage\Integration::configureDisks([
+    'local' => ['driver' => 'local', 'root' => storage_path('app'), 'throw' => false],
+    's3'    => ['driver' => 's3', /* ... */],
+], enableSpans: true, enableBreadcrumbs: true),
+```
+
+### Symfony — Auto-instrumented operations
+
+`TracingRequestListener` and other compiler-wired listeners activate automatically.
+
+| Operation                         | Span Op                | Origin             |
+| --------------------------------- | ---------------------- | ------------------ |
+| HTTP main request                 | `http.server`          | `auto.http.server` |
+| HTTP sub-request                  | `http.server`          | `auto.http.server` |
+| Console command                   | `console.command`      | `auto.console`     |
+| Outbound HTTP calls               | `http.client`          | `auto.http.client` |
+| Doctrine DB query                 | `db.sql.query`         | `auto.db`          |
+| Doctrine DB prepare               | `db.sql.prepare`       | `auto.db`          |
+| Doctrine DB exec                  | `db.sql.exec`          | `auto.db`          |
+| Doctrine TX begin/commit/rollback | `db.sql.transaction.*` | `auto.db`          |
+| PSR-6 cache get/put/delete/flush  | `cache.*`              | `auto.cache`       |
+| Twig template rendering           | `view.render`          | `auto.view`        |
+
+## Distributed Tracing
+
+Two headers carry trace context between services:
+
+| Header         | Purpose                                                     |
+| -------------- | ----------------------------------------------------------- |
+| `sentry-trace` | Trace ID, span ID, sampling decision (Sentry native format) |
+| `baggage`      | Dynamic sampling context (W3C baggage spec)                 |
+
+> **CORS note:** Both headers must be in your CORS allowlist if browser requests are
+> involved. Proxies and API gateways may strip unknown headers.
+
+### Extracting incoming trace context
+
+```php
+$sentryTrace = $_SERVER['HTTP_SENTRY_TRACE'] ?? '';
+$baggage     = $_SERVER['HTTP_BAGGAGE'] ?? '';
+
+// continueTrace() returns a TransactionContext pre-populated with parent trace data
+$ctx = \Sentry\continueTrace($sentryTrace, $baggage);
+$ctx->setName('process-payment')->setOp('task');
+
+$transaction = \Sentry\startTransaction($ctx);
+\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);
+```
+
+### Injecting outgoing trace headers
+
+```php
+// Manual header injection (e.g., Guzzle, curl, any HTTP client)
+$headers = [
+    'sentry-trace' => \Sentry\getTraceparent(),
+    'baggage'      => \Sentry\getBaggage(),
+];
+
+$client = new \GuzzleHttp\Client();
+$response = $client->get('https://internal-api.example.com', [
+    'headers' => $headers,
+]);
+```
+
+### Guzzle middleware (automatic header injection)
+
+```php
+use Sentry\Tracing\GuzzleTracingMiddleware;
+
+$stack = \GuzzleHttp\HandlerStack::create();
+$stack->push(GuzzleTracingMiddleware::trace());
+
+$client = new \GuzzleHttp\Client(['handler' => $stack]);
+$response = $client->get('https://example.com/');
+// sentry-trace + baggage headers injected automatically; span created for the request
+```
+
+### `continueTrace()` full pattern (queue consumers, workers)
+
+```php
+// Continue a distributed trace from a queue job payload
+$context = \Sentry\continueTrace(
+    $job->getMetadata('sentry_trace'),
+    $job->getMetadata('baggage')
+);
+$context->setOp('queue.process')->setName('App\Jobs\ProcessPayment');
+
+$transaction = \Sentry\startTransaction($context);
+\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);
+
+try {
+    $job->handle();
+} catch (\Throwable $e) {
+    $transaction->setStatus(\Sentry\Tracing\SpanStatus::internalError());
+    throw $e;
+} finally {
+    $transaction->finish();
+}
+```
+
+### HTML meta tag injection (frontend/backend trace stitching)
+
+Inject these tags into your HTML `<head>` so the Sentry JavaScript SDK can continue the
+backend trace in the browser.
+
+```php
+// Plain PHP
+echo sprintf('<meta name="sentry-trace" content="%s"/>', \Sentry\getTraceparent());
+echo sprintf('<meta name="baggage" content="%s"/>', \Sentry\getBaggage());
+```
+
+```blade
+{{-- Laravel Blade template --}}
+{!! \Sentry\Laravel\Integration::sentryMeta() !!}
+
+{{-- Or individually: --}}
+{!! \Sentry\Laravel\Integration::sentryTracingMeta() !!}
+{!! \Sentry\Laravel\Integration::sentryBaggageMeta() !!}
+```
+
+```twig
+{# Symfony Twig template — inject via a controller variable #}
+{{ sentry_trace_meta | raw }}
+{{ sentry_baggage_meta | raw }}
+```
+
+### Framework-automatic propagation
+
+| Framework | Incoming (extract)                                                                | Outgoing (inject)                                                                 |
+| --------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Plain PHP | Manual `continueTrace()`                                                          | Manual header injection                                                           |
+| Laravel   | Auto in `Tracing\Middleware`                                                      | Auto on Laravel HTTP Client (≥ 8.45)                                              |
+| Symfony   | Auto in `TracingRequestListener` (supports both `sentry-trace` and `traceparent`) | Auto via HTTP Client decorator (injects `sentry-trace`, `baggage`, `traceparent`) |
+
+## Profiling
+
+Requires the **Excimer** PHP extension (Wikimedia sampling profiler).
+
+- Platform: **Linux or macOS only** — Windows is not supported
+- PHP: 7.2+
+
+```bash
+# Install Excimer
+apt-get install php-excimer      # Debian/Ubuntu
+pecl install excimer             # PECL
+phpenmod -s fpm excimer          # Enable
+```
+
+```php
+// Plain PHP — traces_sample_rate must be set; profiles_sample_rate is relative to it
+\Sentry\init([
+    'dsn'                  => '...',
+    'traces_sample_rate'   => 1.0,
+    'profiles_sample_rate' => 1.0,  // profile 100% of sampled transactions
+]);
+```
+
+```php
+// Laravel — config/sentry.php
+'traces_sample_rate'   => 1.0,
+'profiles_sample_rate' => 1.0,
+```
+
+```yaml
+# Symfony — config/packages/sentry.yaml
+sentry:
+  options:
+    traces_sample_rate: 1.0
+    profiles_sample_rate: 1.0
+```
+
+`profiles_sample_rate` is a **ratio of already-sampled transactions**:
+
+```
+Effective profiling rate = traces_sample_rate × profiles_sample_rate
+
+Examples:
+  0.5 × 0.5 = 25% of all requests profiled
+  1.0 × 1.0 = 100% of all requests profiled
+  0.1 × 1.0 = 10% of all requests profiled
+```
+
+## Framework-Specific Notes
+
+### Plain PHP
+
+- Zero automatic instrumentation — create every transaction and span manually
+- Call `\Sentry\flush()` before process exit in CLI scripts to ensure buffered data is
+  sent
+- For queue workers and long-running processes, start a transaction per job with
+  `continueTrace()` to preserve distributed trace context
+
+### Laravel
+
+- `Tracing\Middleware` is **auto-prepended** by `Tracing\ServiceProvider` — do not add
+  it manually
+- Transaction start time is backdated to Laravel boot via `setBootedTimestamp()` —
+  captures full request duration including framework startup
+- `missing_routes: false` (default) discards 404/unmatched route transactions; set to
+  `true` to trace them
+- `config:cache` breaks if `traces_sampler` is a closure — use a class/callable string
+  or only set it at runtime
+- Queue tracing: `tracing.queue_jobs: true` creates spans;
+  `tracing.queue_job_transactions: true` creates standalone transactions with
+  distributed trace propagation using payload keys `sentry_trace_parent_data` /
+  `sentry_baggage_data`
+- On **Octane**: FastCGI terminable middleware dispatches spans after response — no
+  user-visible latency.
+  Without FastCGI, use a local Relay proxy
+
+### Symfony
+
+- `TracingRequestListener` accepts both `sentry-trace` (Sentry) and `traceparent` (W3C)
+  headers for incoming distributed traces
+- HTTP Client decorator injects three outgoing headers: `sentry-trace`, `baggage`,
+  `traceparent`
+- Console commands are auto-traced by `TracingConsoleListener` — creates a root
+  transaction if none is active, otherwise creates a child span
+- Messenger integration is **error-capture only** (via `MessengerListener`) — no tracing
+  spans for queue messages
+- FastCGI: spans are sent after response via `kernel.terminate`. Without FastCGI, use a
+  local Relay proxy
+
+## Span Ops Reference
+
+| `op`                                                 | What it tracks                       |
+| ---------------------------------------------------- | ------------------------------------ |
+| `http.server`                                        | Incoming HTTP request                |
+| `http.client`                                        | Outgoing HTTP request                |
+| `http.route`                                         | Controller/action dispatch (Laravel) |
+| `db.sql.query`                                       | SQL query execution                  |
+| `db.sql.prepare`                                     | SQL prepare (Symfony)                |
+| `db.sql.exec`                                        | SQL exec (Symfony)                   |
+| `db.sql.execute`                                     | Statement execute (Symfony)          |
+| `db.sql.transaction.begin` / `.commit` / `.rollback` | DB transaction lifecycle (Symfony)   |
+| `db.transaction`                                     | DB transaction (Laravel)             |
+| `view.render`                                        | Template rendering (Blade / Twig)    |
+| `cache.get`                                          | Cache read                           |
+| `cache.put`                                          | Cache write                          |
+| `cache.remove`                                       | Cache delete                         |
+| `cache.flush`                                        | Cache clear                          |
+| `queue.publish`                                      | Job enqueue                          |
+| `queue.process`                                      | Job processing                       |
+| `console.command`                                    | CLI command (Symfony)                |
+
+## Troubleshooting
+
+| Issue                                   | Solution                                                                                                                   |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| No transactions appearing               | Verify `traces_sample_rate > 0` or `traces_sampler` returns non-zero; confirm SDK is initialized before request handling   |
+| Spans not linked to transaction         | Ensure spans are created inside an active transaction; call `setSpan($transaction)` on the hub after `startTransaction()`  |
+| Distributed traces broken               | Verify `sentry-trace` and `baggage` headers pass through proxies, load balancers, and CORS middleware                      |
+| `traces_sampler` ignored in Laravel     | Closures break `config:cache`; use an invokable class or only configure at runtime (not in config file)                    |
+| `traces_sampler` not working in Symfony | Must be a service factory — closures can’t be serialized. Register as a service and reference by ID                        |
+| Missing route transactions in Laravel   | Set `tracing.missing_routes: true` in sentry config (default is `false` — 404s are discarded)                              |
+| No profiling data                       | Confirm Excimer extension is installed (`php -m \| grep excimer`); Windows not supported; `traces_sample_rate` must be set |
+| High response latency from tracing      | Use FastCGI (terminable middleware) or deploy a local Relay proxy to make uploads async                                    |
+| Queue jobs not traced                   | Set `tracing.queue_jobs: true`; for standalone transactions also set `tracing.queue_job_transactions: true`                |
+| HTML meta tags show empty values        | Call `getTraceparent()` / `getBaggage()` inside an active transaction; outside a transaction these return empty strings    |