@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,234 @@
+# Logging — Sentry Python SDK
+
+> Minimum SDK: `sentry-sdk` 2.35.0+ for structured Sentry Logs (`enable_logs=True`)
+
+## Two Logging Systems
+
+| System                           | Produces                                              | Requires                                   |
+| -------------------------------- | ----------------------------------------------------- | ------------------------------------------ |
+| **Sentry Structured Logs**       | Searchable log records in Sentry Logs UI              | `enable_logs=True` + `sentry_sdk.logger.*` |
+| **LoggingIntegration (classic)** | Breadcrumbs and/or error events from stdlib `logging` | Auto-enabled by default                    |
+
+These run simultaneously.
+They are **not** mutually exclusive.
+
+## Configuration
+
+```python
+import sentry_sdk
+from sentry_sdk.integrations.logging import LoggingIntegration
+import logging
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    enable_logs=True,                    # required for structured Sentry Logs
+    integrations=[
+        LoggingIntegration(
+            sentry_logs_level=logging.INFO,   # stdlib records → Sentry Logs (requires enable_logs=True)
+            level=logging.INFO,               # stdlib records → breadcrumbs
+            event_level=logging.ERROR,        # stdlib records → Sentry error events
+        ),
+    ],
+)
+```
+
+### `LoggingIntegration` parameters
+
+| Parameter           | Default | Effect                                                                  |
+| ------------------- | ------- | ----------------------------------------------------------------------- |
+| `sentry_logs_level` | `INFO`  | Records ≥ level → **structured Sentry Logs** (needs `enable_logs=True`) |
+| `level`             | `INFO`  | Records ≥ level → **breadcrumbs** (attached to next error event)        |
+| `event_level`       | `ERROR` | Records ≥ level → standalone **Sentry error events**                    |
+
+## Code Examples
+
+### Sentry Structured Logs — direct API
+
+```python
+import sentry_sdk
+from sentry_sdk import logger as sentry_logger
+
+sentry_sdk.init(dsn="...", enable_logs=True)
+
+sentry_logger.trace("Starting database connection {database}", database="users")
+sentry_logger.debug("Cache miss for user {user_id}", user_id=123)
+sentry_logger.info("Updated global cache")
+sentry_logger.warning("Rate limit reached for endpoint {endpoint}", endpoint="/api/results/")
+sentry_logger.error(
+    "Failed to process payment. Order: {order_id}. Amount: {amount}",
+    order_id="or_2342",
+    amount=99.99,
+)
+sentry_logger.fatal("Database {database} connection pool exhausted", database="users")
+```
+
+Template `{attribute_name}` placeholders become **individually searchable attributes**
+in the Sentry Logs UI.
+
+### Extra structured attributes
+
+```python
+from sentry_sdk import logger as sentry_logger
+
+sentry_logger.error(
+    "Payment processing failed",
+    attributes={
+        "payment.provider": "stripe",
+        "payment.method": "credit_card",
+        "payment.currency": "USD",
+        "user.subscription_tier": "premium",
+    },
+)
+```
+
+### stdlib `logging` → Sentry Logs
+
+```python
+import logging
+import sentry_sdk
+from sentry_sdk.integrations.logging import LoggingIntegration
+
+sentry_sdk.init(
+    dsn="...",
+    enable_logs=True,
+    integrations=[LoggingIntegration(sentry_logs_level=logging.INFO)],
+)
+
+logger = logging.getLogger(__name__)
+logger.info("User signed in", extra={"user_id": 42, "region": "eu-west-1"})
+# extra fields become searchable attributes on the log entry
+```
+
+### Loguru integration
+
+```python
+import sentry_sdk
+from loguru import logger
+
+# LoguruIntegration auto-activates when loguru is installed
+sentry_sdk.init(dsn="...", enable_logs=True)
+
+logger.info("Application started")
+logger.error("Critical failure in payment module")
+```
+
+Manual configuration for full control:
+
+```python
+import sentry_sdk
+from sentry_sdk.integrations.loguru import LoguruIntegration, LoggingLevels
+
+sentry_sdk.init(
+    dsn="...",
+    enable_logs=True,
+    integrations=[
+        LoguruIntegration(
+            sentry_logs_level=LoggingLevels.INFO.value,    # → structured logs
+            level=LoggingLevels.INFO.value,                # → breadcrumbs
+            event_level=LoggingLevels.ERROR.value,         # → error events
+        )
+    ],
+)
+```
+
+### `before_send_log` hook — filter and modify
+
+```python
+import sentry_sdk
+from typing import Optional
+
+def before_log(log, hint) -> Optional[dict]:
+    # Drop all INFO logs
+    if log["severity_text"] == "info":
+        return None
+    # Add custom attribute
+    log["attributes"]["processed_by"] = "before_log"
+    return log
+
+sentry_sdk.init(dsn="...", enable_logs=True, before_send_log=before_log)
+```
+
+### `Log` object schema
+
+| Key               | Type          | Description                                                            |
+| ----------------- | ------------- | ---------------------------------------------------------------------- |
+| `severity_text`   | `str`         | `"trace"` / `"debug"` / `"info"` / `"warning"` / `"error"` / `"fatal"` |
+| `severity_number` | `int`         | 1–24 (OpenTelemetry spec)                                              |
+| `body`            | `str`         | Rendered message string                                                |
+| `attributes`      | `dict`        | Custom key-value pairs                                                 |
+| `time_unix_nano`  | `int`         | Unix epoch in nanoseconds                                              |
+| `trace_id`        | `str \| None` | Associated trace ID                                                    |
+
+### Suppress noisy loggers
+
+Events/breadcrumbs and Sentry Logs have **separate** ignore lists.
+`ignore_logger()` only suppresses breadcrumbs and error events — it does **not** affect
+Sentry Logs. This means framework loggers silenced for events (e.g. `django.server`) can
+still be captured as Sentry Logs.
+
+```python
+from sentry_sdk.integrations.logging import (
+    ignore_logger,
+    ignore_logger_for_sentry_logs,
+    unignore_logger,
+    unignore_logger_for_sentry_logs,
+)
+
+# Suppress breadcrumbs and error events only (Sentry Logs still captured)
+ignore_logger("a.spammy.logger")
+ignore_logger("boto3.*")   # glob patterns supported
+
+# Suppress Sentry Logs only (breadcrumbs and error events still captured)
+ignore_logger_for_sentry_logs("a.noisy.logger")
+
+# Reverse a previous ignore
+unignore_logger("a.spammy.logger")
+unignore_logger_for_sentry_logs("a.noisy.logger")
+```
+
+| Helper                                  | Affects                                    |
+| --------------------------------------- | ------------------------------------------ |
+| `ignore_logger(name)`                   | Breadcrumbs + error events only            |
+| `ignore_logger_for_sentry_logs(name)`   | Sentry Logs only                           |
+| `unignore_logger(name)`                 | Reverses `ignore_logger()`                 |
+| `unignore_logger_for_sentry_logs(name)` | Reverses `ignore_logger_for_sentry_logs()` |
+
+## Decision Table
+
+| Goal                                            | Tool                                                              |
+| ----------------------------------------------- | ----------------------------------------------------------------- |
+| Searchable structured records in Sentry Logs UI | `sentry_sdk.logger.*` + `enable_logs=True`                        |
+| Bridge existing stdlib `logging` to Sentry Logs | `LoggingIntegration(sentry_logs_level=...)` + `enable_logs=True`  |
+| Bridge loguru to Sentry Logs                    | `LoguruIntegration(sentry_logs_level=...)` + `enable_logs=True`   |
+| Breadcrumbs for error context                   | `LoggingIntegration(level=logging.INFO)` (default)                |
+| Auto-create error events from log calls         | `LoggingIntegration(event_level=logging.ERROR)` (default)         |
+| Drop/modify a log before sending                | `before_send_log` callback                                        |
+| Suppress a logger from breadcrumbs/events only  | `ignore_logger(name)`                                             |
+| Suppress a logger from Sentry Logs only         | `ignore_logger_for_sentry_logs(name)`                             |
+| Re-enable a previously ignored logger           | `unignore_logger(name)` / `unignore_logger_for_sentry_logs(name)` |
+
+## Automatically Added Attributes
+
+Every log record receives these automatically:
+
+| Attribute                                | Source                      |
+| ---------------------------------------- | --------------------------- |
+| `sentry.environment`                     | `init(environment=...)`     |
+| `sentry.release`                         | `init(release=...)`         |
+| `sentry.sdk.name` / `sentry.sdk.version` | SDK metadata                |
+| `server.address`                         | hostname                    |
+| `sentry.message.template`                | Original template string    |
+| `sentry.message.parameter.*`             | Template placeholder values |
+| `user.id`, `user.name`, `user.email`     | Active scope user (if set)  |
+
+## Troubleshooting
+
+| Issue                                                                | Solution                                                                                                                       |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `sentry_sdk.logger.*` calls have no effect                           | Ensure `enable_logs=True` is set in `sentry_sdk.init()`                                                                        |
+| stdlib logs not appearing as Sentry Logs                             | Set `sentry_logs_level` in `LoggingIntegration` and `enable_logs=True`                                                         |
+| Logger’s own level filters out records                               | SDK respects the logger’s configured level — set it to `logging.INFO` or lower                                                 |
+| Too many log records hitting quota                                   | Use `before_send_log` to filter by severity or attribute                                                                       |
+| Loguru not auto-activating                                           | Verify `loguru` is installed; or add `LoguruIntegration()` explicitly                                                          |
+| `ignore_logger()` still sending Sentry Logs                          | Expected — `ignore_logger()` only suppresses breadcrumbs/events; use `ignore_logger_for_sentry_logs()` to suppress Sentry Logs |
+| Framework logger (e.g. `django.server`) not appearing in Sentry Logs | It may be in the default Sentry Logs ignore list; call `unignore_logger_for_sentry_logs("django.server")`                      |

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

