@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/concepts/ai-monitoring.md

@@ -0,0 +1,131 @@
+# AI / Agent Monitoring — What & Why
+
+## What it is
+
+Tracing specialized for LLM apps.
+LLM calls, agent runs, tool calls, and agent-to-agent handoffs are captured as
+`gen_ai.*` spans carrying model, token usage, cost, and latency.
+It is built on [tracing](tracing.md), so tracing must be on
+(`tracesSampleRate`/`traces_sample_rate` > 0) — without spans there is nothing to attach
+`gen_ai` data to.
+
+Auto-instrumented for detected AI SDKs on **JavaScript, Python, and Laravel** (OpenAI,
+Anthropic, Vercel AI, LangChain/LangGraph, Google GenAI, HuggingFace, Pydantic AI, and
+Laravel AI; `litellm` needs explicit registration).
+Every other platform is manual `gen_ai.*` instrumentation, or unsupported — the platform
+`index.md` says which.
+
+**Auto-instrumentation is runtime-dependent, not just language-dependent.** It patches
+the AI client at require/import time, so it only applies on a patchable runtime.
+On workerd (Cloudflare Workers) and in browser/client-side code there is nothing to
+patch — those need build-time instrumentation (the Cloudflare Vite plugin) or a manual
+client wrapper (`Sentry.instrumentOpenAiClient` and friends).
+Check the platform’s `ai-monitoring.md` before assuming “it’s JavaScript, so it’s
+automatic”.
+
+## What the artifact shows
+
+A trace _is_ the agent run: a `gen_ai.invoke_agent` span parents the `gen_ai.chat` (LLM
+call), `gen_ai.execute_tool`, and `gen_ai.handoff` children it triggered.
+Read cost and latency off the child spans’ token attributes.
+Two views surface it: the **AI Agents** dashboard and **Explore > Conversations**.
+
+The span `op` is `gen_ai.{operation}` — `chat`, `embeddings`, `generate_content`,
+`text_completion` for calls, plus `invoke_agent`, `execute_tool`, `handoff`. The span
+**name** repeats the operation with its subject: `chat gpt-4o`,
+`invoke_agent Weather Agent`, `execute_tool get_weather`,
+`handoff from triage to billing`. Attributes accept primitives only; arrays/objects are
+JSON-stringified. The canonical attribute set lives under
+`references/semantics/gen_ai.md` in skills that hydrate semantic conventions (see the
+instrument skill’s Semantic conventions list).
+The SDK docs can lag, and deprecated attributes are omitted from that reference on
+purpose.
+
+## Conversations
+
+Conversations groups spans by `gen_ai.conversation.id` into a chat-style timeline.
+A conversation can span multiple traces (a page refresh mid-chat), and one trace can
+hold spans from multiple conversations — the two are independent.
+
+**Conversation ID format matters:** use a short, opaque identifier — alphanumeric with
+dashes or underscores only (a UUID, or a prefixed id like `conv_5j66Up…`). Never use a
+URL, email, or other free-form text: Sentry uses the id as a URL path segment, so a
+value containing a slash breaks Conversations for that session.
+Some integrations infer the id automatically (Python OpenAI Agents, Node OpenAI, Laravel
+AI agents using `Conversational` + `RemembersConversations`); everything else sets it
+explicitly. The view also needs input/output capture and gen_ai span streaming (both on
+by default on recent JS/Python SDKs; Laravel AI spans are emitted directly) or it
+renders empty, and a `setUser`/`set_user` call to populate the User column where
+supported.
+
+## Token accounting (avoid negative costs)
+
+Sentry computes cost from token attributes, and cached/reasoning counts are **subsets**
+of the totals, not separate buckets: `gen_ai.usage.input_tokens` already includes
+`.input_tokens.cached`, and `gen_ai.usage.output_tokens` already includes
+`.output_tokens.reasoning`. Reporting a subset larger than its total makes Sentry
+subtract past zero and show a negative cost.
+
+## Input/output message shape
+
+`gen_ai.input.messages` and `gen_ai.output.messages` are JSON-stringified arrays of
+`{role, parts}`, where each part is `{type, content}` — part types include `text`,
+`reasoning`, `tool_call`, and `tool_call_response`.
+
+Extended thinking (Anthropic `thinking`, Gemini `thought`, DeepSeek `reasoning_content`)
+belongs in a **`reasoning` part, never folded into a `text` part**: Sentry surfaces
+reasoning separately and filters it out of the user-facing Conversations view, so
+thinking passed as `text` shows up as if the model said it.
+When prior thinking is fed back into a multi-turn request, keep those same `reasoning`
+parts in the assistant messages inside `gen_ai.input.messages`.
+
+The system prompt is separate from the messages — it goes in
+`gen_ai.system_instructions` — as is the tool catalog offered to the model,
+`gen_ai.tool.definitions`. Both are model input and carry the same PII weight as the
+messages.
+
+## PII
+
+Prompts and model outputs are user content and are **likely PII**. JavaScript captures
+input/output by default (governed by `dataCollection.genAI`); Python gates it behind
+`send_default_pii=True`; Laravel gates it behind `SENTRY_SEND_DEFAULT_PII=true`. Confirm
+the privacy policy and regulations allow it and **ask the user before enabling capture**
+— see [data-scrubbing.md](data-scrubbing.md).
+
+## Setup essentials
+
+- Tracing must be on; then detect the AI SDK and let auto-instrumentation handle it
+  (JS/Python/Laravel AI), or instrument `gen_ai.*` spans manually.
+- Sample AI traces at **100%** — see Sampling below.
+- Set a `gen_ai.conversation.id` wherever multi-turn chats need grouping.
+
+## Sampling
+
+An agent run is one span tree and the sampling decision is made at the **root**;
+children inherit it unconditionally.
+Drop the root and every `gen_ai` child goes with it — so at any rate below 1.0 you lose
+whole agent runs, not a fraction of each.
+Which root depends on the app:
+
+- **The `gen_ai` span is itself the root** (cron job, queue consumer, CLI): the sampler
+  function sees the `gen_ai.*` op directly — match on it and return 1.0.
+- **The `gen_ai` spans hang off an HTTP transaction** (most web apps): the sampler never
+  runs for them, because the request was already sampled before any AI code executed.
+  Keep the AI-serving routes at 1.0 instead.
+
+If AI is the core product, skip the sampler and keep tracing at 1.0 outright.
+
+**Read the app’s current rate before changing it, and ask.** If tracing is below 1.0
+with no sampler configured, say what the current rate is and what a dropped root costs,
+then wait for an answer — raising trace volume is the user’s cost decision, the same as
+the PII gate above.
+
+When 100% tracing isn’t affordable, metrics and logs are sampled independently of
+traces: emit token counts and per-call log records on every LLM call to keep full
+cost/usage coverage alongside sampled traces.
+
+## Related
+
+- [`tracing.md`](tracing.md) — AI monitoring is tracing; spans are the substrate.
+- [`data-scrubbing.md`](data-scrubbing.md) — prompt/output capture is the PII decision.
+- [`reduce-volume.md`](reduce-volume.md) — the volume/cost tradeoff across signals.

