@danieljvdm/dev-kit 1.0.1 → 2.0.0

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

@@ -0,0 +1,552 @@
+# Symfony — Sentry SDK Deep Dive
+
+> Package: `sentry/sentry-symfony` · Requires `sentry/sentry ^4.20.0`\
+> Symfony versions: `^4.4.20` through `^8.0`
+
+---
+
+## Installation & Setup
+
+### Requirements
+
+- PHP `^7.2 | ^8.0`
+- Symfony `^4.4.20`–`^8.0`
+- `zend.exception_ignore_args: Off` in `php.ini` (required for stack trace arguments)
+
+### Install
+
+```bash
+composer require sentry/sentry-symfony
+```
+
+**With Symfony Flex**, this automatically:
+
+- Registers the bundle in `config/bundles.php`
+- Creates `config/packages/sentry.yaml`
+- Adds `SENTRY_DSN` to `.env`
+
+**Without Flex**, register manually:
+
+```php
+// config/bundles.php
+return [
+    Sentry\SentryBundle\SentryBundle::class => ['all' => true],
+];
+```
+
+### Environment Variable Setup
+
+```env
+###> sentry/sentry-symfony ###
+SENTRY_DSN="___PUBLIC_DSN___"
+###< sentry/sentry-symfony ###
+```
+
+### Verify
+
+```bash
+php bin/console sentry:test
+```
+
+---
+
+## `config/packages/sentry.yaml` — Complete Schema
+
+```yaml
+sentry:
+  dsn: "%env(SENTRY_DSN)%" # The ONLY mandatory option
+  register_error_listener: true # Register Symfony error event listener
+  register_error_handler: true # Register PHP error/exception handlers
+
+  options:
+    # Release & environment
+    environment: "%kernel.environment%" # Default: kernel env (not "production")
+    release: "%env(default::SENTRY_RELEASE)%"
+    server_name: "web-01"
+
+    # Error monitoring
+    sample_rate: 1.0
+    ignore_exceptions:
+      - "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"
+      - "Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException"
+    error_types: "E_ALL & ~E_NOTICE"
+    before_send: "sentry.callback.before_send" # DIC service ID
+
+    # Tracing
+    traces_sample_rate: 0.1
+    traces_sampler: "sentry.callback.traces_sampler"
+    ignore_transactions:
+      - "GET /health"
+    before_send_transaction: "sentry.callback.before_send_transaction"
+    trace_propagation_targets:
+      - "example.com"
+
+    # Profiling
+    profiles_sample_rate: 0.1
+
+    # Logs
+    enable_logs: true
+    before_send_log: "sentry.callback.before_send_log"
+
+    # Metrics
+    enable_metrics: true
+    before_send_metric: "sentry.callback.before_send_metric"
+
+    # Breadcrumbs
+    max_breadcrumbs: 100
+    before_breadcrumb: "sentry.callback.before_breadcrumb"
+
+    # Context
+    context_lines: 5
+    attach_stacktrace: false
+    send_default_pii: false
+    max_request_body_size: "medium" # none|never|small|medium|always
+    capture_silenced_errors: false
+    max_value_length: 1024
+    in_app_exclude:
+      - "%kernel.cache_dir%"
+      - "%kernel.project_dir%/vendor"
+    in_app_include:
+      - "%kernel.project_dir%/src"
+
+    # Tags
+    tags:
+      server: "web-01"
+      region: "us-east-1"
+
+    # Transport
+    http_proxy: "proxy.example.com:8080"
+    http_connect_timeout: 2
+    http_timeout: 5
+
+    # Serialization
+    class_serializers:
+      App\User: "App\\Sentry\\Serializer\\UserSerializer"
+
+  # Symfony Messenger integration
+  messenger:
+    enabled: true
+    capture_soft_fails: true
+    isolate_breadcrumbs_by_message: false
+
+  # Symfony auto-instrumentation
+  tracing:
+    enabled: true
+    dbal:
+      enabled: true
+      connections:
+        - default
+    twig:
+      enabled: true
+    cache:
+      enabled: true
+    http_client:
+      enabled: true
+    console:
+      excluded_commands:
+        - "messenger:consume"
+```
+
+---
+
+## Symfony-Specific Defaults
+
+These differ from the plain PHP SDK:
+
+| Option           | Plain PHP Default                      | Symfony Default                                                                         |
+| ---------------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
+| `environment`    | `SENTRY_ENVIRONMENT` or `"production"` | `%kernel.environment%` (kernel env)                                                     |
+| `release`        | `SENTRY_RELEASE` env                   | Auto-detected via `PrettyVersions::getRootPackageVersion()`                             |
+| `in_app_exclude` | `[]`                                   | Auto-includes `%kernel.cache_dir%`, `%kernel.build_dir%`, `%kernel.project_dir%/vendor` |
+
+---
+
+## Bundle-Level Options
+
+| Option                    | Type           | Default | Description                                                             |
+| ------------------------- | -------------- | ------- | ----------------------------------------------------------------------- |
+| `dsn`                     | `scalar\|null` | `null`  | Sentry DSN                                                              |
+| `register_error_listener` | `boolean`      | `true`  | Register Symfony `ErrorListener` event subscriber on `kernel.exception` |
+| `register_error_handler`  | `boolean`      | `true`  | Register PHP-level error/exception handlers                             |
+| `logger`                  | `scalar\|null` | `null`  | Service ID of a PSR-3 `LoggerInterface` for SDK debug logging           |
+
+---
+
+## Callable Options — DIC Service Pattern
+
+Symfony’s YAML configuration cannot hold inline PHP closures.
+All callable options must reference a **DIC service ID** whose factory method returns
+the callable.
+
+```yaml
+# config/packages/sentry.yaml
+sentry:
+  options:
+    before_send: "sentry.callback.before_send"
+    traces_sampler: "sentry.callback.traces_sampler"
+    before_send_log: "sentry.callback.before_send_log"
+
+# config/services.yaml
+services:
+  sentry.callback.before_send:
+    class: 'App\Service\SentryCallbacks'
+    factory: ['@App\Service\SentryCallbacks', "getBeforeSend"]
+
+  sentry.callback.traces_sampler:
+    class: 'App\Service\SentryCallbacks'
+    factory: ['@App\Service\SentryCallbacks', "getTracesSampler"]
+
+  sentry.callback.before_send_log:
+    class: 'App\Service\SentryCallbacks'
+    factory: ['@App\Service\SentryCallbacks', "getBeforeSendLog"]
+```
+
+```php
+// src/Service/SentryCallbacks.php
+namespace App\Service;
+
+class SentryCallbacks
+{
+    public function getBeforeSend(): callable
+    {
+        return function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
+            if ($hint?->exception instanceof MyIgnoredException) {
+                return null;
+            }
+            return $event;
+        };
+    }
+
+    public function getTracesSampler(): callable
+    {
+        return function (\Sentry\Tracing\SamplingContext $context): float {
+            return $context->getParentSampled() ? 1.0 : 0.25;
+        };
+    }
+
+    public function getBeforeSendLog(): callable
+    {
+        return function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
+            if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
+                return null; // drop info logs
+            }
+            return $log;
+        };
+    }
+}
+```
+
+This pattern applies to: `before_send`, `before_send_transaction`,
+`before_send_check_in`, `before_send_log`, `before_send_metric`, `before_breadcrumb`,
+`traces_sampler`, `transport`, `http_client`, `logger`, `class_serializers` values.
+
+---
+
+## Auto-Instrumented Operations
+
+| Operation                        | Span Op                       | Requires                   |
+| -------------------------------- | ----------------------------- | -------------------------- |
+| HTTP main request                | `http.server`                 | Always                     |
+| HTTP sub-request                 | `http.server` (child span)    | Always                     |
+| Console command                  | `console.command`             | Always                     |
+| Outbound HTTP calls              | `http.client`                 | `symfony/http-client`      |
+| Doctrine DB prepare              | `db.sql.prepare`              | `doctrine/doctrine-bundle` |
+| Doctrine DB query                | `db.sql.query`                | `doctrine/doctrine-bundle` |
+| Doctrine DB exec                 | `db.sql.exec`                 | `doctrine/doctrine-bundle` |
+| Doctrine TX begin                | `db.sql.transaction.begin`    | `doctrine/doctrine-bundle` |
+| Doctrine TX commit               | `db.sql.transaction.commit`   | `doctrine/doctrine-bundle` |
+| Doctrine TX rollback             | `db.sql.transaction.rollback` | `doctrine/doctrine-bundle` |
+| PSR-6 cache get/put/delete/flush | `cache.*`                     | `symfony/cache`            |
+| Twig template render             | `view.render`                 | `symfony/twig-bundle`      |
+
+**Doctrine span data fields:** `db.system`, `db.user`, `db.name`, `server.address`,
+`server.port`
+
+**⚠️ HTTP client tracing warning:** “Using HTTP client tracing will not execute your
+requests concurrently.”
+— tracing wraps each request synchronously.
+
+### Tracing Sub-Config
+
+```yaml
+sentry:
+  tracing:
+    enabled: true
+    dbal:
+      enabled: true
+      connections: [default] # Specify which DB connections to trace
+    twig:
+      enabled: true
+    cache:
+      enabled: true
+    http_client:
+      enabled: true
+    console:
+      excluded_commands:
+        - "messenger:consume" # Always excluded by default
+        - "app:my-command"
+```
+
+---
+
+## Structured Logs (≥ 5.4.0)
+
+```yaml
+# config/packages/monolog.yaml
+monolog:
+  handlers:
+    sentry_logs:
+      type: service
+      id: Sentry\SentryBundle\Monolog\LogsHandler
+
+# config/services.yaml
+services:
+  Sentry\SentryBundle\Monolog\LogsHandler:
+    arguments:
+      - !php/const Monolog\Logger::INFO # Minimum log level
+
+# config/packages/sentry.yaml
+sentry:
+  options:
+    enable_logs: true
+```
+
+```php
+// Usage — inject LoggerInterface via DI
+class MyService
+{
+    public function __construct(private \Psr\Log\LoggerInterface $logger) {}
+
+    public function doSomething(int $userId): void
+    {
+        $this->logger->info('User logged in');
+        $this->logger->warning('User {id} failed to login.', ['id' => $userId]);
+        $this->logger->error('Something went wrong', [
+            'user_id' => $userId,
+            'action'  => 'update_profile',
+        ]);
+    }
+}
+```
+
+**Auto-flush:**
+
+- HTTP requests: flushed on `kernel.terminate`
+- Console commands: flushed on `console.terminate`
+
+### Traditional Monolog Handler (Error Events, Not Structured Logs)
+
+For sending log messages as Sentry error events (not the Logs product):
+
+```yaml
+# config/services.yaml
+services:
+  app.sentry.handler:
+    class: Sentry\Monolog\Handler
+    arguments:
+      - '@Sentry\State\HubInterface'
+      - !php/const Monolog\Logger::WARNING
+
+  Sentry\Monolog\BreadcrumbHandler:
+    arguments:
+      - '@Sentry\State\HubInterface'
+      - !php/const Monolog\Logger::WARNING
+
+# config/packages/monolog.yaml
+monolog:
+  handlers:
+    sentry:
+      type: service
+      id: app.sentry.handler
+    sentry_buffer:
+      type: buffer
+      handler: sentry
+      level: notice
+      buffer_size: 50
+```
+
+The `BufferFlushPass` compiler pass auto-discovers `BufferHandler` instances and flushes
+them on `kernel.terminate`, `console.command`, `console.terminate`, and `console.error`.
+
+---
+
+## Messenger Integration
+
+The Messenger integration provides error capture for queue workers (not tracing spans):
+
+```yaml
+sentry:
+  messenger:
+    enabled: true # Auto-enabled when MessageBusInterface exists
+    capture_soft_fails: true # Capture failures that will be retried
+    isolate_breadcrumbs_by_message: false # Separate breadcrumb buffer per message
+```
+
+| Option                           | Default | Description                                                               |
+| -------------------------------- | ------- | ------------------------------------------------------------------------- |
+| `enabled`                        | `true`  | Enable Messenger integration                                              |
+| `capture_soft_fails`             | `true`  | Capture exceptions even if the message will be retried                    |
+| `isolate_breadcrumbs_by_message` | `false` | Push/pop scope per message — prevents breadcrumb leakage between messages |
+
+**What it captures:**
+
+- Tags events with `messenger.receiver_name`, `messenger.message_class`,
+  `messenger.message_bus`
+- Unwraps nested exceptions from `HandlerFailedException`,
+  `DelayedMessageHandlingException`, `WrappedExceptionsInterface`
+- Sets `ExceptionMechanism(isHandled: $willRetry)` — retried failures are marked as
+  handled
+- Flushes the client after each failure (background workers have no shutdown hook)
+
+**⚠️ No tracing spans:** There is no `MessengerTracingMiddleware` in the current SDK —
+Messenger integration is error-capture only.
+Use `captureCheckIn()` manually for cron-like queue monitoring.
+
+---
+
+## Cron Monitoring
+
+The Symfony SDK has no dedicated scheduled-task integration.
+Use the PHP SDK functions directly:
+
+```php
+use Sentry\CheckInStatus;
+use Sentry\MonitorConfig;
+use Sentry\MonitorSchedule;
+
+// Two-step check-in (recommended)
+$checkInId = \Sentry\captureCheckIn(
+    slug: 'my-cron-job',
+    status: CheckInStatus::inProgress(),
+);
+
+// ... do work ...
+
+\Sentry\captureCheckIn(
+    slug: 'my-cron-job',
+    status: CheckInStatus::ok(),
+    checkInId: $checkInId,
+);
+
+// Wrapper approach
+\Sentry\withMonitor(
+    slug: 'my-cron-job',
+    callback: fn () => $this->doWork(),
+);
+
+// With programmatic monitor config
+$monitorConfig = new \Sentry\MonitorConfig(
+    \Sentry\MonitorSchedule::crontab('*/10 * * * *'),
+    checkinMargin: 5,
+    maxRuntime: 15,
+    timezone: 'Europe/Vienna',
+    failureIssueThreshold: 2,
+    recoveryThreshold: 5,
+);
+
+$checkInId = \Sentry\captureCheckIn(
+    slug: 'my-cron-job',
+    status: CheckInStatus::inProgress(),
+    monitorConfig: $monitorConfig,
+);
+```
+
+**Filter check-ins:**
+
+```yaml
+sentry:
+  options:
+    before_send_check_in: "App\\Sentry\\BeforeSendCheckInCallback"
+```
+
+---
+
+## Console Command Tracing & Monitoring
+
+### Error Capture (`ConsoleListener`)
+
+Auto-enabled. Tags every console command scope with:
+
+- `console.command` — command name
+- `console.command.exit_code` — exit code
+- `Full command` — full command with arguments (extra context)
+
+Flushes logs AND metrics on `console.terminate`.
+
+### Tracing (`TracingConsoleListener`)
+
+```yaml
+sentry:
+  tracing:
+    console:
+      excluded_commands:
+        - "messenger:consume" # Always excluded
+```
+
+Creates transactions with:
+
+- `op: 'console.command'`
+- `origin: 'auto.console'`
+- `source: TransactionSource::task()`
+- Status: `ok()` if exit code 0, `internalError()` otherwise
+
+---
+
+## Event Listeners Auto-Registered
+
+| Listener                    | Events                                 | Description                                       |
+| --------------------------- | -------------------------------------- | ------------------------------------------------- |
+| `ErrorListener`             | `kernel.exception`                     | Captures all uncaught exceptions                  |
+| `RequestListener`           | `kernel.request`, `kernel.controller`  | Sets IP (PII-gated); tags route name              |
+| `ConsoleCommandListener`    | `console.command`, `console.terminate` | Tags scope, flushes on terminate                  |
+| `MessengerListener`         | Messenger worker events                | Captures failures, optional scope isolation       |
+| `LoginListener`             | Symfony Security login events          | Captures authenticated user context               |
+| `TracingRequestListener`    | `kernel.request`, `kernel.terminate`   | Creates/finishes transaction for HTTP requests    |
+| `TracingSubRequestListener` | `kernel.request` (subrequest)          | Creates child spans for sub-requests              |
+| `TracingConsoleListener`    | `console.command`, `console.terminate` | Creates/finishes transaction for console commands |
+
+### Distributed Tracing — Automatic Header Handling
+
+The `TracingRequestListener` automatically reads incoming trace headers:
+
+```php
+// Accepts both Sentry and W3C trace context formats:
+$request->headers->get('sentry-trace')   // Sentry format
+$request->headers->get('traceparent')    // W3C format
+$request->headers->get('baggage')
+```
+
+The `AbstractTraceableHttpClient` decorator automatically injects outbound headers on
+all Symfony HTTP Client requests:
+
+```
+sentry-trace: <value>
+baggage: <value>
+traceparent: <value>   # W3C trace context
+```
+
+Respects `trace_propagation_targets` — only injects headers to matching hostnames.
+
+---
+
+## Metrics (≥ 5.8.0)
+
+```php
+use function Sentry\traceMetrics;
+
+traceMetrics()->count('button-click', 5, ['browser' => 'Firefox']);
+traceMetrics()->distribution('page-load', 15.0, ['page' => '/home'], \Sentry\Unit::millisecond());
+traceMetrics()->gauge('memory-usage', memory_get_usage(), ['worker' => 'web-01']);
+```
+
+**Config:**
+
+```yaml
+sentry:
+  options:
+    enable_metrics: true
+    before_send_metric: "App\\Sentry\\BeforeSendMetricCallback"
+```
+
+**Auto-flush:** Flushed automatically on `kernel.terminate` and `console.terminate` — no
+manual flush needed in typical web/console contexts.