@@ -0,0 +1,154 @@
+# Metrics — Sentry Python SDK
+
+> Minimum SDK: `sentry-sdk` 2.44.0+
+
+## Overview
+
+`sentry_sdk.metrics` provides custom counters, gauges, and distributions.
+Metrics are enabled by default — no extra `init()` flag needed.
+
+## Metric Types
+
+| Type         | API                      | Use for                                                     |
+| ------------ | ------------------------ | ----------------------------------------------------------- |
+| Counter      | `metrics.count()`        | Event occurrences, request counts                           |
+| Distribution | `metrics.distribution()` | Latencies, sizes — supports p50/p90/p95/p99                 |
+| Gauge        | `metrics.gauge()`        | Current values (min, max, avg, sum, count — no percentiles) |
+
+## Configuration
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    # No extra flag — metrics are on by default
+)
+```
+
+Optional `before_send_metric` hook:
+
+```python
+from typing import Optional
+
+def before_metric(metric, hint) -> Optional[dict]:
+    if metric["name"] == "noisy-metric":
+        return None                          # drop this metric
+    metric["attributes"]["env"] = "prod"    # add attribute
+    return metric
+
+sentry_sdk.init(dsn="...", before_send_metric=before_metric)
+```
+
+## Code Examples
+
+### Counter — event occurrences
+
+```python
+import sentry_sdk
+
+sentry_sdk.metrics.count(
+    "button_click",
+    1,
+    attributes={
+        "browser": "Firefox",
+        "page": "/checkout",
+    },
+)
+
+# Increment by more than 1
+sentry_sdk.metrics.count("api.request", 5, attributes={"endpoint": "/v2/users"})
+```
+
+### Distribution — percentile analysis
+
+Best for latencies, response sizes, durations where p50/p90/p99 matter:
+
+```python
+import time
+import sentry_sdk
+
+start = time.time()
+process_order(order)
+duration_ms = (time.time() - start) * 1000
+
+sentry_sdk.metrics.distribution(
+    "order.processing_time",
+    duration_ms,
+    unit="millisecond",
+    attributes={"order.type": "subscription", "region": "eu"},
+)
+```
+
+### Gauge — space-efficient aggregates
+
+Use when high cardinality is a concern; no percentile support:
+
+```python
+import sentry_sdk
+
+sentry_sdk.metrics.gauge(
+    "queue.depth",
+    len(pending_jobs),
+    unit="none",
+    attributes={"queue": "billing"},
+)
+```
+
+### All four attribute value types
+
+```python
+sentry_sdk.metrics.count(
+    "api.request",
+    1,
+    attributes={
+        "endpoint": "/v2/users",     # str
+        "method": "POST",
+        "success": True,             # bool
+        "status_code": 201,          # int
+        "latency": 0.042,            # float
+    },
+)
+```
+
+### Unit strings
+
+| Category      | Values                                                                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------- |
+| Time          | `"nanosecond"`, `"microsecond"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"` |
+| Data          | `"bit"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`                             |
+| Fractions     | `"ratio"`, `"percent"`                                                                                |
+| Dimensionless | `"none"` (default when omitted)                                                                       |
+
+### `before_send_metric` — `Metric` schema
+
+| Key          | Type          | Description                                |
+| ------------ | ------------- | ------------------------------------------ |
+| `name`       | `str`         | Metric identifier                          |
+| `type`       | `str`         | `"counter"` / `"gauge"` / `"distribution"` |
+| `value`      | `float`       | Numeric measurement                        |
+| `unit`       | `str \| None` | Unit string                                |
+| `attributes` | `dict`        | Custom key-value pairs                     |
+| `timestamp`  | `float`       | Epoch seconds                              |
+| `trace_id`   | `str \| None` | Associated trace ID                        |
+| `span_id`    | `str \| None` | Active span ID                             |
+
+## Best Practices
+
+- Keep attribute cardinality low — avoid user IDs, UUIDs, or timestamps as attribute
+  values
+- Use `distribution` over `gauge` when you need percentile analysis
+- Prefix metric names with your service name: `"payments.charge_time"` not
+  `"charge_time"`
+- Use standard unit strings — Sentry renders them in the UI with proper labels
+- Metrics are buffered and flushed periodically — avoid using them for critical alerting
+  requiring sub-second latency
+
+## Troubleshooting
+
+| Issue                       | Solution                                                                           |
+| --------------------------- | ---------------------------------------------------------------------------------- |
+| Metrics not appearing       | Verify SDK version ≥ 2.44.0; check `debug=True` output                             |
+| Metric dropped silently     | Check `before_send_metric` hook; verify metric name contains no special characters |
+| High cardinality warning    | Reduce attribute values — avoid per-user or per-request identifiers                |
+| No percentiles in Sentry UI | Switch from `gauge` to `distribution` — gauges do not support percentiles          |

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