package/skills/sentry/references/concepts/choosing-a-signal.md

@@ -0,0 +1,78 @@
+# Choosing a signal
+
+Sentry captures several distinct **signals**. They are not interchangeable.
+Picking the right one is the single most important instrumentation decision, and the
+wrong one is the most common waste of quota.
+Decide by the question you are trying to answer.
+
+| You want to know…                                                                                   | Reach for          | Why                                                                                                                         |
+| --------------------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| _Something broke — what, where, and why?_                                                           | **Error**          | An exception/crash with a stack trace, grouped into an issue. The default, always-on signal.                                |
+| _Why is this slow? What’s the chain of calls? Did the request flow through the system as expected?_ | **Span / trace**   | Timing and structure of a request across services (distributed tracing). Powers performance-issue detection (N+1, slow DB). |
+| _What happened leading up to this?_                                                                 | **Log**            | A searchable, structured, trace-connected record of discrete events. Narrative context, not timing.                         |
+| _How many / how much / what’s the trend over time?_                                                 | **Metric**         | An aggregate number (counter / gauge / distribution) for a KPI you watch and alert on.                                      |
+| _Which exact function/line is burning CPU?_                                                         | **Profile**        | Code-level sampling under a traced transaction. Requires tracing on.                                                        |
+| _What did the user actually see and do?_                                                            | **Session Replay** | A video-like reproduction of a frontend/mobile session around an error or UX problem.                                       |
+| _What does the user think went wrong?_                                                              | **User Feedback**  | A qualitative report from a human, linked to the surrounding context.                                                       |
+| _Did my scheduled job run on time?_                                                                 | **Cron monitor**   | Check-ins that detect missed, late, or failed recurring jobs.                                                               |
+
+Most of these signals carry the same **trace ID**, so once one surfaces a problem you
+can pivot to the others in the same request — the trace is the connective tissue that
+ties errors, spans, logs, replays, and metrics together for debugging.
+
+## Comparisons
+
+- **Error vs. log.** An exception your code can’t handle is an **error** (capture it as
+  one — it groups into an issue and gets a stack trace).
+  A noteworthy thing that happened but isn’t a failure is a **log**. Don’t log-spam
+  things that should be errors; don’t capture routine events as errors and pollute the
+  issue stream.
+- **Log vs. span.** A log answers _what happened_; a span answers _how long it took and
+  what it called_. If you find yourself logging start/end timestamps to measure
+  duration, you want a span instead.
+- **Span vs. metric.** A span is one sampled instance of an operation (great for “show me
+  a slow request”). An **Application Metric** is a numeric measurement aggregated over
+  all occurrences at query time (great for “alert when p95 latency exceeds 500ms”) and,
+  unlike a traditional metric, can carry high-cardinality attributes.
+- **Metric vs. counting events.** Don’t emit a custom metric for something Sentry already
+  derives from errors/spans (issue counts, throughput, latency percentiles, crash-free
+  rate). Reserve custom metrics for **business/operational KPIs** Sentry can’t see —
+  `checkout.failed`, `queue.depth`, `cache.hit_ratio`.
+- **Profile rides on tracing.** Profiling is not a standalone signal — it samples
+  _inside_ traced transactions.
+  Tracing must be on first.
+
+## What to instrument where
+
+- **Errors:** everywhere, always.
+  This is the baseline and the first thing to get working.
+- **Tracing:** the request **boundaries** first — incoming HTTP, outbound HTTP, DB /
+  cache / queue. Auto-instrumentation covers most of these once tracing is on.
+  Add custom spans only for meaningful business operations.
+- **Logging:** a few high-signal events per request with structured attributes — not a
+  firehose.
+- **Metrics:** a small, deliberate set of KPIs that map to a real decision or alert.
+- **Replay:** frontend (and mobile) only; high sampling on errors, low on normal
+  sessions.
+- **Crons:** every scheduled job whose silent failure would hurt.
+
+When the user is unsure, ask what question they’re trying to answer and map it with the
+table above. When they say “set it up properly” / “you pick the defaults,” lean on the
+recommended baseline: **errors + tracing at a modest sample rate + releases + source
+maps**, then add logs/replay/profiling as the use case warrants.
+
+## Cross-cutting concepts (not signals)
+
+These shape how the signals above behave and how you act on them — each has its own
+reference:
+
+- **Releases** — tie every event to a deployed version.
+  Unlocks regression detection, crash-free rates, suspect commits, and
+  resolve-in-next-release.
+- **Monitors → Issues → Alerts** — Sentry’s detection-and-response model.
+  _Monitors_ decide when a signal becomes an **issue**; _Alerts_ act on issues.
+- **Data scrubbing / PII** — what’s sensitive, and the defense-in-depth model for
+  keeping it out.
+- **Volume & cost** — what to keep vs.
+  drop, and where to sample.
+- **Search query language** — the `key:value` grammar shared by every query surface.

