From vivreal-knowledge
Use when investigating what happened during a Vivreal user action across the stack, tracing an error end-to-end, validating a deploy, or doing tenant-scoped triage with Sentry. Teaches WHEN to trace cross-stack (frontend spans ↔ backend logs ↔ WebSocket events) and HOW (trace-ID propagation, the standard tag set, request_id fallback, service.* breadcrumbs). Triggers on: "what happened when I did X", "why did this error", trace this request, Sentry issue, deploy validation, "everything's broken for this group", crash, error timeline. For the full investigation agent with Sentry MCP tools wired in, dispatch the `sentry` agent / `/sentry-trace` (both in the `vivreal-sentry` plugin); this skill is the passively-loaded knowledge layer.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vivreal-knowledge:sentry-tracerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Every portal user action produces a **complete distributed trace**: browser → edge proxy → backend Lambda → MongoDB. Reconstruct that trail from Sentry to explain what happened, what failed, and what's missing. This skill is the **passive knowledge layer**; the active **`sentry` agent** (in the `vivreal-sentry` plugin, driven by `/sentry-trace`) owns the Sentry MCP querying. For LIVE infrastruc...
Every portal user action produces a complete distributed trace: browser → edge proxy → backend Lambda → MongoDB. Reconstruct that trail from Sentry to explain what happened, what failed, and what's missing. This skill is the passive knowledge layer; the active sentry agent (in the vivreal-sentry plugin, driven by /sentry-trace) owns the Sentry MCP querying. For LIVE infrastructure state (Lambda concurrency, Step Functions executions, Atlas saturation) rather than Sentry telemetry, that's the vivreal-ops agent.
Always pass organizationSlug: 'vivreal' and regionUrl: 'https://us.sentry.io' on every Sentry MCP call.
| Project slug | Service | Tracing |
|---|---|---|
vivreal-portal | Portal (Next.js) — browser + edge + SSR | 100% |
vr-secure-api | VR_Secure_API + WebSocket Lambdas | 100% |
vr-cms-api | VR_CMS_API | 100% |
vr-main-api | VR_Main_API (auth/signup/email) | 100% |
vr-client-api | VR_Client_API (public content) | 100% |
vr-client-auth | VR_Client_Auth authorizer | 100% |
site-deployment | Vivreal_EventHandler Step Functions | 100% |
vivreal-mcp-server | VR-MCP-Server | 100% |
vivreal-templates | Customer sites | errors only (no tracing by design) |
vivreal-portal HTTP client spans in the last ~5 min, grab the Trace ID, follow it into the relevant backend project(s), then read backend logs + WebSocket send events. Build a chronological timeline.service.* category names the controller + operation), check tag distribution, then trace upstream (portal failed HTTP span) or downstream (backend error log).find_releases for the new version, compare error rate last hour vs 24h, look for new issue types and expected log patterns.environment:production FIRST, then scope by groupID across projects to find the noisiest service, drill in, read breadcrumbs on a representative event.sentry-trace + baggage headers. The portal edge proxy forwards them; the backend Lambda's initSentry() (first line of lambda.js) extracts them via awsLambdaIntegration. A single Trace ID connects browser → edge → backend → Mongoose spans.mongooseIntegration creates DB spans (real query time). pinoIntegration ingests structured logs — but only with the two-arg pino form logger.info(obj, 'event_name'); single-arg logger.info({event:'x'}) yields empty message bodies (a regression signal post-2026-05-18).get_sentry_resource(resourceType:'trace', resourceId:<traceId>) shows the full waterfall in one view.| Tag | Use to filter by |
|---|---|
environment | Filter this FIRST — production vs staging. Never investigate unscoped. |
groupID | Tenant triage (Mongo _id). |
dbKey | DB-routing scope (general_shared / pro_plus). |
request_id / requestId | Critical fallback when trace IDs don't stitch — search_events(... 'tagged request_id:<id> across all projects'). |
lambda | Which Lambda fired. |
route | Endpoint scope. |
release | Bisect by deploy. |
Backend services emit Sentry.addBreadcrumb({ category: 'service.<area>' }) at entry + risky ops: service.collectionObjects, service.integrationObjects, service.sites, service.group, service.integrations, service.billing. The LAST service.* breadcrumb before the throw names the controller + operation that failed. Cross-reference it with the stack trace's first first-party frame.
password*, *token*, apikey, secret, integrationkey. Seeing a raw secret is a regression to flag — don't quote it.sentry-trace/baggage, an un-redeployed Lambda, or a header-stripping hop. Fall back to request_id correlation.Produce a timeline table (Time UTC | Service | Event | Trace ID | Request ID | Tenant groupID/dbKey | Details), then Trace Health (continuity ✓/✗, environment, source maps resolved), then Findings citing trace ID + request_id + breadcrumb + tenant tags.
Reference audit: Vivreal_Portal_Mobile/docs/audits/sentry-observability-2026-05-16.md.
npx claudepluginhub hillbombcreations/vivreal-skills --plugin vivreal-knowledgeProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.