The pnpm workspace hoists packages into a root node_modules/, which the
root .gitignore never covered (only packages/installer/ ignores its own),
so the merge commit accidentally swept it into the tree. Untrack it and
add the ignore so it cannot recur.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Resolves conflicts against the harness build-on-demand refactor (#321),
the develop/main deploy split (#317), and the flowmark reformat (#315/#316):
- harnesses/index.ts: register the two OpenCode harnesses inside
buildHarnesses() and drop their module-level constants, matching the
single-construction-path refactor
- deploy-plugins.yml: keep main's develop/main branch semantics with the
job counts updated for six plugin repos
- AGENTS.md / READMEs: fold the OpenCode V1/V2 mentions into main's
reflowed prose
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Our plugin reaches Claude two ways. The installer uses Anthropic's
official catalog, which pins getsentry/plugin-claude; adding our own
catalog by hand installs the same repo under a second id. Claude holds
both happily, so two plugins end up serving the same skills and both
resolve.
Claude had no cleanup hook, so nothing dropped the copy the installer
does not manage. It gets one, checking only whether the other id is
present -- a no-op for anyone who has only ever run the installer.
The direction is not the same as the other harnesses and is not meant to
be: Grok evicts the vendor catalog's copy to keep its direct-repo
install, because its marketplace install is TUI-only. The rule they share
is to keep whatever the harness installs and evict every other sentry.
The four harnesses were module-level constants, so importing the barrel
constructed all of them as a side effect and there were two ways to get
one: the singleton or the factory it was built from. A caller that needs
them configured differently could only use the factories and rebuild the
list by hand.
buildHarnesses() replaces the constant, leaving a single construction
path and no work at import time.
Nothing has read this file since the builds became the only consumers of
mcp.json: Codex and Grok emit their own .mcp.json, Cursor takes mcp.json
as-is, and Claude inlines the server in plugin.json. It had already
drifted -- the copy was missing the utm_source tag added in #191 -- which
is the failure mode a second hand-synced copy invites.
The plugins had no releases to speak of: one hand-edited version copied
across four manifests, no tags in any distribution repo, and every merge
rewriting each repo's main. Nothing separated "merged" from "shipped",
and no ref named a version anyone could pin or roll back to.
src/plugins/version.json is now the one version, stamped over the 0.0.0
placeholder in each manifest at build time, so the four plugins move in
lockstep from a single bump.
Deploys land on develop instead, leaving main to advance only when the
Release plugins workflow cuts a version -- which tags this repo
plugin/v<version> and each distribution repo v<version>. Consumers all
resolve main today, so this is what makes shipping deliberate rather
than a side effect of merging.
Develop builds carry their distance from the last tag
(1.2.1-dev.14.gdeadbee). The patch bump is load-bearing: semver ranks a
prerelease below its release, so 1.2.0-dev.14 would compare older than
the 1.2.0 it is fourteen commits ahead of, and build metadata is ignored
in comparisons entirely.
Now that the tree is formatted, this keeps it that way. prek runs the hooks the
way sentry runs its own, so one command covers Markdown formatting, file
hygiene, workflow schemas, and the two validators this repo already had.
scripts/lint.sh is the entrypoint and pins prek through uvx, so there is nothing
to install first. It replaces the Validate Skill Tree workflow, whose two steps
are hooks now.
Most hooks fix rather than report, and the workflow leans on that: on a pull
request from this repository it pushes whatever they rewrote back to the branch
instead of failing a check, then runs them again to report the state after the
fix -- a GITHUB_TOKEN push starts no workflow run of its own, so the fix commit
would otherwise carry no signal. Fork pull requests have no branch to push to
and fail with the command to run. Sentry pushes these fixes under a GitHub App
token so the follow-up commit gets checked normally; that app's private key is
not available to this repo.
Markdown belongs to flowmark alone. It writes a trailing space on the blank
lines inside a blockquote, so trailing-whitespace and end-of-file-fixer skip
Markdown rather than strip what flowmark rewrites on the next run, forever.
src/SKILL_TREE.md stays out of flowmark's reach through .flowmarkignore because
build-skill-tree.sh generates it, and skills-legacy/ is excluded repo-wide as
frozen content nothing ships.
Skill and reference prose is the product here, and it had drifted into three
different wrapping styles. This is the mechanical pass that settles it: flowmark
with semantic line breaks, an 88-column wrap, typographic quotes and ellipses in
prose, and its safe cleanups. Fenced code is untouched. The tooling that keeps
it this way lands separately; this commit is the one-time reformat, so it can be
read as noise and skipped.
Two parts of it are not noise. Thirteen table rows across eight SDK references
held a code span with a raw `|` or a nested backtick, which GFM does not allow
and no formatter can round-trip: the pipe ends the cell early, so the
`tracePropagationTargets` row was quietly losing its description. Pipes are
escaped now, and the cells that showed a template literal name it in prose --
every one of those files already shows the real syntax in a fenced block
nearby.
The other part is file hygiene, off the Markdown path: a final newline on
.gitattributes and the two SVG assets, and a trailing blank line dropped from
skill-drift.yml.
Every MCP claim across these files was tested against the live server, with the
sentry-mcp source settling the ambiguous cases. Much of it had drifted from the
deployed tools in ways that send an agent down a failing path.
The most common problem was `get_issue_details`, written as a bare call in six
places despite being catalog-only. `get_sentry_resource` delegates to the same
handler and is exposed directly, so it takes over. setup-verification also had
the classification inverted, calling the two exposed search tools catalog ones,
and named output fields the MCP does not return.
new-project omitted that `create_project` requires a team slug, so following it
verbatim fails validation. Several docs asked for things the MCP cannot answer:
per-frame in-app markers, symbolication status, and whether an artifact upload
predates an event.
The search grammar needed the most work. Both search tools route every query
through an LLM that rewrites fields to fit the dataset, so documented constructs
are silently changed — `age:` becomes `firstSeen:` with `+` flipped to `-`,
reversing the filter's meaning. Wrong-dataset keys return zero results rather
than erroring, which the pitfalls section had backwards.
The skills inventory listed 26 skills, every one of which is gone -- the 19
per-SDK bundles became the reference library, and span-streaming,
instrumentation-guide, fix-issues, and sdk-skill-creator were each removed or
dissolved. Eight skills ship today and none of them appear in that section.
Replace the inventory with a pointer to SKILL_TREE.md rather than a corrected
copy. The list is generated from the skills themselves; a second copy maintained
by hand is what rotted here, and would rot again on the next rename.
Drop the instruction to keep `allowed-tools` in every skill file. No skill has
it, nothing requires it, and following the instruction is a change to every
skill in the repo for no effect -- an agent that trusts this file adds the field
and is then wrong.
Also stale: the Sentry code-review convention outlived the skills it described
(removed in 7141b95), and the validation section still advertised breadcrumb and
router-table checks that no longer exist.
Document what an agent editing references actually needs and currently has to
reverse-engineer: the library layout, the consumer-count rule that decides
whether content is shared or skill-local, and the no-cross-domain-links rule
that makes hydration safe. Add the built-tree link check from #312, and why it
runs against the built tree.
Dissolving the last routers (#310) emptied both category buckets, but the
generator still emitted their headings, intro prose, and a bare table header
with no rows underneath. That ships to every agent that reads SKILL_TREE.md as
two sections advertising capabilities with nothing in them.
Removing just those sections would leave a worse state behind: a skill carrying
a category would still be scanned and validated, but nothing would render it, so
it would vanish from the tree with the script reporting success. So retire the
concept instead of half of it.
Nothing needs it. No skill carries category, parent, role, or
disable-model-invocation; outside this script nothing reads those fields at all.
What remained was ~120 lines validating and rendering a model the project has
abandoned -- router roles, parent-must-be-a-router, leaf-listed-in-its-router,
per-category tables -- none of it reachable. The hierarchy validation is
replaced by the rule that actually holds now: those four fields are rejected
outright, so a stale copy-paste or an attempt to reintroduce routing fails
loudly rather than dropping a skill silently.
The categorize pass collapses with it: one flat table means every skill is a
row, so ALL_SKILLS is the list and the STANDALONE/ROUTERS split has nothing left
to distinguish. The heading becomes "Available Skills" -- "Standalone" only
meant something in contrast to the category sections that are gone.
The inert breadcrumb check goes too. It skipped every skill that was neither a
router nor categorized, which is all of them, so no link has been checked for
some time; replacing it is a separate change.
Skill link checking has been silently off. build-skill-tree.sh has a
breadcrumb-link check, but it opens by skipping any skill that is neither a
router nor categorized:
if [[ "$role" != "router" && -z "$cat" ]]; then
continue
fi
Every skill is standalone now, so every skill takes that branch and no link is
checked at all. It was not turned off deliberately -- the guard was written when
standalone skills were the exception, and going flat quietly disabled it for
everything. That leaves the failure #308 fixed with nothing guarding it.
Check the built plugin trees rather than the source. A skill only becomes
self-contained once the build hydrates its declared references in, so the source
tree cannot answer the question on its own -- any check there has to
re-implement the hydrator's glob semantics and can drift from it. Building
first removes the simulation: what gets validated is the tree a user installs,
per agent, including each agent's own transform.
Every agent is built and checked, since layout and transforms differ between
them and a link can survive one while breaking another. The builds need no
network or credentials and take well under a second each, so the whole sweep
costs a few seconds per pull request.
Passing the source library in as well buys a cause instead of a symptom: a
target missing from the built skill but present in the library means the
manifest never declared it, so the error says to fix references.yml rather than
leaving a bare dangling-link report.
Runs in the existing validate job, which gains a uv install matching the one
deploy-plugins already uses.
An issue tells you what broke but nothing about when it started or what
changed, and nothing in the shipped library wires that up. The second skill
from the getting-started design's later-focus set, filling that gap.
Releases are not only a task someone asks for, though -- like readable stack
traces, they are part of getting setup right. first-error-setup.md already
tells the agent to make sure release/environment are set in the production
environment, and could not act, because no procedure existed to hand off to.
So the content lands in references/releases/ and is hydrated by
sentry-get-started and sentry-instrument as well, and both of those hooks now
route into it. Three consumers, one copy.
Why a group rather than a single file: this setup has two halves that fail
silently and independently -- the SDK tagging events with a release name, and
CI creating a release object under that same name with its commits and deploy.
Neither errors when the other is missing, so the group leads with an index.md
that diagnoses which half is absent before anything gets configured. tagging.md
is the half a setup flow can do inline (one init option); ci-pipeline.md,
suspect-commits.md, and troubleshooting.md are the rest, and the skill stays
thin orchestration over them.
auth-token.md moves out of debug-artifacts/ to the top level. Creating a
release is a write to the org needing the same build-time secret as an artifact
upload, so it now has two consumer groups, and references may not link across
domains -- a releases/ file could not have reached it where it sat.
The bundler-plugin release options (create/finalize/inject defaulting true,
setCommits defaulting to auto) are verified against
@sentry/bundler-plugin-core 4.6.1; sentry-docs does not document them.
With AI monitoring absorbed into sentry-instrument, the router only grouped
create-alert, otel-exporter-setup, and snapshots-cocoa — each a self-contained
task. Promote all three to standalone skills (drop category/parent/
disable-model-invocation and the router breadcrumb) so they're discoverable
directly from their descriptions, and delete the router.
No routers remain. Rewrite the AGENTS skill-tree navigation to describe the flat,
task-shaped model (one skill = one task, shared content hydrated from
references/) and regenerate SKILL_TREE.md.
An event whose frames read chunk-4f2a.js:1:28471 costs you the thing Sentry is
for, and nothing in the shipped library fixes it. The first skill from the
getting-started design's later-focus set, filling that gap.
Making traces readable is not only a symptom-driven task, though — it is part of
getting setup right. first-error-setup.md already tells the agent to flag what
production needs, and setup-verification.md already treats minified frames as
not-yet-done; neither could act, because no procedure existed to hand off to.
So the per-platform content lands in references/debug-artifacts/ and is
hydrated by sentry-get-started and sentry-instrument as well, and both of those
hooks now route into it. Three consumers, one copy.
Why a new top-level group rather than the SDK trees: source maps and debug
symbols are on STRUCTURE.md's list of topics the SDK references must not carry,
references may not link across domains (so an sdks-hosted procedure could not
reach the auth-token or matching docs), and ten of the twenty slugs are
JavaScript — one source-map story that per-slug files would duplicate ten times.
STRUCTURE.md now names debug-artifacts/ as the home so the topic stops
scattering. What stays per-platform in sdks/*/index.md is the SDK-side config
hook the contract does allow: the bundler-plugin block, the Gradle sentry {}
options, the wizard call.
The group covers what no platform file does: the auth token (a silent no-op when
unset, the most common reason a correct-looking setup uploads nothing), artifact
matching for when upload succeeded but frames stayed raw, and the native upload
mechanics. Content is harvested from the pre-refactor per-SDK wizards and the
retired sentry-source-maps stub; the Apple procedure is checked against the
current docs, and where an option name drifts across plugin majors (Android
native symbols, the Flutter plugin's pubspec keys) the reference says to verify
rather than pinning a version-specific guess.
The skill itself is diagnosis-first: read a real event and classify the failure
before editing build files, because missing, mismatched and partially-covered
artifacts look identical in a trace. It also refuses to call the job done
against the old event — artifacts never repair an event that already arrived, so
only a new one proves the fix.
46 relative links dangled in the shipped output — a reader following one got
nothing. Three distinct causes, all invisible in the source tree:
Manifests were scoped by what a skill *reads*, but links resolve by what is
*present*. The concept docs cross-link each other (data-scrubbing, reduce-volume,
releases, monitors, profiling), so hydrating a hand-picked subset breaks every
pointer to an omitted sibling. Since hydration only places files on disk, the
subsetting bought nothing and cost 33 links: instrument, get-started and
debug-issue now take concepts/ whole, with the reading scope still stated in a
comment and enforced where it belongs, in SKILL.md.
Six concept docs pointed at search-query-language.md as a sibling, but it lives
at the references root, one level up. This was broken in source too, not just in
dist — the path never existed. Now ../search-query-language.md.
sdks/index.md linked STRUCTURE.md, which is an internal authoring contract the
builds deliberately exclude, so the link could never resolve in a shipped skill.
It stays mentioned for authors working in the repo, minus the link.
Verified by building all four targets (claude, cursor, codex, grok) and resolving
every non-external relative link in each: 46 dangling before, 0 after.
Major-version SDK upgrades are a rare, low-frequency task and don't fit the
task-shaped skill set the getting-started redesign is converging on. Retiring
sentry-sdk-upgrade empties the sentry-workflow router (its only remaining child
after the code-review skills were removed in #283), so drop the router too.
Move sentry-sdk-upgrade under skills-legacy/ the way #265 retired the other
superseded skills: out of the plugin build and the drift automation, still
served by skills.sentry.dev for existing URL consumers. The router itself is
deleted rather than moved — a router that fronts nothing has nothing to serve.
Drop the README/AGENTS listings and the workflow entries in the AGENTS
skill-tree navigation, then regenerate SKILL_TREE.md. sentry-feature-setup is
now the last router as the library migrates toward flat standalone skills.
(cherry picked from commit ef57592f08263023198ddb43a851df02adecd544)
AI/LLM monitoring is a signal, and sentry-instrument already wires it up per
platform from the reference library. With the shared concepts/ai-monitoring.md
now in place (#285) as the canonical home for the cross-cutting rules —
gen_ai.* model, conversation-ID format, token/cost accounting, PII and sampling
strategy — the standalone skill is fully absorbed.
Remove sentry-setup-ai-monitoring: drop the skill, its entry and AI wording in
the sentry-feature-setup router, and the README/AGENTS listings, then regenerate
SKILL_TREE.md.
Fold in the parts that only lived in the skill, language-agnostically, so
nothing is lost with it: auto-instrumentation is runtime-dependent (there is
nothing to patch on workerd or in the browser), the input/output message shape
and why thinking must be a reasoning part rather than text, and the root-span
sampling rule that decides whether keeping gen_ai at 100% means matching the
gen_ai op or the HTTP route in front of it. Also drop the last pointer at the
retired skill name, in the PHP reference.
(cherry picked from commit b7d29503746a3e38dff9c4e54f01e3206bdd12b7)
* docs(cloudflare): update references for @sentry/cloudflare 10.69.0
Update the Cloudflare SDK reference tree for the 10.69.0 release,
verified against the release changelog, the published npm package, the
SDK source, and the new agents-sdk feature page on docs.sentry.io.
New in 10.69.0:
- instrumentAgentWithSentry — dedicated wrapper for Cloudflare Agents
SDK classes (Agent, AIChatAgent, McpAgent). Applies everything
instrumentDurableObjectWithSentry does plus @callable() RPC spans
(with cloudflare.agent.class/name attributes), automatic conversation
IDs per chat turn and RPC call (defaulting to the instance name), and
conversation rotation on chat clear. durable-objects.md's Agents
section is rewritten around it, with the manual
instrumentDurableObjectWithSentry + setConversationId pattern kept as
the pre-10.69 fallback.
- Vite plugin autoInstrumentation now detects and wraps Agent classes
automatically, and gains a top-level wranglerConfigPath option for
custom wrangler config names.
- spotlightIntegration — local-dev event forwarding to a Spotlight
sidecar; added to the index's integrations notes.
- Framework-internal Durable Object storage spans (cf_/cf:/__ps_//
key prefixes) are filtered out; noted in durable-objects.md.
- Fixed: a Vercel AI SDK call no longer suppresses direct env.AI.run
spans for the rest of the isolate; troubleshooting row added.
Also aligned with the new agents-sdk docs page guidance: conversation
IDs should be real chat session IDs — instance names only when one
instance is one chat session, never per-user or shared singletons like
'default'. Added troubleshooting rows for chats not grouping and for
the one-giant-conversation misconfiguration. Default-integrations table
updated (conversationIdIntegration, httpServerIntegration) and version
notes bumped to 10.69.0.
Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
* docs(cloudflare): address review feedback on 10.69.0 update
Address JPeer264's review on the Agents SDK / conversation ID sections:
- Clarify the heading and lead of the 'automatic' Agents SDK section:
it's the conversation ID that is automatic, and 'the automatic ID'
now reads 'the conversation ID'
- Correct the pre-10.69 Vercel AI + Workers AI troubleshooting row: the
bug produced duplicate spans (both the Vercel AI integration and the
Workers AI binding recorded the same call), not suppressed env.AI.run
spans; 10.69.0 makes the binding skip calls the Vercel AI integration
is already recording
- Document what triggers conversation rotation concretely:
clearHistory() from useAgentChat, or anything emitting the
message:clear observability event (linked to the Cloudflare Agents
observability channels docs), in both ai-monitoring.md and
durable-objects.md, plus a troubleshooting row explaining that a
split conversation after a chat reset is by design
Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
---------
Co-authored-by: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
* docs(cloudflare): add dedicated Agent Tracing reference
Add src/references/sdks/cloudflare/ai-monitoring.md, a canonical
ai-monitoring signal file covering Sentry Agent Tracing on Cloudflare
Workers, grounded in the live agent-tracing docs, sentry-docs PR #18844,
and the published @sentry/cloudflare@10.68.0 package.
The workerd runtime cannot monkey-patch, so the reference is organized
around the three instrumentation paths available on Cloudflare:
1. Workers AI (env.AI) — automatic via withSentry (v10.67.0+)
2. sentryCloudflareVitePlugin (v10.68.0+, experimental) — build-time
diagnostics_channel injection for openai, @anthropic-ai/sdk,
@google/genai, and ai, plus optional autoInstrumentation with
instrument.server.* / defineCloudflareOptions
3. Manual wrapping — instrumentOpenAiClient, instrumentAnthropicAiClient,
instrumentGoogleGenAIClient, createLangChainCallbackHandler,
instrumentLangGraph (LangChain/LangGraph are not covered by the Vite
plugin's channel injection — verified against the shipped
channel-integration-definitions)
Also covers Conversations (setConversationId, setUser, Agents SDK
this.name pattern), privacy controls via dataCollection.genAI,
streamGenAiSpans and the self-hosted caveat, manual gen_ai.* spans with
the current attribute names (gen_ai.input.messages etc.), token subset
cost gotchas, verification, and troubleshooting.
Wire the new file into the Cloudflare index (detect, recommend, feature
routing, verification), cross-link it from tracing.md's Workers AI
section, disambiguate sentryVitePlugin vs sentryCloudflareVitePlugin in
the source-maps section, and add a Cloudflare section to the
sentry-setup-ai-monitoring skill pointing at the reference.
Verified: scripts/build-skill-tree.sh --check passes and the Claude
build hydrates the new reference into sentry-instrument.
Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
* docs(cloudflare): make conversation ID a first-class setup step
Field testing showed agents set up Workers AI monitoring, correctly
note that env.AI is auto-instrumented, and stop there — the user only
gets conversation grouping after noticing the Conversations view is
empty and asking for it.
Auto-instrumentation covers the spans, not the grouping: Workers AI
never infers gen_ai.conversation.id. Promote setConversationId from a
later 'Tracking Conversations' section to part of the Workers AI setup
path itself, with the client-generates-ID / handler-sets-ID pattern and
a code sample. Also flag it in the index's detect and recommend phases
so a wizard run proposes it for chat apps up front, and add a
Conversations row to the verification checklist.
Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
* docs(cloudflare): embed conversation ID step in the Workers setup path
A fresh field test showed the previous fix wasn't enough: the agent
followed the index's Workers Setup section linearly, wired withSentry,
correctly reported free gen_ai spans — and never opened
ai-monitoring.md, so setConversationId was skipped again.
The detect/recommend hints landed in sections the agent skims past when
the user says 'set up instrumentation'. Put the step where the work
actually happens instead:
- Workers Setup gains an 'AI apps: set a conversation ID (required,
same edit)' subsection with the client-ID + handler pattern inline,
so following the setup path top-to-bottom now includes it
- The binding-instrumentation table row for Workers AI notes spans-only
- The recommend phase marks conversation tracking non-optional for AI
apps: an AI setup with spans but no Conversations is incomplete
Note: the earlier session run also predates the /cloudflare namespace
fallback pointing at this branch — the proxy serves main, so none of
the ai-monitoring.md content was reachable; the inline step in index.md
closes that gap regardless of which sub-files the agent fetches.
Co-Authored-By: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
---------
Co-authored-by: Claude (claude-sonnet-4-5) <noreply@anthropic.com>
Let callers pass an instruction after the install command and offer a
prefixed version on the clipboard once installation succeeds.
Co-authored-by: GPT-5 <noreply@openai.com>
Warden is now handled globally from getsentry/.github, so the
repo-local workflow is redundant. Keep warden.toml for config.
Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: junior <junior@sentry.io>
Co-authored-by: David Cramer <david@sentry.io>
Update the Python span-streaming migration skill to document the new
top-level sentry_sdk.init() parameters instead of nesting them under
_experiments. Rewrite the enable, sampling, ignore_spans, minimal setup,
and checklist examples to use trace_lifecycle="stream" and ignore_spans=[...]
directly. Add a Common Issues entry for the new warning emitted when
ignore_spans is set without span streaming enabled.
before_send_span remains under _experiments since it was not promoted.
Fixes PY-2611
Fixes GH-6823
Refs PY-2609
Refs GH-6820
* update version to the number that will be the minimum pending SDK release
Document Laravel AI support across the AI monitoring and PHP SDK skills so agents can detect laravel/ai, recommend the Sentry Laravel 4.27 instrumentation path, and verify captured gen_ai spans.
Add a PHP reference covering Laravel AI installation, tracing and PII configuration, verification with an agent/tool, Conversations behavior, feature flags, and troubleshooting.
Co-authored-by: OpenAI GPT-5.2 <noreply@openai.com>
The PR-bot code-review skills (resolving sentry[bot] comments and Seer
bug-prediction findings on a PR) fall outside the task-shaped skill set the
getting-started redesign is converging on, and were flagged as dropped in that
consolidation. Remove them along with their router entries and doc listings.
The workflow router now points only at sentry-sdk-upgrade; SKILL_TREE.md is
regenerated to match.
AI/LLM monitoring was the one signal without a concepts/ reference, so its
cross-cutting strategy lived only in the four platform ai-monitoring.md files
(node, python, nextjs, nestjs) — duplicated and drifting. The proof: the
conversation-ID format rule (opaque, no slashes — a slash breaks Conversations)
had ended up in only the standalone sentry-setup-ai-monitoring skill and none of
the platform files.
Factor that shared knowledge into concepts/ai-monitoring.md: the gen_ai.* span
model and how to read an agent trace, the Conversations grouping and ID-format
rule, the token/cost subset accounting, and the PII and 100%-sampling strategy.
Per-platform SDK code stays in each platform's ai-monitoring.md. Add it to
sentry-instrument's references.yml and replace the "AI/LLM monitoring has no
concept doc" note in its playbook with a pointer to the new reference.
This gives the conversation-ID rule a canonical home and is a prerequisite for
retiring sentry-setup-ai-monitoring in favor of sentry-instrument.
Relocate all buildable source -- skills/, references/, plugin-src/, and
SKILL_TREE.md -- under a single src/ tree so the repo root cleanly separates
source from the frozen skills-legacy/ wizards, the installer package, assets,
and docs. plugin-src/ becomes src/plugins/.
The per-agent build scripts now resolve their content root at $REPO_ROOT/src,
build-skill-tree.sh scans src/skills and writes src/SKILL_TREE.md, and the
deploy and skill-drift workflows point at the new paths. references.yml
manifests are unchanged -- their paths are relative to the references root the
build passes in.
Keeps the existing 7-day merged-PR scan, but drops PRs whose merge commit
is not yet in the SDK's latest release and reads changed source at the
release tag instead of the default-branch merge SHA. Prevents documenting
APIs that are merged to master but unreleased.
Claude-Session: https://claude.ai/code/session_01F8AMk7i38XwYCjmJFdQRjA
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Switch the skill-drift detect job from the direct Anthropic API to
OpenRouter's Anthropic-compatible endpoint. The OpenRouter key is passed
via the action's anthropic_api_key input and ANTHROPIC_BASE_URL points
at https://openrouter.ai/api, per OpenRouter's official Claude Code
GitHub Action recipe. This adds provider failover and per-key budget
controls for the weekly fan-out runs.
Also bump the model from claude-sonnet-4-5 to claude-sonnet-5 (the
Anthropic Skin maps native model IDs, verified available on OpenRouter
as anthropic/claude-sonnet-5) and update the Co-Authored-By byline in
auto-created drift-fix commits to match.
Requires the OPENROUTER_API_KEY repo secret to be set before the next
scheduled run.
Co-authored-by: Claude (Anthropic AI model) <noreply@anthropic.com>
* docs(ai-monitoring): Document valid conversation ID format
gen_ai.conversation.id is used as a URL path segment in Sentry's
Conversations UI/API. A value containing a slash (e.g. a full URL) breaks
that routing — a customer hit this by setting their conversation ID to a
page URL.
Add explicit format guidance (short opaque identifier, alphanumeric with
dashes/underscores only) with UUID and conv_/asst_/sess_ prefixed
examples, so agents instrumenting AI monitoring steer customers toward
safe values instead of picking whatever string is convenient.
Co-Authored-By: Claude <noreply@anthropic.com>
* docs(ai-monitoring): Drop in-doc redirect wording
Remove the pointer to the Setting a Conversation ID section from the
Prerequisites paragraph — no redirects, just state the requirement.
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
The /seer command only wrapped what users can already do by asking the agent
natural-language questions directly against the Sentry MCP server, so it earned
its own maintenance surface (a command file, build wiring, and docs) for no real
capability. Remove the command along with the commands/ build plumbing
(copy_commands, per-agent build.sh calls, the deploy-plugins path trigger) and
every /seer reference across the READMEs, AGENTS.md, TELEMETRY.md, plugin
manifests, and concept docs.
sentry-workflow and sentry-feature-setup still routed to skills that moved to
skills-legacy/ — sentry-fix-issues, the three sentry-span-streaming-* skills,
sentry-instrumentation-guide, and sentry-instrument-logging. Those targets are
excluded from the plugin build and are not served by skills.sentry.dev, so the
links dangle (404 over the proxy, missing skill in the shipped plugin).
Drop those entries from both routers (rules + tables), trim the descriptions
and intros accordingly, and point production-issue debugging at the standalone
sentry-debug-issue skill and signal instrumentation at sentry-instrument.
This repo is the source of truth for skills, not an installable plugin.
Per-agent plugin metadata is generated by the plugin-src/<agent>/build.sh
scripts and published to each agent's distribution repository, so the
root-level .agents/ symlinks and the .claude-plugin/ and .cursor-plugin/
manifests are stale. Remove them and update the structure docs.
* docs: restore log-quality guidance to the logging concept doc
Backfills three things from the retired sentry-instrument-logging skill that
were thinned out in the migration to references/concepts/logging.md:
- a "Is a log worth keeping?" review checklist (production question, useful at
volume, right signal, not already covered, consistent, safe, actionable) plus
the one-sentence justification test;
- cross-service convention coherence — agree namespacing/naming/levels once so
logs correlate across languages, and share attribute names across a
baggage/sentry-trace boundary;
- what to include on error-level logs, and the nuance that large raw payloads
(LLM prompt/response, webhook/HTTP bodies) have legitimate uses but should be
weighed against cost/risk rather than flatly banned.
* docs: use literal angle brackets in the log-value example
Sergiy Dybskiy