package/skills/sentry/references/concepts/crons.md

@@ -0,0 +1,50 @@
+# Cron / Scheduled-Job Monitoring — What & Why
+
+Monitoring for recurring jobs — cron jobs, scheduled tasks, queue workers.
+Sentry watches for runs that are **missed**, **late**, **timed out**, or **failed** and
+turns those into issues.
+It works via **check-ins**: the job reports `in_progress` when it starts and
+`ok`/`error` when it finishes; a run that never checks in (or checks in late) is flagged
+against the monitor’s schedule.
+
+Reach for it where **silent failure is dangerous** — a nightly billing run, a data sync,
+a backup — and “it didn’t run” is as bad as “it crashed.”
+
+## Why a cron issue often isn’t where you’d look
+
+- **A “missed” issue frequently isn’t in the job code.** Missed means no check-in
+  arrived in the expected window — commonly the **scheduler** (misconfigured, skipped,
+  never started the job), a **network** problem (outbound firewall, flaky connection),
+  or a timeout. Don’t assume the job body threw.
+- **The real exception is a separate error event on the same trace.** If the SDK is
+  configured, errors thrown during the run are captured as normal error events and tied
+  back to the check-in through the run’s trace — follow the trace from the cron issue to
+  find them.
+- **Issue creation is threshold-gated,** not per-failure: `failure_issue_threshold` (N
+  consecutive failures before an issue opens) and `recovery_threshold` (N consecutive
+  OKs before it resolves).
+  A single failure may not create an issue.
+- **Absence of alerts ≠ healthy.** A monitor broken for weeks gets auto-muted — it stops
+  producing issues and notifications while billing continues.
+  A silent monitor may be muted, not passing.
+
+## Setup essentials
+
+- **Monitor config is data** (server-side): the schedule (crontab — 5-field only — or
+  interval), the **`timezone`**, **`checkin_margin`** (how late counts as missed), and
+  **`max_runtime`** (how long counts as hung).
+  Set the last two to the job’s real timing — tight enough to catch a hang, loose enough
+  to avoid false alarms.
+- **Check-ins are code** (SDK-side).
+  Paths: the SDK **`withMonitor` / decorator** wrapper (cleanest when an SDK is present
+  — sends both start and outcome), an **HTTP check-in** (any language, ideal for shell
+  crontabs), or **`sentry-cli`** wrapping a shell command.
+  Wrap the **whole job** so both success and failure report; a bare heartbeat (single
+  `ok`/`error`) detects _missed_ but not _`max_runtime`_ timeouts.
+- **Use a stable, descriptive slug** (`nightly-invoice-sync`, not `job-1`) — it’s the
+  check-in key, so slug churn on every deploy orphans monitors.
+
+## Related
+
+- [`monitors.md`](monitors.md) — a cron monitor is one kind of Monitor that creates
+  issues.

