debug-and-logging
Use when diagnosing Apex behavior with debug logs, choosing log levels, or replacing `System.debug` habits with structured production logging and async job monitoring. Triggers: 'debug log', 'System.debug', 'logging framework', 'AsyncApexJob monitoring', 'production logs'. NOT for exception taxonomy design alone or for non-Apex observability platforms by themselves.
Best use case
debug-and-logging is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when diagnosing Apex behavior with debug logs, choosing log levels, or replacing `System.debug` habits with structured production logging and async job monitoring. Triggers: 'debug log', 'System.debug', 'logging framework', 'AsyncApexJob monitoring', 'production logs'. NOT for exception taxonomy design alone or for non-Apex observability platforms by themselves.
Teams using debug-and-logging should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debug-and-logging/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debug-and-logging Compares
| Feature / Agent | debug-and-logging | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when diagnosing Apex behavior with debug logs, choosing log levels, or replacing `System.debug` habits with structured production logging and async job monitoring. Triggers: 'debug log', 'System.debug', 'logging framework', 'AsyncApexJob monitoring', 'production logs'. NOT for exception taxonomy design alone or for non-Apex observability platforms by themselves.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
Use this skill when the question is not merely “where do I put a debug line?” but “how do I make Apex diagnosable in the environments that matter?” Debug logs are useful in development and targeted troubleshooting. Structured logs, async job monitoring, and durable records are what keep production support workable. ## Before Starting - Is the need short-lived debugging in a lower environment or persistent production observability? - Which contexts fail today: synchronous requests, triggers, Queueables, Batch jobs, or event subscribers? - What can safely be logged without leaking secrets, tokens, or sensitive business data? ## Core Concepts ### `System.debug` Is A Development Tool First `System.debug` is valuable for temporary investigation and lower-environment diagnosis, especially when paired with the right debug categories and levels. It is not a durable production logging strategy. Teams that rely on `System.debug` alone usually discover too late that the information they need was never retained or queryable. ### Structured Logging Needs A Durable Sink For production support, use a real destination such as a custom log object, platform event, or external observability system. The important properties are durability, correlation, and queryability. A useful log record usually includes operation name, record IDs or correlation ID, severity, outcome, and normalized error details. ### Log Levels Should Reflect Actionability Debug levels are not decorative. Excessive low-value logging creates noise and storage pressure. Use lower-detail debug traces during focused diagnosis, but keep persistent production logging targeted toward warnings, errors, and key workflow checkpoints that support can actually act on. ### Async Monitoring Is Part Of Logging If Queueable or Batch work matters to the business, `AsyncApexJob` status and job metrics are part of observability. Logging should connect the initiating action to job IDs, job outcomes, and error counts instead of leaving async failures orphaned. ## Common Patterns ### Temporary Debug Logging With Removal Discipline **When to use:** A developer is tracing a bug in a sandbox or lower environment. **How it works:** Add targeted `System.debug` statements with clear labels and remove them after diagnosis. **Why not the alternative:** Leaving broad debug noise in production code makes future diagnosis harder. ### Structured Logger Wrapper **When to use:** A service, integration, or async worker needs durable support diagnostics. **How it works:** Centralize logging through one utility or service that writes severity, context, and identifiers to a durable sink. ### Async Job Correlation **When to use:** Batch or Queueable work drives business-critical outcomes. **How it works:** Log the initiating business context alongside the enqueued job ID, then monitor `AsyncApexJob` for failures and throughput. ## Decision Guidance | Situation | Recommended Approach | Reason | |---|---|---| | Sandbox-only debugging session | Targeted `System.debug` with clear labels | Fastest way to inspect runtime state temporarily | | Production support needs durable diagnostics | Structured log object or event | Queryable and retained beyond transient debug logs | | Async worker must be monitored | Correlate to `AsyncApexJob` and log job outcomes | Required for real operational visibility | | Sensitive integration flow | Minimal structured logs with secret-safe fields | Avoids leaking tokens or payload secrets | ## Recommended Workflow Step-by-step instructions for an AI agent or practitioner activating this skill: 1. Gather context — confirm the org edition, relevant objects, and current configuration state 2. Review official sources — check the references in this skill's well-architected.md before making changes 3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above 4. Validate — run the skill's checker script and verify against the Review Checklist below 5. Document — record any deviations from standard patterns and update the template if needed --- ## Review Checklist - [ ] `System.debug` usage is targeted and justified, not left as permanent noise. - [ ] Durable logging exists for production-critical failures. - [ ] Logged fields exclude secrets, tokens, and unnecessary sensitive payload data. - [ ] Async processes can be traced through job IDs or equivalent correlation. - [ ] Log severity and volume are aligned to support actionability. - [ ] Teams know where logs are retained and how they are purged. ## Salesforce-Specific Gotchas 1. **Debug logs are temporary and operationally fragile** — they are not a replacement for durable production logs. 2. **Overlogging can hide the signal you actually need** — a flood of low-value debug lines makes incidents slower to diagnose. 3. **Async failures often need both logs and `AsyncApexJob` inspection** — one without the other leaves blind spots. 4. **Logging secrets is still a security defect even if the log helps debugging** — sanitize outbound request data and auth fields. ## Output Artifacts | Artifact | Description | |---|---| | Logging review | Findings on debug noise, missing durable logs, and async visibility gaps | | Logging strategy | Recommendation for debug usage, structured logging, and retention | | Correlation pattern | Guidance for linking business actions, exceptions, and async job IDs | ## Related Skills - `apex/exception-handling` — use when the main gap is how exceptions are classified, rethrown, or mapped. - `apex/batch-apex-patterns` — use when observability issues center on Batch lifecycle and job monitoring. - `apex/callouts-and-http-integrations` — use when logs need to support outbound API troubleshooting safely.
Related Skills
omnistudio-debugging
Use when diagnosing failures, unexpected output, or silent errors in OmniScript, DataRaptor, or Integration Procedure assets. Triggers: 'omniscript not working', 'dataraptor returns empty', 'integration procedure failing', 'debug mode', 'action debugger', 'preview not running'. NOT for Apex debugging, LWC console errors unrelated to OmniStudio, or Flow fault path debugging.
lwc-debugging-devtools
Use when you need to diagnose live Lightning Web Component behavior in the browser — setting breakpoints, stepping through @wire emits, inspecting component state with the Lightning Component Inspector, reading wire-adapter network traffic, and interpreting symptoms like silent render failures or 'works in dev but not in prod'. Triggers: 'how to set breakpoint in lwc', 'source maps missing', 'enable debug mode', 'lightning inspector chrome extension', 'lwc wire not emitting'. NOT for Jest test failures — use `lwc-testing` — and NOT for Apex debug logs, which are an Apex debugging concern. Specific runtime error messages (wire undefined, querySelector returns null, NavigationMixin errors) belong in `common-lwc-runtime-errors`; this skill covers the debug TOOLING itself.
scheduled-flow-not-running-debug
Use when a Schedule-Triggered Flow is configured but is not firing at the expected time, or appears active in Setup → Flows but never produces output. Covers where scheduled flows actually surface (Setup → Scheduled Jobs, NOT Setup → Apex Jobs), the AsyncApexJob / CronTrigger evidence trail, top causes (deactivated scheduling user, daylight-savings transitions, time-zone mismatches between scheduling user and org, fault-paths that quietly stop the schedule, daily async-Apex limit pressure), and recovery steps (re-schedule via Apex, run the flow manually with the same input, switch the scheduling user). Triggers: 'how do I schedule a flow to run every monday', 'scheduled flow not firing', 'flow scheduled but no execution', 'scheduled flow stopped working last week', 'monday 6am scheduled flow did not run after dst change'. NOT for designing a new scheduled flow's record scope or idempotency (use flow/scheduled-flows), NOT for record-triggered Scheduled Paths that don't fire (use flow/flow-time-based-patterns), NOT for general Batch Apex job monitoring (use admin/batch-job-scheduling-and-monitoring).
flow-interview-debugging
Diagnose Flow failures using the Debug Log, Flow Error emails, and the Debug panel; instrument flows so production issues are triageable. NOT for Apex debugging.
flow-debugging
Use when diagnosing a Flow that does not run, runs but produces wrong results, fails silently, or shows an unexpected fault email. Triggers: 'flow debug mode', 'flow not running', 'flow interview log', 'fault email', 'record-triggered flow not firing', 'debug run as user', 'flow test suite'. NOT for Apex debugging (use debug-and-logging), NOT for designing fault connectors (use fault-handling), NOT for fixing governor-limit failures caused by bulk volume (use flow-bulkification).
debug-logs-and-developer-console
Use when setting up debug logs and trace flags, reading Apex log output and log levels, running queries in the Developer Console, executing anonymous Apex, or using the Apex Replay Debugger in VS Code. Triggers: 'set up debug log', 'Developer Console', 'anonymous Apex', 'trace flag', 'Apex Replay Debugger'. NOT for production logging strategy or custom structured logging frameworks (use debug-and-logging), and NOT for writing test classes (use apex-test-class-standards).
custom-logging-and-monitoring
Use when designing or implementing a custom logging framework in Apex: log sObject schema, log level gating, retention policies, batch purge jobs, and forwarding logs to external monitoring systems (Splunk, Datadog, etc.). NOT for built-in debug logs or Developer Console (use debug-logs-and-developer-console), NOT for exception capture and error propagation (use error-handling-framework), NOT for Event Monitoring (use security skills).
xss-and-injection-prevention
Use when writing or reviewing Visualforce pages, Apex controllers, or LWC components that output user-supplied data, build dynamic queries, or construct HTTP responses. Triggers: 'XSS in Visualforce', 'SOQL injection vulnerability', 'how to encode output in Apex', 'JSENCODE Visualforce', 'open redirect prevention'. NOT for Apex CRUD/FLS enforcement (use soql-security or apex-crud-and-fls), NOT for Shield encryption (use shield-encryption-key-management), NOT for AppExchange security review process (use secure-coding-review-checklist).
visualforce-security-and-modernization
Use when hardening or modernizing legacy Visualforce pages — covers the platform CSRF token model and when disabling it is a security regression, view state encryption guarantees and the 170 KB ceiling, FLS/CRUD enforcement gaps on `<apex:outputField>` and on getters that return sObjects, `<apex:includeScript>` interaction with the org Content Security Policy, hosting LWC inside a VF page via `lightning:container` / `lightning-out`, and the retire-vs-harden-vs-leave-alone decision for an inventory of legacy pages. Triggers: 'should I rewrite this Visualforce page in LWC', 'CSRF protection disabled on Visualforce page is that safe', 'community user sees a field they should not on a Visualforce page', 'view state encryption is that enough for sensitive data', 'how do I host an LWC inside a Visualforce page', 'apex:dynamicComponent and apex:actionFunction safe to keep'. NOT for greenfield Visualforce architecture (use apex/visualforce-fundamentals — controller types, view state pattern selection, PDF rendering); NOT for Visualforce email template authoring (use apex/visualforce-email-templates if/when that skill is authored); NOT for general Apex security review across triggers and async (use apex/soql-security and security/secure-coding-review-checklist).
transaction-security-policies
Transaction Security policy creation and configuration: condition builder, enhanced policies, enforcement actions (block, MFA, notification, end session), real-time monitoring mode, and policy troubleshooting. NOT for Event Monitoring log analysis or Shield Event Monitoring setup (use event-monitoring). NOT for Apex testing or debug-log analysis.
sso-saml-troubleshooting
Diagnosing broken SAML SSO into Salesforce — IdP-initiated vs SP-initiated flows, signing-certificate validity / expiry, NameID format mismatches, RelayState handling, audience / entityId / issuer mismatches, clock skew, the SAML Assertion Validator in Setup, the Login History debug log, and the My Domain prerequisite for SSO. Covers the standard diagnostic loop: read the SAML response, identify which check failed, fix at the IdP or SP. NOT for OAuth / OpenID Connect SSO (see security/oauth-openid-troubleshooting), NOT for setting up SSO from scratch (see security/sso-saml-setup).
shield-kms-byok-setup
Configure Shield Platform Encryption with customer-supplied (BYOK) or customer-held (Cache-Only Key Service) tenant secrets, rotate them, and recover. NOT for Classic Encryption or field masking.