@danieljvdm/dev-kit 1.0.1 → 2.0.0

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

@@ -0,0 +1,242 @@
+# Logging — Sentry PHP SDK
+
+> Minimum SDK versions: `sentry/sentry` ≥ 4.12.0 · `sentry/sentry-laravel` ≥ 4.15.0 ·
+> `sentry/sentry-symfony` ≥ 5.4.0
+
+## Overview
+
+Sentry PHP structured logs are **separate from error reporting**. They produce
+searchable log records in the Sentry Logs UI. The feature must be explicitly enabled
+with `enable_logs: true`.
+
+## Configuration
+
+### PHP (base SDK)
+
+```php
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'enable_logs' => true,
+]);
+```
+
+### Laravel (`.env`)
+
+```bash
+LOG_CHANNEL=stack
+LOG_STACK=single,sentry_logs
+SENTRY_ENABLE_LOGS=true
+LOG_LEVEL=info
+SENTRY_LOG_LEVEL=warning    # optional: Sentry-specific threshold
+```
+
+`config/sentry.php`:
+
+```php
+'enable_logs' => env('SENTRY_ENABLE_LOGS', false),
+'logs_channel_level' => env('SENTRY_LOG_LEVEL', env('LOG_LEVEL', 'debug')),
+```
+
+> For SDK versions ≤ 4.16.0, also add `sentry_logs` to `config/logging.php` channels
+> manually. Versions > 4.16.0 auto-register it.
+
+### Symfony (`config/packages/sentry.yaml` + `monolog.yaml`)
+
+```yaml
+# config/packages/sentry.yaml
+sentry:
+  options:
+    enable_logs: true
+```
+
+```yaml
+# config/packages/monolog.yaml
+monolog:
+  handlers:
+    sentry_logs:
+      type: service
+      id: Sentry\SentryBundle\Monolog\LogsHandler
+```
+
+```yaml
+# config/services.yaml
+services:
+  Sentry\SentryBundle\Monolog\LogsHandler:
+    arguments:
+      - !php/const Monolog\Logger::INFO
+```
+
+## Code Examples
+
+### PHP — direct logger API
+
+```php
+\Sentry\logger()->trace('Starting request processing');
+\Sentry\logger()->debug('Cache lookup for key %s', values: ['user:42']);
+\Sentry\logger()->info('User logged in');
+\Sentry\logger()->warn('Rate limit approaching for %s', values: ['/api/v1/users']);
+\Sentry\logger()->error('Payment failed for order %s', values: [$orderId]);
+\Sentry\logger()->fatal('Database connection pool exhausted');
+
+// Must flush at end of script (CLI) or long-running processes
+\Sentry\logger()->flush();
+```
+
+### PHP — with custom attributes
+
+```php
+\Sentry\logger()->warn('This is a warning log with attributes.', attributes: [
+    'attribute1' => 'string',
+    'attribute2' => 1,
+    'attribute3' => 1.0,
+    'attribute4' => true,
+]);
+```
+
+### PHP — Monolog bridge
+
+```php
+use Monolog\Level;
+use Monolog\Logger;
+
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'enable_logs' => true,
+]);
+
+$log = new Logger('app');
+$log->pushHandler(new \Sentry\Monolog\LogsHandler(
+    hub: \Sentry\SentrySdk::getCurrentHub(),
+    level: Level::Info,
+));
+
+$log->info('Application started');
+$log->error('Something went wrong', ['user_id' => 42]);
+
+\Sentry\logger()->flush();
+```
+
+### Laravel — Laravel Log facade
+
+```php
+use Illuminate\Support\Facades\Log;
+
+Log::info('This is an info message');
+Log::warning('User {id} failed to login.', ['id' => $user->id]);
+Log::error('Payment failed', [
+    'user_id' => auth()->id(),
+    'order_id' => $orderId,
+]);
+
+// Send only to Sentry (not to other channels)
+Log::channel('sentry_logs')->error('Critical failure in payment module');
+```
+
+### Symfony — via injected LoggerInterface
+
+```php
+// Inject via constructor or autowiring
+$this->logger->info('User {id} logged in', ['id' => $userId]);
+$this->logger->warning('Slow query detected', ['duration_ms' => 850]);
+$this->logger->error('Payment processing failed', [
+    'user_id' => $userId,
+    'action' => 'checkout',
+]);
+```
+
+### Filtering with `before_send_log`
+
+**PHP / Laravel:**
+
+```php
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'enable_logs' => true,
+    'before_send_log' => function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
+        if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
+            return null;  // drop info logs
+        }
+        return $log;
+    },
+]);
+```
+
+**Symfony** (uses service ID, not a closure):
+
+```yaml
+sentry:
+  options:
+    before_send_log: "sentry.callback.before_send_log"
+```
+
+```php
+// App\Service\Sentry
+public function getBeforeSendLog(): callable
+{
+    return function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
+        if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
+            return null;
+        }
+        return $log;
+    };
+}
+```
+
+## Two Log Channel Types in Laravel
+
+| Channel       | Driver        | Purpose                                                   |
+| ------------- | ------------- | --------------------------------------------------------- |
+| `sentry`      | `sentry`      | Sends log messages as Sentry **error events/breadcrumbs** |
+| `sentry_logs` | `sentry_logs` | Sends **structured logs** to the Sentry Logs product      |
+
+These are independent — use `sentry_logs` for the structured logs feature.
+
+## Log Levels
+
+| Method    | PSR Level |
+| --------- | --------- |
+| `trace()` | debug     |
+| `debug()` | debug     |
+| `info()`  | info      |
+| `warn()`  | warning   |
+| `error()` | error     |
+| `fatal()` | critical  |
+
+## Automatically Added Attributes
+
+Every log record receives these automatically:
+
+| Attribute                                | Description                           |
+| ---------------------------------------- | ------------------------------------- |
+| `sentry.environment`                     | Environment from SDK config           |
+| `sentry.release`                         | Release from SDK config               |
+| `sentry.sdk.name` / `sentry.sdk.version` | SDK metadata                          |
+| `sentry.server.address`                  | Server hostname                       |
+| `sentry.message.template`                | Parameterized template string         |
+| `sentry.message.parameter.N`             | Template parameter values             |
+| `user.id`, `user.name`, `user.email`     | Active scope user (if set)            |
+| `sentry.origin`                          | Log origin (e.g., `auto.log.monolog`) |
+
+## Flushing
+
+Logs are buffered and must be flushed to be sent:
+
+| Context           | Behavior                                                      |
+| ----------------- | ------------------------------------------------------------- |
+| PHP (CLI/scripts) | Call `\Sentry\logger()->flush()` manually at end of execution |
+| Laravel           | Auto-flushed via `app->terminating()` callback                |
+| Symfony (HTTP)    | Auto-flushed on `kernel.terminate` by `LogRequestListener`    |
+| Symfony (console) | Auto-flushed on `console.terminate` by `ConsoleListener`      |
+
+**Long-running CLI tasks:** Call `\Sentry\logger()->flush()` periodically to avoid
+memory buildup.
+
+## Troubleshooting
+
+| Issue                       | Solution                                                                            |
+| --------------------------- | ----------------------------------------------------------------------------------- |
+| Logs not appearing          | Verify `enable_logs: true` and that `\Sentry\logger()->flush()` is called           |
+| Laravel logs missing        | Check `LOG_STACK` includes `sentry_logs` and `LOG_LEVEL` permits expected messages  |
+| Symfony logs missing        | Verify `LogsHandler` is registered in `monolog.yaml` and `enable_logs: true` is set |
+| Tinker session missing logs | Manually call `\Sentry\logger()->flush()` — Tinker skips normal lifecycle           |
+| Info logs filtered out      | Check `before_send_log` callback and `SENTRY_LOG_LEVEL` threshold                   |

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