package/skills/sentry/references/concepts/data-scrubbing.md

@@ -0,0 +1,43 @@
+# Data Scrubbing / PII — Strategy
+
+Controlling what personal or sensitive data reaches (and is stored by) Sentry — a common
+GDPR / PCI / SOC2 requirement, or just not wanting tokens in your error tracker.
+Treat as sensitive: emails, names, IPs, user IDs that map to people, full
+request/response **bodies**, **headers** (auth tokens, cookies, session IDs), query
+strings with tokens, passwords, and anything regulated.
+When in doubt, assume a field is sensitive.
+
+## Defense in depth — two layers, both
+
+1. **SDK-side (before data leaves the app)** — the strongest guarantee; data you never
+   send can’t leak.
+   - `sendDefaultPii` controls whether the SDK attaches request/user PII automatically
+     (default off).
+   - `beforeSend` / `beforeSendTransaction` hooks strip, redact, or drop fields on every
+     event.
+2. **Server-side (Sentry, the backstop)** — data-scrubbing rules scrub on ingest
+   (Safe/Sensitive field lists + an advanced selector rules engine).
+   On by default.
+
+Scrub at the earliest layer you can; keep the server-side rules as a backstop, because
+you’ll eventually capture something you didn’t anticipate.
+
+## AI/LLM attributes (`gen_ai.*`)
+
+**Prompt and completion attributes (`gen_ai.input.messages`, `gen_ai.output.messages`,
+`gen_ai.tool.call.*`, …) are not scrubbed by the default server-side rules.** Their
+capture is itself opt-in (only when PII capture is enabled), but _once captured they
+aren’t redacted_ — so if you instrument an LLM app, explicitly scrub them with an
+advanced rule (`$span.data.'<attribute>'`) or disable their capture.
+
+## Verify, don’t assume
+
+Trigger an event and confirm the sensitive fields are absent/redacted in the event
+detail. Logs and replay/screenshots are the easiest leaks — pair with
+[`logging.md`](logging.md) and [`session-replay.md`](session-replay.md).
+
+## Related
+
+- [`logging.md`](logging.md)
+- [`session-replay.md`](session-replay.md)
+- [`reduce-volume.md`](reduce-volume.md)

package/skills/sentry/references/concepts/errors.md

