Observability & Operational Reliability

Debug logs are not a Salesforce observability strategy

JSBC Labs17 October 20268 min read

A log is evidence, not awareness

A customer says an order disappeared between Salesforce and fulfilment. The support team asks an administrator to enable a trace flag, reproduce the problem and download a debug log. That may reveal one transaction, but it cannot show whether the failure began yesterday, affects one customer or five thousand, or is still accumulating. The organisation has a debugging procedure, not operational visibility.

Salesforce documents debug logs as records of database operations, system processes and errors produced while a transaction executes. It also documents ApexLog retention as finite. Those properties make logs useful for diagnosis, but reactive and selective. The JSBC Labs view is that observability starts when the system continuously exposes enough structured evidence to detect, scope and explain failure before a human guesses which user and time window to trace.

Start with the service, not the tool

Do not begin an observability programme by buying a dashboard or writing a logging framework. Begin with the business service Salesforce supports: lead capture, case routing, order submission, identity provisioning or consent activation. Define what healthy means in terms that operations and technology can both recognise: completion rate, end-to-end latency, backlog age, data accuracy and recovery time.

Salesforce Well-Architected separates the reliability designed into a solution from the operational discipline used to sustain it. Convert that principle into a small set of service-level indicators and objectives. A 99.9% Apex success rate is meaningless if the remaining failures are every high-value order. Measure the user outcome, segment it by risk and volume, and use platform measures to explain why the outcome moved.

Design three complementary signals

A practical Salesforce telemetry model needs events, metrics and diagnostic context. Events record discrete facts such as an integration request, Flow fault or batch failure. Metrics aggregate behaviour over time: p95 latency, failure ratio, queue depth, CPU distribution or API consumption. Diagnostic context preserves the detail needed to investigate a specific occurrence without making every transaction an unreadable transcript.

This is consistent with Salesforce Architects guidance, which distinguishes logging, metrics, tracing and alerting, and recommends designing observability from the initial architecture. Decide which signals each component must emit as part of its definition of done. If instrumentation is postponed until production, teams usually discover that the identifiers, timestamps and business context required for correlation were never retained.

Carry one correlation identity across boundaries

Most serious incidents cross more than one Salesforce transaction. A Lightning action starts Apex, publishes a platform event, wakes a subscriber and calls an external service. Separate logs can prove each step ran, yet still fail to show that they belong to the same business request. A timestamp is not a reliable join key when volume and retries increase.

Create a correlation identifier at the first controlled boundary and propagate it through asynchronous jobs, event payloads, callout headers and downstream responses. Pair it with stable business identifiers, component name, operation, outcome and duration. Salesforce Well-Architected explicitly identifies correlation across async chains and integrations as good practice. Keep the identifier non-sensitive and searchable so an operator can reconstruct one journey without exposing customer data.

Make failure a structured event

A catch block that writes System.debug and returns a friendly message has converted a visible exception into a silent operational defect. Handle expected conditions deliberately, but emit a structured failure signal with severity, component, operation, correlation ID, exception category and safe diagnostic context. Preserve the original cause; do not collapse every problem into a generic ‘processing failed’ message.

Use platform-provided signals where they fit. Salesforce publishes BatchApexErrorEvent for failures and exceptions in batch Apex classes that opt into platform events, including information about the failed scope. Event Monitoring can expose Apex unexpected exceptions for platform-event triggers. Custom telemetry is still needed for handled failures and business rejections, but it should complement standard evidence rather than duplicate it inconsistently.

Use Event Monitoring for its actual job

Event Monitoring provides operational evidence about user and platform activity, including API use, logins, Apex execution, queries and Lightning interactions. Salesforce exposes event log files through EventLogFile and documents how they can be integrated with external storage and analytics. That makes them valuable for security investigation, adoption analysis and performance diagnosis across an org.

It does not make every signal instantaneous or durable. Salesforce documents delivery delays, subscription-dependent retention, possible duplicates and potential gaps during exceptional platform operations. Design ingestion to query by creation time, deduplicate, record checkpoints and monitor its own freshness. If an alert must fire within minutes, verify that the selected real-time event and licence support that requirement instead of treating a daily file as a paging mechanism.

Include declarative automation

Observability fails when Apex is instrumented but Flow is treated as configuration. A record-triggered Flow can own a critical transaction, invoke subflows and Apex, create scheduled work and fail under a different execution identity. Monitoring only code creates a blind spot precisely where organisations expect low-code delivery to accelerate.

Use Salesforce’s Flow monitoring for paused and failed interviews, scheduled actions and element error rates, then connect those signals to the same service measures used for code. Fault paths should capture safe context and a correlation identifier before routing an operational event. Alert on repeated faults, ageing interviews and stalled business outcomes, not merely on every individual error email.

Control telemetry as production data

More logging is not automatically better. Customer records, authentication material, request bodies and personal data can turn an observability store into an unmanaged copy of the production database. Verbose instrumentation also consumes storage, increases query cost and makes the important signal harder to find during an incident.

Define an allowlist of fields for each event schema. Mask or hash sensitive identifiers, restrict access, document residency and set retention by operational and regulatory need. Use severity and sampling deliberately, but never sample away rare high-impact failures. Salesforce Well-Architected calls for access-controlled, retained and accountable telemetry; apply the same data governance to logs that you apply to business records.

Alert on impact, not noise

An alert for every exception teaches the on-call team to ignore alerts. A dashboard that nobody owns is merely decorative. Page someone when a service objective is at risk, data may be corrupted, security may be compromised or a queue is approaching an irreversible deadline. Route lower-severity trends to a review queue with an explicit response target.

Combine symptoms with context: failure rate plus transaction volume, latency plus backlog age, API consumption plus remaining headroom. Set thresholds from business tolerance and observed baselines, then test them during release validation. Every alert needs an owner, severity, runbook, escalation path and evidence link. If the first response is still ‘turn on a debug log and wait’, the alert has not shortened recovery.

Make observability part of architecture review

Add an operational contract to every important Salesforce component: service objective, emitted events, metrics, correlation method, sensitive-data rules, dashboards, alerts, runbook and owner. Review it with the transaction design and security model. Test that failures produce the expected telemetry, that asynchronous hops preserve identity, and that operators can find the right evidence with production-like permissions.

Debug logs remain indispensable when an engineer needs transaction detail. They should be the drill-down after continuous signals identify where and when to investigate—not the mechanism that tells the organisation a service is failing. A system becomes observable when its behaviour can be understood across boundaries under real operating conditions. That capability is architecture, not an administrator’s emergency ritual.