SfSkills Domains Docs GitHub

Home / apex / apexguru-performance-analysis

apexguru-performance-analysis

Run and interpret the ApexGuru engine in Salesforce Code Analyzer v5 for Apex performance and scalability findings: verify the authenticated target org, scope .cls/.trigger files, capture JSON evidence, triage line-level recommendations, validate fixes, and avoid claiming runtime telemetry the report does not contain. Trigger keywords: ApexGuru scan, apexguru Code Analyzer, Apex performance findings, SOQL scalability issue, AI Apex optimization. NOT for general PMD/security lint — use devops/salesforce-code-analyzer. NOT for Apex debug-log or production transaction profiling.

Open the skill folder on GitHub

ApexGuru Performance Analysis

Use ApexGuru as one evidence source for Apex performance work. In Salesforce Code Analyzer v5 it is an AI-driven remote analysis engine that requires an authenticated Salesforce org, scans Apex .cls and .trigger files, and returns line-level JSON findings. A connected org is required for the service; that fact alone does not prove the report contains production runtime telemetry.

Preconditions

Confirm all of the following before scanning:

CheckRequired evidenceStop condition
Code Analyzer generationsf code-analyzer --help or installed plugin version confirms v5 commandsLegacy sfdx scanner:* only
Target identityExact org alias/username resolved by Salesforce CLIAlias absent, ambiguous, or unauthenticated
ApexGuru availabilityOrg supports and has ApexGuru activatedEngine unavailable or activation unknown for a required scan
WorkspaceExplicit project/workspace rootAccidental scan of a home or monorepo root
TargetsBounded .cls and .trigger files inside the workspaceRequest expects Flow, metadata XML, objects, or other unsupported files
BaselineCurrent commit/hash, tests, and scan output pathFindings cannot be tied to source revision
AuthorityRead/analysis operation only; no production mutation impliedRequest asks the scan to approve or deploy a fix

Authentication is reused from the Salesforce CLI session. Do not put usernames, passwords, access tokens, or refresh tokens in code-analyzer.yml.

Reproducible CLI Scan

Use Code Analyzer v5 and write machine-readable output:

sf code-analyzer run \
  --rule-selector apexguru \
  --workspace . \
  --target "force-app/main/default/classes/**/*.cls" \
  --target "force-app/main/default/triggers/**/*.trigger" \
  --target-org my-apexguru-org \
  --view detail \
  --output-file artifacts/apexguru-results.json

Important behavior:

For the installed CLI, verify flags with:

sf code-analyzer run --help

Project Configuration

A project can set ApexGuru engine defaults in code-analyzer.yml:

engines:
  apexguru:
    disable_engine: false
    target_org: my-apexguru-org
    api_timeout_ms: 300000
    api_initial_retry_ms: 2000
    api_max_retry_ms: 60000
    api_backoff_multiplier: 2

The shown timeout/backoff values are documented defaults. Change them only for an observed need and keep api_max_retry_ms >= api_initial_retry_ms. The overall api_timeout_ms remains the hard budget.

Prefer an explicit --target-org in CI when multiple authenticated orgs exist; it is easier to audit than relying on a developer's default org. Never commit secret material.

Evidence Mode and Attribution

Classify the output before interpreting it:

ModeWhat may be claimed
Code Analyzer ApexGuru JSONApexGuru analyzed the identified source revision through the authenticated org service and returned these findings
Report explicitly carries analysisMode: staticPreserve the label Static only; do not infer production behavior
Report explicitly carries analysisMode: full or a documented equivalentPreserve the report's exact label and evidence; identify which metrics are actually present
No mode field or runtime metricsLabel Source analysis; do not call it production telemetry, hotspot frequency, or measured runtime impact
Debug logs, Event Monitoring, APM, or transaction tracesTreat as separate runtime evidence and link it to the source finding without attributing it to ApexGuru unless the report says so

A finding's severity is the engine's prioritization, not a measured CPU/heap/query cost. Validate impact in the relevant transaction and data-volume context.

JSON Result Contract

Code Analyzer v5 JSON contains a root object with runDir, violationCounts, versions, and violations. Each violation should preserve:

Do not flatten multi-location findings to one line when the analysis path matters. CSV includes only the primary location; JSON or SARIF is preferable for review and automation.

  1. Validate provenance and scope — source revision, workspace, authenticated target org, command, Code Analyzer/engine versions, .cls/.trigger targets, timestamp, and output hash.
  2. Normalize and group findings with the bundled checker while preserving original JSON. Group by rule, affected transaction/entry point, shared query/DML pattern, and severity—not severity alone.
  3. Inspect code context around every primary and related location, and confirm that the finding applies to a reachable path.
  4. Cross-check runtime relevance using tests, data volume, query plans, debug logs, transaction traces, or production insights when authorized and available.
  5. Choose a disposition and design the smallest safe change: fix, validate, suppress-with-rationale, defer, or not-applicable. Preserve sharing, CRUD/FLS, transaction semantics, bulk behavior, ordering, and error handling.
  6. Test and rescan positive, negative, bulk, and failure paths, then rerun the same targets with the same engine/config and compare result hashes/findings.
  7. Record residual risk and supporting evidence. A zero-finding scan is not proof of runtime performance or absence of all Apex defects.

Disposition Criteria

DispositionUse whenRequired record
fixFinding is applicable and a safe change is understoodChange, tests, before/after scan, runtime or scale rationale
validateApplicability or impact depends on data shape or call pathExact experiment/query plan/log evidence needed
suppress-with-rationaleFinding is accepted, false positive, generated code, or unavoidable under a documented constraintScope-limited suppression, owner, review trigger, risk
deferValid issue is lower priority than current risk/capacityBacklog owner, severity rationale, review date/trigger
not-applicableCode path or assumption does not applyReproducible evidence; do not dismiss from intuition

Never auto-apply generated fixes. Performance changes can alter correctness, locking, sharing, query selectivity, memory, and transaction boundaries.

Validation Checklist

Result Validation Command

python3 skills/apex/apexguru-performance-analysis/scripts/check_apexguru_performance_analysis.py \
  --input artifacts/apexguru-results.json \
  --output artifacts/apexguru-normalized.json

The checker validates the Code Analyzer JSON shape, severity/location data, Apex file scope, and evidence-mode labeling. It does not contact Salesforce or judge whether a recommendation is correct.

See the bundled references for triage examples, attribution failures, and the official source map.

Dependencies

Package files