@@ -0,0 +1,40 @@
+# Error monitoring
+
+Unhandled exceptions and crashes — plus anything you send explicitly with
+`captureException` — grouped into **issues** with the context needed to fix them: a
+stack trace, breadcrumbs (the events leading up to the error), and request/user/release
+metadata. An issue is the unit you triage, assign, resolve, and link a fix to.
+
+## What an issue actually is
+
+- An **issue is a group of events** sharing a fingerprint (stack trace + exception
+  type/message), not a single occurrence.
+  Sentry surfaces one **representative event** — the one richest in context, which is
+  not necessarily the latest — so you reason about the group and drill into an event for
+  specifics.
+- **The cause isn’t always in the stack trace.** Suspect commits tie the issue to the
+  commit that likely introduced it, and a **trace-related issue** points to a
+  _different_ issue in the same request that may be the real origin — the crash you’re
+  looking at can be a downstream symptom.
+- **When one bug shows up as several issues (or several bugs as one), that’s a grouping
+  problem** — the fingerprint is tunable, not something to live with.
+
+## What makes an error actionable
+
+- **A readable stack trace** — minified JS or unsymbolicated native frames make an issue
+  nearly useless; readable frames depend on source maps (JS) or debug symbols
+  (native/mobile) being uploaded.
+- **`release` and `environment` tags** — unlock regression detection,
+  resolve-in-next-release, and separating prod from staging noise.
+  Set them from the start.
+- **Context, not PII** — tags, user IDs, and breadcrumbs make an error diagnosable;
+  scrub sensitive data before it leaves the app
+  ([`data-scrubbing.md`](data-scrubbing.md)).
+- **Not routine control flow** — expected 404s and validation rejections aren’t errors;
+  capturing them buries the real problems.
+
+## Related
+
+- [`tracing.md`](tracing.md)
+- [`releases.md`](releases.md)
+- [`data-scrubbing.md`](data-scrubbing.md)

package/skills/sentry/references/concepts/logging.md

@@ -0,0 +1,85 @@
+# Structured Logging — What & Why
+
+Structured, trace-connected logs: each log carries a level, a message, and key/value
+**attributes**, and Sentry automatically attaches the trace ID so it correlates with the
+spans, errors, and other logs in the same request.
+Logs record the context and decisions that explain _what happened_ during execution —
+the context a stack trace alone can’t give.
+
+## When to reach for a log
+
+- **Not for timing or flow** — that’s a span / trace.
+- **Not for unexpected critical failures** — that’s an error (it groups into an issue
+  with a stack trace).
+  A log is for noteworthy-but-handled events: a runtime decision (a feature flag served
+  a different path), an audit or business event (created / updated / deleted /
+  permission changed), a summary of a multi-step operation, or context around a
+  _recoverable_ failure (a retry before the final attempt, a non-critical upstream that
+  failed).
+- **Not for every function call** — high-frequency line-spam is noise and billed volume.
+  A log should answer a concrete production question and still be useful if emitted
+  thousands of times.
+
+## Structure
+
+- **Consistent key/value attributes, not interpolation.** Namespace them
+  (`myapp.<domain>.<field>`) and reuse field names across the app so events can be
+  searched and aggregated.
+  A good log answers who did it, what happened, and when.
+  Attributes are what you query — `severity:error`, `trace_id:...`, `user.id:...` with
+  `AND`/`OR` (the level field is `severity` in search); raw text search matches only the
+  message, so anything you want to filter on must be an attribute.
+- **Agree conventions once, across services.** Decide the attribute namespacing,
+  event-name phrasing, and levels up front so logs from every language and service can
+  be searched and correlated together.
+  On both sides of a call that propagates trace headers (`baggage` / `sentry-trace`),
+  use the same attribute names so a single trace reads coherently across services.
+- **Accumulate context as a request evolves** — early logs may carry only request info;
+  later ones add the authenticated user, feature flags, and outcomes.
+  Prefer the SDK’s `set_user` over repeating a user ID on every log.
+- **Levels carry meaning:** `debug` (temporary diagnostics), `info` (normal events),
+  `warn` (recoverable but notable), `error` (handled failures).
+  For anything critical — or that should group into an issue with a stack trace —
+  capture a real Sentry **error** event, not a log.
+  On the `error`-level logs you do keep, include what explains the failure: retry count,
+  the response status and key non-sensitive request/response fields for external calls,
+  and the runtime decisions that led there.
+- **Log fields, not whole objects** — pick the fields you’ll query and omit absent
+  optional attributes rather than logging `null`.
+- Sentry can integrate with an existing logging abstraction (Monolog, slog, Rails
+  logger, Pino/console) or you can call the SDK’s logger directly.
+
+## Don’t log sensitive data
+
+Assume anything logged will be read by another human.
+Never log passwords, tokens, or API keys; prefer opaque user IDs over emails or names,
+and mind PCI / GDPR / CCPA / HIPAA-regulated fields.
+Large raw payloads — a full LLM prompt/response, a webhook or HTTP body — have
+legitimate debugging uses, but users put personal data in prompts and bodies carry
+secrets, so weigh the cost and risk and prefer logging the specific fields you’ll query
+over the whole payload.
+Server-side scrubbing is a backstop, not a license to log carelessly
+([`data-scrubbing.md`](data-scrubbing.md)).
+
+## Is a log worth keeping?
+
+Review each log you add or change, and drop any that can’t answer yes to all of these:
+
+- **Production question** — what concrete production question does it answer?
+- **Useful at volume** — would it still help if emitted thousands of times?
+- **Right signal** — is it better as a span, a metric, or a real Sentry error?
+- **Not already covered** — does an exception, an existing log, or a shared API/client
+  wrapper already capture it?
+- **Consistent** — do its event name and attributes follow the app’s conventions?
+- **Safe** — no PII, secrets, raw payloads, or unstable exception-message text?
+- **Actionable** — would seeing it change how someone investigates or responds?
+
+For each log you keep, be able to say: _“This log is valuable because it helps answer
+<specific question>.”_ Drop logs that merely confirm a routine UI interaction, duplicate
+a generic API failure, or record an expected validation failure without adding context.
+
+## Related
+
+- [`data-scrubbing.md`](data-scrubbing.md)
+- [`reduce-volume.md`](reduce-volume.md)
+- [`search-query-language.md`](../search-query-language.md) — querying logs.

