Intro

Since the inception of computer science, software engineers have attempted to understand the state and health of software systems. In modern programming, this practice is called observability. Observability systems use instrumentation—code which reports data about the system—to produce telemetry data. This telemetry data is then aggregated and analyzed to understand system operation. In this article, you’ll learn about different types of instrumentation, observability data, and how you can use instrumentation in your Salesforce environment to emit observability data.

Basics of Observability

Generally speaking, software observability deals with the ability to understand the internal state of software systems. Observability systems rely on the timely collection of telemetry information from the system. This information (sometimes called “signals”) comes in the form of metrics, logs, and traces.

• Metric: A point-in-time measurement of something (e.g., a method took n milliseconds).
• Trace: Tracks the flow of a transaction over time (often composed of many metrics).
• Log: Text-based information about what is happening, typically emitted on errors or exceptions.

Metrics and traces are structured and emitted continuously, while logs are usually unstructured and emitted when events occur. Observability tools aggregate these signals—for example, calculating the mean or median latency from trace data—to assess overall system health.

NOTE: The Open Telemetry Project standardizes telemetry APIs and formats, making it easier for vendors to build compatible observability solutions.

A Primer on Instrumentation

Instrumentation is the practice of emitting traces, metrics, and logs from a system’s components. It can be done in two ways:

1. Code-based instrumentation: Developers insert code to emit signals explicitly.
2. Agent-based (non-code) instrumentation: An agent injects logic at compile, deploy, or runtime to emit the desired signals.

In Salesforce (Apex), only code-based instrumentation is available. Extra care must be taken to minimize performance impact when adding instrumentation calls.

Instrumentation and Salesforce Customizations

Salesforce developers commonly use System.debug() to log execution details. For richer logging, tools like Nebula Logger require adding instrumentation calls (mantra.AudicityApex.track()) in Apex triggers or classes. This records transaction start/end points and details in custom objects.

Example simple trigger instrumentation:

trigger CampaignTrigger on Campaign (
    before insert, before update, before delete,
    after insert, after update, after delete, after undelete
) {
    mantra.AudicityApex.track();
}

In trigger frameworks, calls are placed at the very beginning (before) and end (after) of transactions to bookend execution.

Processity Data History and Instrumentation

Processity Data History provides a complete historical log of Salesforce data changes. It instruments Apex triggers, queueable classes, and Flows to capture transaction flow and record changes:

• Apex Triggers & Queueables: mantra.AudicityApex.track() in before and after contexts.
• Flows: After‑save Flow actions to bookend transactions when Apex ordering is unclear.

Data History instrumentation actions in a Salesforce Flow

Salesforce transaction visualised in the Data History transaction viewer

Building Observability and More

Once telemetry is emitted, observability tools can analyze structured (metrics/traces) and unstructured (logs) signals together to paint a complete picture of system health. Processity Data History doubles as a business process mining engine and an observability data source.

Instrumentation and Platform Events

Change Data Capture (CDC) events in Salesforce emit data changes but lack context on how code execution impacted those changes. CDC also has licensing and coverage limitations, making it insufficient for deep observability.

Summing Up Instrumentation

Instrumentation provides essential runtime data but requires careful planning to minimize performance impact. Processity Data History (formerly Audicity) offers a turnkey solution for comprehensive data history and telemetry in Salesforce.