@@ -0,0 +1,193 @@
+# Metrics — Sentry PHP SDK
+
+> Minimum SDK versions: `sentry/sentry` ≥ 4.19.0 · `sentry/sentry-laravel` ≥ 4.20.0 ·
+> `sentry/sentry-symfony` ≥ 5.8.0
+
+## Overview
+
+Custom metrics (counters, distributions, gauges) are enabled by default — no extra flag
+required. Use `\Sentry\traceMetrics()` as the entry point.
+
+> **Note:** The old `\Sentry\metrics()` API is **fully deprecated** — all methods are
+> no-ops. Use `\Sentry\traceMetrics()` instead.
+
+## Metric Types
+
+| Type         | Method           | Aggregations              | Use for                                 |
+| ------------ | ---------------- | ------------------------- | --------------------------------------- |
+| Counter      | `count()`        | sum                       | Event occurrences, request counts       |
+| Distribution | `distribution()` | p90, min, max, avg        | Latencies, sizes — supports percentiles |
+| Gauge        | `gauge()`        | min, max, avg, sum, count | Current values — no percentiles         |
+
+## Code Examples
+
+### Counter — event occurrences
+
+```php
+\Sentry\traceMetrics()->count('button-click', 5, [
+    'browser' => 'Firefox',
+    'app_version' => '1.0.0',
+]);
+```
+
+### Distribution — percentile analysis
+
+Best for latencies, response sizes, durations where p90/p99 matter:
+
+```php
+use \Sentry\Metrics\Unit;
+
+\Sentry\traceMetrics()->distribution('page-load', 15.0, ['page' => '/home'], Unit::millisecond());
+```
+
+### Gauge — space-efficient aggregates
+
+Use when high cardinality is a concern; no percentile support:
+
+```php
+use \Sentry\Metrics\Unit;
+
+\Sentry\traceMetrics()->gauge('active-connections', 42.0, ['region' => 'eu-west'], Unit::none());
+```
+
+### Flushing manually
+
+Metrics are buffered (up to 1000 entries).
+Flush explicitly in CLI scripts or when emitting high volumes:
+
+```php
+\Sentry\traceMetrics()->flush();
+```
+
+### Filtering with `before_send_metric`
+
+**PHP / Laravel:**
+
+```php
+use \Sentry\Metrics\Types\Metric;
+
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'before_send_metric' => static function (Metric $metric): ?Metric {
+        if ($metric->getName() === 'removed-metric') {
+            return null;  // drop this metric
+        }
+        return $metric;
+    },
+]);
+```
+
+**Symfony** (uses service ID, not a closure):
+
+```yaml
+sentry:
+  options:
+    enable_metrics: true
+    before_send_metric: 'App\Sentry\BeforeSendMetricCallback'
+```
+
+## Units
+
+```php
+use \Sentry\Metrics\Unit;
+
+// Duration
+Unit::nanosecond()    Unit::microsecond()   Unit::millisecond()
+Unit::second()        Unit::minute()        Unit::hour()
+Unit::day()           Unit::week()
+
+// Information
+Unit::bit()           Unit::byte()
+Unit::kilobyte()      Unit::megabyte()      Unit::gigabyte()
+Unit::terabyte()
+
+// Fraction
+Unit::ratio()         Unit::percent()
+
+// Dimensionless
+Unit::none()
+```
+
+## Flushing
+
+Metrics are buffered in a ring buffer (capacity: 1000 entries):
+
+| Context           | Behavior                                        |
+| ----------------- | ----------------------------------------------- |
+| PHP (CLI/scripts) | Call `\Sentry\traceMetrics()->flush()` manually |
+| Laravel           | Auto-flushed at end of each request or command  |
+| Symfony (HTTP)    | Auto-flushed on `kernel.terminate`              |
+| Symfony (console) | Auto-flushed on `console.terminate`             |
+
+**Buffer limit:** When more than 1000 metrics are buffered, the oldest entries are
+dropped. Flush periodically in high-volume scripts.
+
+## Auto-Flush Threshold
+
+Use `metric_flush_threshold` to automatically flush buffered metrics after N entries,
+without needing to call `flush()` manually:
+
+**PHP / Laravel:**
+
+```php
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'metric_flush_threshold' => 500,  // flush automatically after 500 metrics
+]);
+```
+
+**Symfony:**
+
+```yaml
+sentry:
+  options:
+    metric_flush_threshold: 500
+```
+
+This is useful in CLI scripts or workers that emit metrics continuously.
+The threshold triggers a flush mid-process so the buffer never fills to its 1000-entry
+cap.
+
+## Symfony Configuration
+
+```yaml
+sentry:
+  options:
+    enable_metrics: true # default: true
+    attach_metric_code_locations: true # attach file/line info
+    metric_flush_threshold: 500 # auto-flush after N metrics (optional)
+    before_send_metric: 'App\Sentry\BeforeSendMetricCallback'
+```
+
+## Automatically Added Attributes
+
+Every metric receives these automatically:
+
+| Attribute                                | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `sentry.environment`                     | Environment from SDK config                          |
+| `sentry.release`                         | Release from SDK config                              |
+| `sentry.sdk.name` / `sentry.sdk.version` | SDK metadata                                         |
+| `server.address`                         | Server hostname                                      |
+| `user.id`, `user.name`, `user.email`     | Active scope user (only if `send_default_pii: true`) |
+
+## Best Practices
+
+- Keep attribute cardinality low — avoid user IDs, UUIDs, or timestamps as attribute
+  values
+- Use `distribution` over `gauge` when you need percentile analysis (p90, p99)
+- Prefix metric names with your service: `"payments.charge_time"` not `"charge_time"`
+- In high-throughput scripts, flush periodically to prevent the buffer from dropping old
+  entries
+- Laravel closures in `config/sentry.php` may cause issues with `config:cache` — see
+  [Laravel closures config docs](https://docs.sentry.io/platforms/php/guides/laravel/configuration/laravel-options/#closures-and-config-caching)
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                                       |
+| ------------------------------------------- | ------------------------------------------------------------------------------ |
+| Metrics not appearing                       | Verify SDK version meets minimum; check `enable_metrics` is `true`             |
+| Metrics being dropped                       | Buffer cap is 1000 — flush periodically with `\Sentry\traceMetrics()->flush()` |
+| No percentiles in Sentry UI                 | Switch from `gauge` to `distribution` — gauges do not support percentiles      |
+| High cardinality warning                    | Reduce attribute values — avoid per-user or per-request identifiers            |
+| Old `\Sentry\metrics()` calls doing nothing | Migrate to `\Sentry\traceMetrics()` — the old API is fully deprecated          |

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

@@ -0,0 +1,115 @@
+# Profiling — Sentry PHP SDK
+
+> Requires the **Excimer** PHP extension (Linux/macOS only — Windows not supported)
+
+## Prerequisites
+
+**Excimer extension** must be installed:
+
+```bash
+# Linux (recommended)
+apt-get install php-excimer
+
+# PECL
+pecl install excimer
+
+# Enable (if needed)
+phpenmod -s fpm excimer
+```
+
+Excimer requires PHP 7.2+ and does **not** support Windows.
+
+## Version Requirements
+
+| Framework  | Min SDK Version                 |
+| ---------- | ------------------------------- |
+| PHP (base) | `sentry/sentry` ≥ 3.15.0        |
+| Laravel    | `sentry/sentry-laravel` ≥ 3.3.0 |
+| Symfony    | `sentry/sentry-symfony` ≥ 4.7.0 |
+
+## Configuration
+
+Profiling requires `traces_sample_rate > 0`. `profiles_sample_rate` is relative to
+`traces_sample_rate`.
+
+### PHP (base SDK)
+
+```php
+\Sentry\init([
+    'dsn' => '___PUBLIC_DSN___',
+    'traces_sample_rate' => 1.0,
+    'profiles_sample_rate' => 1.0,  // relative to traces_sample_rate
+]);
+```
+
+### Laravel (`config/sentry.php`)
+
+```php
+return [
+    'dsn' => env('SENTRY_LARAVEL_DSN', env('SENTRY_DSN')),
+    'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE') === null ? null : (float) env('SENTRY_TRACES_SAMPLE_RATE'),
+    'profiles_sample_rate' => env('SENTRY_PROFILES_SAMPLE_RATE') === null ? null : (float) env('SENTRY_PROFILES_SAMPLE_RATE'),
+];
+```
+
+`.env`:
+
+```bash
+SENTRY_TRACES_SAMPLE_RATE=1.0
+SENTRY_PROFILES_SAMPLE_RATE=1.0
+```
+
+### Symfony (`config/packages/sentry.yaml`)
+
+```yaml
+sentry:
+  options:
+    traces_sample_rate: 1.0
+    profiles_sample_rate: 1.0
+```
+
+## How `profiles_sample_rate` Works
+
+`profiles_sample_rate` is a **fraction of already-sampled transactions**, not of all
+requests:
+
+```
+Effective profiling rate = traces_sample_rate × profiles_sample_rate
+
+Examples:
+  traces_sample_rate: 1.0, profiles_sample_rate: 1.0  → 100% of requests profiled
+  traces_sample_rate: 0.5, profiles_sample_rate: 0.5  → 25% of requests profiled
+  traces_sample_rate: 0.1, profiles_sample_rate: 1.0  → 10% of requests profiled
+```
+
+## Reducing Latency Impact
+
+Profiling data is sent to Sentry after generating the response, not before:
+
+- **Laravel (FastCGI):** Uses terminable middleware — data sent **after** response is
+  dispatched
+- **Symfony (FastCGI):** Uses `kernel.terminate` event — same behavior
+- **Non-FastCGI servers:** Use a local [Relay](https://docs.sentry.io/product/relay/)
+  instance:
+
+```
+PHP App → local Relay (127.0.0.1) → Sentry Cloud
+```
+
+## Best Practices
+
+- Start with `profiles_sample_rate: 1.0` in development to verify setup
+- In production, reduce `traces_sample_rate` (e.g., `0.1`) — profiling follows
+  automatically
+- Profiling has no meaningful overhead on Linux with Excimer; Relay is only needed to
+  avoid latency on non-FastCGI servers
+- Profiles are capped at **30 seconds** per transaction
+
+## Troubleshooting
+
+| Issue                                | Solution                                                                            |
+| ------------------------------------ | ----------------------------------------------------------------------------------- |
+| No profiles appearing                | Verify Excimer is installed (`php -m \| grep excimer`) and `traces_sample_rate > 0` |
+| `profiles_sample_rate has no effect` | Check SDK version meets minimum requirement                                         |
+| Windows deployment                   | Profiling is not supported on Windows — use Linux or macOS                          |
+| High latency from profiling          | Use FastCGI (terminable middleware) or deploy a local Relay instance                |