package/skills/sentry/references/concepts/metrics.md

@@ -0,0 +1,49 @@
+# Application Metrics — What & Why
+
+**Application Metrics** are numeric values you emit and watch over time, trace-connected
+so a spike on a chart links back to the producing traces.
+Unlike traditional (StatsD-style) metrics they support high cardinality and
+dimensionality — a key difference that changes how you instrument them (see below).
+Three types, picked by the question:
+
+| Type             | Answers                            | Example                               |
+| ---------------- | ---------------------------------- | ------------------------------------- |
+| **count**        | _How many?_                        | `checkout.failed`, `signup.completed` |
+| **gauge**        | _What’s the value now?_            | `queue.depth`, `connections.active`   |
+| **distribution** | _What’s the spread (p50/p95/max)?_ | `api.latency`, `payload.size`         |
+
+## What Application Metrics excel at
+
+They answer _how many / how much / what’s the trend_ — the aggregate view you alert and
+build dashboards on, where the other signals don’t fit: tracing is for request
+performance and flow, logging for runtime decisions and audit trails, errors for
+critical failures. A metric tells you _that_ something moved, not _why_ — and because
+Application Metrics are trace-connected, you pivot from a point on the chart to its
+samples and the traces behind them to find the cause.
+
+## Setup essentials
+
+- **Don’t re-invent what Sentry derives** — issue counts, throughput, latency
+  percentiles, and crash-free rate come from errors/spans for free.
+  Reserve Application Metrics for KPIs Sentry can’t see: conversion, business failures,
+  saturation, cache-hit ratio.
+- **A KPI already sitting in your logs is a candidate to promote to a metric** — a log
+  is an ephemeral signal optimized for search; a metric is a durable, review-worthy code
+  artifact optimized for alerting and dashboards.
+- **High cardinality and dimensionality are fine — and a key benefit.** Unlike
+  traditional metrics, Application Metrics can carry high-cardinality attributes (user
+  IDs, request IDs, URLs); don’t force low-cardinality attributes the way you would with
+  a StatsD-style metric or you’ll throw away useful signal.
+  Set **units** on distributions (ms, bytes) and name consistently
+  (`domain.thing.action`).
+- Values are emitted **per occurrence and aggregated at query time** (not a client-side
+  pre-aggregate).
+- The old beta `Sentry.metrics.increment` / StatsD-style API was **removed in SDK v9** —
+  use the current `count` / `gauge` / `distribution` API (the exact surface varies by
+  platform).
+
+## Related
+
+- [`monitors.md`](monitors.md) — a Metric Monitor can alert on an Application Metric (it
+  can also watch logs, spans, or errors — it isn’t metrics-specific).
+- [`tracing.md`](tracing.md) — Application Metrics complement, don’t replace, spans.