@@ -0,0 +1,120 @@
+# Profiling — Sentry Python SDK
+
+> Minimum SDK: `sentry-sdk` 1.18.0+ (transaction-based); 2.24.1+ (continuous /
+> session-based)
+
+## Configuration
+
+| Option                        | API                        | Min SDK | Purpose                                                               |
+| ----------------------------- | -------------------------- | ------- | --------------------------------------------------------------------- |
+| `profiles_sample_rate`        | Transaction-based (legacy) | 1.18.0  | Fraction of transactions to profile; relative to `traces_sample_rate` |
+| `profile_session_sample_rate` | Continuous (new)           | 2.24.1  | Fraction of sessions to profile; evaluated once per process start     |
+| `profile_lifecycle`           | Continuous (new)           | 2.24.1  | `"trace"` = SDK auto-manages; `"manual"` = explicit start/stop        |
+
+Profiling requires `traces_sample_rate > 0` (or `traces_sampler`) to be set.
+
+## API Comparison
+
+|                  | `profiles_sample_rate` (transaction-based) | `profile_session_sample_rate` (continuous) |
+| ---------------- | ------------------------------------------ | ------------------------------------------ |
+| **Min SDK**      | 1.18.0                                     | 2.24.1                                     |
+| **Evaluated**    | Per transaction                            | Once per process/deployment start          |
+| **Max duration** | 30 seconds per transaction                 | Unlimited                                  |
+| **Requires**     | `traces_sample_rate`                       | `profile_lifecycle` + `traces_sample_rate` |
+| **Use when**     | Simple setup, short-lived transactions     | Long-running apps, background services     |
+
+## Code Examples
+
+### Transaction-based profiling (simple / legacy)
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    traces_sample_rate=1.0,
+    profiles_sample_rate=1.0,   # relative to traces_sample_rate
+    # e.g. profiles_sample_rate=0.5 → profiles 50% of sampled transactions
+)
+```
+
+Profiles start when the transaction starts and stop when it ends or after **30
+seconds**, whichever is first.
+
+### Continuous profiling — auto-managed (`profile_lifecycle="trace"`)
+
+SDK automatically starts and stops the profiler around active spans.
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    traces_sample_rate=1.0,
+    profile_session_sample_rate=1.0,   # evaluated once at process start
+    profile_lifecycle="trace",          # SDK manages start/stop automatically
+)
+```
+
+### Continuous profiling — manual control (`profile_lifecycle="manual"`)
+
+Full programmatic control over profiler lifetime.
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    traces_sample_rate=1.0,
+    profile_session_sample_rate=1.0,
+    profile_lifecycle="manual",
+)
+
+# Application startup
+sentry_sdk.profiler.start_profiler()
+
+# ... application runs ...
+
+# Application shutdown
+sentry_sdk.profiler.stop_profiler()
+```
+
+### Production-recommended setup (continuous)
+
+```python
+import sentry_sdk
+import signal
+
+sentry_sdk.init(
+    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
+    environment="production",
+    release="my-app@2.0.0",
+    traces_sample_rate=0.1,             # sample 10% of transactions
+    profile_session_sample_rate=1.0,    # profile all sampled sessions
+    profile_lifecycle="trace",
+)
+```
+
+## Best Practices
+
+- Use continuous profiling (`profile_session_sample_rate` + `profile_lifecycle`) for
+  long-running services and production workloads
+- Use transaction-based (`profiles_sample_rate`) for simple setups or short-lived
+  scripts
+- `profile_session_sample_rate` is evaluated **once at process start** — changing it
+  requires a restart
+- `"trace"` and `"manual"` profile lifecycles are mutually exclusive; do not mix them
+- Reduce `traces_sample_rate` in production (e.g., `0.1`) — profiling overhead is low
+  but not zero
+- Python’s GIL means the profiler captures the thread holding the GIL; async I/O wait
+  time appears as near-zero CPU — this is expected
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                                      |
+| ------------------------------------------- | ----------------------------------------------------------------------------- |
+| No profiles appearing                       | Verify `traces_sample_rate > 0` and profiling options are set correctly       |
+| Profiles cut off at 30s                     | Switch to continuous profiling (`profile_session_sample_rate`)                |
+| `profile_session_sample_rate` has no effect | Check SDK version is ≥ 2.24.1; ensure `profile_lifecycle` is also set         |
+| Profiler not stopping                       | In `"manual"` mode, call `sentry_sdk.profiler.stop_profiler()` on shutdown    |
+| Async functions show no CPU time            | Expected — Python profiler only captures GIL-holding time, not async I/O wait |