package/skills/sentry/references/concepts/monitors.md

@@ -0,0 +1,78 @@
+# Monitors → Issues → Alerts — The Model
+
+Sentry separates **what you detect** from **what you do about it**, in three stages —
+**Monitors** detect, **Issues** are the unit you triage, and **Alerts** respond:
+
+- A **Monitor** decides _when_ a signal becomes an **issue**.
+- An **Issue** is the unit you triage — a grouped, stateful object (status, priority,
+  assignee, history).
+- An **Alert** decides _what to do_ once an issue matches its conditions — notify Slack,
+  page someone, open a ticket, hit a webhook.
+
+Monitors detect; Alerts respond.
+They’re configured independently: one alert can watch many monitors/projects, and one
+monitor can feed several alerts.
+
+> Terminology: this model uses **Metric Monitor** for the detection stage and reserves
+> **Alert** for the response stage.
+> Older docs and integrations still say “metric **alert**” for the same detection
+> concept — treat them as the same thing; the rename isn’t fully settled across the
+> product.
+
+## Monitors — when a signal becomes an issue
+
+- **Default monitors** — auto-created per project: the **Issue Stream Monitor** and
+  **Error Monitor** (the error-detection / grouping pipeline).
+  Nothing to set up; worth knowing they’re “monitors” in this model.
+- **Custom monitors:**
+  - **Metric Monitor** — a threshold on errors / spans / logs / releases / Application
+    Metrics; the threshold can be **fixed**, a **percentage change** vs.
+    a prior window, or **dynamic anomaly detection**. Often created straight from a
+    saved Discover or Metrics-Explorer query.
+  - **Cron Monitor** — a scheduled-job watch via check-ins ([`crons.md`](crons.md)).
+  - **Uptime Monitor** — periodic HTTP checks against a URL.
+  - **Mobile Builds Monitor** — app-size thresholds across iOS/Android builds.
+
+**Monitor config also sets issue attributes at creation** — priority, auto-resolve, and
+assignee (ownership rules can override the assignee).
+The monitor decides not just _that_ something becomes an issue but _how important_ it is
+and _who owns it_.
+
+## Alerts — acting on issues
+
+An alert is **sources → triggers → filters → actions**:
+
+- **Sources** — which projects/monitors it watches.
+- **Triggers** — which issue-state changes fire it (new, regression, reappearance,
+  resolved); triggers are OR’d.
+- **Filters** — conditions the issue/event must match before actions run (priority,
+  frequency, tags, assignment, age); filter groups can be ANY or ALL. **If an issue
+  exists but no alert fired, a filter is usually why.**
+- **Actions** — Slack, email, PagerDuty, Discord, Jira, webhook, …
+
+## When to reach for what
+
+- _“Tell me in Slack when a new issue shows up”_ → an **Alert** (the default error
+  monitor already makes the issues).
+- _“Alert when error rate / latency / a metric crosses a line”_ → a **Metric Monitor**,
+  then an alert.
+- _“My nightly job didn’t run”_ → a **Cron Monitor**. _“Is my endpoint up?”_ → an
+  **Uptime Monitor**.
+
+## Coverage honesty
+
+Alert creation is automatable via Sentry’s workflow-engine API; several monitor types
+(uptime, dashboards) are heavier UI/API hand-offs today — be upfront about what the
+agent can do end-to-end vs.
+where it walks the user through the UI. The MCP is **read-only** here: it can inspect
+alert rules (`find_alert_rules`, `get_alert_rule`), cron monitors and their check-ins
+(`find_monitors`, `get_monitor_details`), and dashboards — useful for verifying after
+creation — but there is no create or update path for any of them, and uptime monitors
+have no MCP surface at all.
+
+## Related
+
+- [`crons.md`](crons.md)
+- [`metrics.md`](metrics.md)
+- [`releases.md`](releases.md)
+- [`search-query-language.md`](../search-query-language.md)

package/skills/sentry/references/concepts/profiling.md

@@ -0,0 +1,38 @@
+# Profiling — What & Why
+
+Code-level sampling of production execution.
+Tracing tells you _which operation_ is slow; profiling tells you _which function and
+line_ inside it is burning the time.
+The output is a **flame graph**, also available as **differential** ("what got slower
+between releases") views.
+
+## What a flame graph represents
+
+A flame graph aggregates many stack samples, and its two shapes have **different
+x-axes**. In a single-profile graph X is time and **width = time spent**, so the
+bottleneck is the deepest wide frame with high **self-time** (time in the function
+itself, excluding children) — a wide frame with little self-time just means the cost is
+in a child. In an **aggregated** graph X is not time; **width = how often a frame
+appears** across samples.
+Frames are colored **application vs.
+system**: you can only act on your own code, so a wide _application_ frame is the
+target, not a wide system frame.
+A profile covers one thread at a time.
+
+## Setup essentials
+
+- **Modes:** **Continuous profiling** (backend; Python/Node today) and **UI profiling**
+  (frontend/mobile) are the current products; legacy transaction-based profiling is
+  being replaced.
+- **The dependency to get right:** in the default **`manual` lifecycle** mode, profiling
+  runs _independently_ of tracing — you start/stop it explicitly
+  (`start_profiler`/`stop_profiler`), and nothing is collected until you do.
+  Only the optional **`trace` lifecycle** mode (and legacy transaction-based profiling)
+  require tracing on and sample relative to sampled transactions.
+- **Sample, don’t profile everything** — ~1–5% CPU overhead; sampling is session-scoped.
+  Mind minimum SDK versions (support varies by platform).
+
+## Related
+
+- [`tracing.md`](tracing.md) — profiling localizes a bottleneck tracing pointed at.
+- [`reduce-volume.md`](reduce-volume.md) — sampling/overhead tradeoffs.

package/skills/sentry/references/concepts/reduce-volume.md

@@ -0,0 +1,49 @@
+# Volume & Cost — Strategy
+
+Sentry bills by the volume of each signal (errors, spans, replays, profiles), and logs
+and metrics are billed by _size_ — so attribute count and message length matter, not
+just event count. Reducing volume is keeping the data that earns its place and dropping
+the rest — for quota _and_ for signal-to-noise.
+
+## The core tradeoff, per signal
+
+- **Errors:** sample _lightly_ or not at all — usually what you can’t afford to miss.
+  The cheapest win is **filtering known noise** (browser-extension errors, bots, a
+  specific bogus exception), not blanket down-sampling.
+- **Spans / traces:** sample _aggressively_ — the highest-volume signal and biggest
+  lever. A `tracesSampler` that keeps important paths and drops health-check noise beats
+  a flat low rate. (Note `tracesSampleRate: 0` doesn’t disable tracing — see
+  [`tracing.md`](tracing.md).)
+- **Replays / profiles:** keep the asymmetric/sampled defaults (high on error, low on
+  normal).
+- **Logs / metrics:** billed by size — trim attribute count and message length, not just
+  event count, on top of emitting fewer, higher-signal events.
+
+## Where to sample — head vs. server-side
+
+- **Client / head sampling (SDK)** — decide before sending; cheapest, and the decision
+  propagates across a trace so you keep whole traces.
+  The first lever.
+- **Server-side (Sentry)** — a backstop, and for what the SDK can’t cleanly decide:
+  - **Inbound data filters** — browser-extension errors, known crawlers, legacy
+    browsers, `localhost`, specific error messages or releases, by IP. (Some are
+    Business-plan.)
+  - **Per-DSN rate limits** — cap a noisy key.
+    **Spike protection** — an automatic guard against a sudden flood.
+    **Delete & Discard** — stop ingesting a specific high-volume issue entirely.
+
+## A practical workflow
+
+1. **Find the top offenders first** (MCP / Explore across errors, spans, and logs) —
+   don’t cut blind.
+2. **Filter known noise** — high precision, no fidelity loss on real data.
+3. **Tune span sampling** with a `tracesSampler` — the biggest lever.
+4. **Set rate limits / spike protection** as a safety net.
+5. **Re-measure** to confirm you cut noise, not signal.
+
+## Related
+
+- [`tracing.md`](tracing.md) — span sampling, the main lever.
+- [`logging.md`](logging.md)
+- [`session-replay.md`](session-replay.md)
+- [`profiling.md`](profiling.md)