> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-presentations/transaction-parent-logs.md).

# Transaction (Parent) Logs

Learn about parent (transaction) log presentations and Triton transaction logging.

Transaction logs provide visibility into **logical business processes** that span multiple Salesforce transactions or extend into external systems. Using Pharos Triton's transaction tracking capability, you can group related logs together under a single parent log, keyed on a shared transaction ID, for end-to-end tracing.

{% hint style="success" %}
**End-to-End Tracing:** Business processes rarely fit into a single Salesforce transaction. Triton's logical transactions group related logs across triggers, queueables, flows, and external callouts—providing complete visibility into multi-step workflows.
{% endhint %}

## Understanding Transactions vs. Salesforce Transactions

A Salesforce transaction is a single execution context, but business processes span many of them—so Triton introduces a logical transaction to tie them together.

### The Challenge: Salesforce's Transaction Model

In Salesforce, a "transaction" is typically a single execution context:

* One trigger execution
* One queueable job
* One batch execute() invocation
* One Flow interview
* One API request

**Business processes rarely fit into a single transaction.** They often involve:

```
User Action (LWC)
  → Trigger Processing (Apex)
    → Asynchronous Job (Queueable)
      → Flow Orchestration
        → External System Callout
          → Scheduled Cleanup (Batch)
```

Each arrow represents a **new Salesforce transaction** with no native way to trace them together.

### Triton's Solution: Logical Transactions

Triton introduces the concept of a **logical transaction** using a unique identifier (GUID):

```
Transaction ID: 550e8400-e29b-41d4-a716-446655440000

Log 1: [LWC] User clicked "Submit Order" button
Log 2: [Trigger] Order validation passed  
Log 3: [Queueable] Inventory check completed (15 units available)
Log 4: [Queueable] External system callout initiated
Log 5: [External API] ERP sync response received (HTTP 200)
Log 6: [Flow] Fulfillment records created (3 line items)

All logs share the same Transaction ID → grouped as one logical operation
```

This approach provides **end-to-end tracing** across platform boundaries while working within Salesforce's transaction model.

Under the hood, child logs link to a parent via the Log Parent self-lookup, matched on a shared transaction Id, flow interview GUID, or request Id—so grouping also applies to Flow interviews and inbound requests, not only Triton transaction Ids.

## How Transaction Logs Work

Transaction logging follows three steps: start a transaction, propagate its ID across execution contexts, and view the grouped logs.

### 1. Starting a Transaction

At the entry point of a business process, call `Triton.startTransaction()`. It generates a GUID, returns it, and stamps it on every log that follows. The ID is the whole transaction—there is no transaction object, name, or parent transaction.

**Key Concepts:**

* **Transaction ID:** Unique GUID identifying the logical operation
* **Resuming:** Each downstream Apex context adopts the same ID with `Triton.resumeTransaction(id)`; a Flow passes it to the Log action's **Transaction ID** input
* **Spans:** Within a transaction, spans record which work happened inside which—see [Nesting with Spans](#nesting-with-spans)

### 2. Propagating the Transaction ID

The critical step is **passing the Transaction ID** across execution contexts:

**Example: Trigger → Queueable**

```
Trigger:
  1. Starts a transaction: Triton.startTransaction() → abc-123
  2. Logs: "Validation passed"
  3. Enqueues job, passes Transaction ID to queueable constructor

Queueable:
  1. Receives Transaction ID: abc-123
  2. Resumes it: Triton.resumeTransaction('abc-123')
  3. Logs: "Inventory checked" (linked to same transaction)
```

**Example: Apex → Platform Event → Flow**

```
Apex:
  1. Transaction ID: xyz-789
  2. Publishes platform event with Transaction ID in payload

Flow:
  1. Triggered by platform event
  2. Extracts Transaction ID from event
  3. Passes it to the Log action's Transaction ID input
  4. All flow logs linked to same transaction
```

**Example: Salesforce → External System → Salesforce**

```
Apex (outbound):
  1. Transaction ID: def-456
  2. Includes Transaction ID in API request header or body

External System:
  1. Receives Transaction ID
  2. Returns it in response or callback

Apex (inbound):
  1. Extracts Transaction ID from response
  2. Resumes it: Triton.resumeTransaction(id)
  3. Logs final status
```

### 3. Viewing Transaction Logs

In the Pharos Log Viewer, transaction logs are displayed with parent-child relationships:

```mermaid
graph TD
    T[Transaction ID: abc-123<br/>Created: 2026-01-12 10:15:23]
    T --> L1[10:15:23.125 LWC: Order form submitted by John Doe]
    T --> L2[10:15:23.450 Apex Trigger: Validation rules passed]
    T --> L3[10:15:24.100 Apex Trigger: Inventory service callout started]
    T --> L4[10:15:26.875 Queueable: Inventory check - 15 units available]
    T --> L5[10:15:27.200 Queueable: ERP sync initiated]
    T --> L6[10:15:35.500 External System: ERP returned Order Number ORD-9876]
    T --> L7[10:15:36.100 Flow: Created 3 fulfillment line items]
    T --> L8[10:15:37.650 Flow: Order marked as Confirmed]
```

**Benefits:**

* See the complete timeline of a business process
* Identify which step took the longest (performance bottleneck)
* Pinpoint exact failure point when errors occur
* Understand the sequence of events leading to an issue

## Use Cases for Transaction Logging

Transaction logging is valuable wherever a process crosses execution boundaries, from integrations to approvals to batch jobs.

### Use Case 1: Complex Integration Workflows

**Scenario:** Order synchronization between Salesforce and external ERP

**Challenge:** Orders occasionally fail to sync, but it's unclear at which point

**Solution with Transaction Logging:**

```
Step 1: Order__c After Insert Trigger
  - Log: "Order ready for sync, validating required fields"
  
Step 2: OrderSyncQueueable Job
  - Log: "Validation passed, preparing ERP payload"
  - Log: "Making HTTP POST to ERP endpoint"
  
Step 3: ERP System (logs returned via callback)
  - Log: "ERP received order, assigned ID: ERP-12345"
  
Step 4: OrderConfirmationHandler (processes callback)
  - Log: "Order sync confirmed, updating Salesforce record"
  
Step 5: Flow (triggered by field update)
  - Log: "Sending confirmation email to customer"

Outcome: If sync fails, you know exactly which step failed and why
```

### Use Case 2: Multi-Step Approval Processes

**Scenario:** Expense approval workflow with multiple approvers and notifications

**Challenge:** Track the entire approval journey, including delegations and escalations

**Solution with Transaction Logging:**

```
Step 1: LWC - Employee Submission
  - Log: "Employee ID: 005xxx submitted expense $1,250.00"
  
Step 2: Apex Trigger - Routing Logic
  - Log: "Amount > $1,000, requires Director approval"
  - Log: "Assigned to Director: Jane Smith"
  
Step 3: Flow - Approval Notification
  - Log: "Slack notification sent to #approvals channel"
  
Step 4: Apex Process - Director Approval
  - Log: "Director approved, escalating to VP for amounts > $1,000"
  
Step 5: Flow - VP Notification
  - Log: "Email sent to VP: Mike Johnson"
  
Step 6: Apex Process - VP Approval
  - Log: "VP approved, final approval complete"
  
Step 7: Flow - Confirmation
  - Log: "Expense status updated to Approved"
  - Log: "Email sent to employee confirming approval"

Outcome: Complete audit trail of approval workflow for compliance
```

### Use Case 3: Batch Job Monitoring

**Scenario:** Nightly batch job processes thousands of records with multiple stages

**Challenge:** When batch fails, need to know which records were processed before failure

**Solution with Transaction Logging:**

```
Batch Start:
  - Log: "Batch job started, scope size: 200 records per batch"
  
Batch Execute 1:
  - Log: "Processing batch 1 of 50 (records 1-200)"
  - Log: "Archived 198 records, 2 skipped (validation errors)"
  
Batch Execute 2:
  - Log: "Processing batch 2 of 50 (records 201-400)"
  - Log: "Archived 200 records, 0 skipped"
  
...
  
Batch Execute 25:
  - Log: "Processing batch 25 of 50 (records 4801-5000)"
  - Log: "ERROR: Governor limit exception (Too many SOQL queries)"
  
Batch Finish:
  - Log: "Batch completed with errors. Successfully processed 4,800 of 10,000 records"

Outcome: Know exactly where batch failed and how many records were processed
```

### Use Case 4: User Experience Tracking

**Scenario:** Multi-screen wizard for product configuration

**Challenge:** Users abandon the process—where do they drop off?

**Solution with Transaction Logging:**

```
Screen 1:
  - Log: "User started wizard, selected Product Category: Electronics"
  
Screen 2:
  - Log: "User selected Product: Laptop, Model: XPS-15"
  
Screen 3:
  - Log: "User added 3 accessories: Mouse, Keyboard, Monitor"
  
Screen 4:
  - Log: "User clicked 'Calculate Price', total: $2,450.00"
  
Screen 5:
  - Log: "User viewed payment options"
  - [NO FURTHER LOGS - USER ABANDONED]

Outcome: Analyze 100 sessions, discover 60% abandon at Screen 5
Action: Investigate payment options UI for usability issues
```

## Best Practices

The following practices keep transaction logs focused, readable, and reliable across execution boundaries.

### 1. Choose Transaction Boundaries Wisely

**Good Transaction Boundaries:**

* Complete business process (Order Creation)
* User-initiated workflow (Lead Conversion)
* Scheduled job execution (Nightly Data Sync)

**Poor Transaction Boundaries:**

* Individual method calls (too granular)
* Entire day's activity (too broad)
* Unrelated operations grouped together (confusing)

### 2. Start Once, Resume Everywhere

Call `Triton.startTransaction()` only at the true entry point—the user action or the scheduled job that kicks the process off. Every downstream context resumes the existing ID instead:

**Bad:**

```
Queueable:
  Triton.startTransaction()   → new ID; everything logged afterward is cut off from the trace
```

**Good:**

```
Queueable:
  Triton.resumeTransaction(id) → joins the trace the trigger started
```

### 3. Always Propagate Transaction IDs

When your process crosses execution boundaries, **always pass the Transaction ID**:

**Passing via Constructor:**

```apex
// Caller (for example, a trigger handler)
System.enqueueJob(new MyQueueable(Triton.startTransaction()));

public class MyQueueable implements Queueable {
    private String transactionId;
    
    public MyQueueable(String txId) {
        this.transactionId = txId;
    }
    
    public void execute(QueueableContext context) {
        Triton.resumeTransaction(this.transactionId);
        // ... work and logging, all linked to the same transaction
    }
}
```

**Passing via Platform Event:**

```apex
My_Event__e evt = new My_Event__e(
    Transaction_Id__c = transactionId,
    // other fields...
);
```

**Passing via HTTP Header:**

```apex
HttpRequest req = new HttpRequest();
req.setHeader('X-Transaction-Id', transactionId);
```

### 4. Log Key Milestones, Not Everything

**Avoid Over-Logging:**

```
❌ Log every variable assignment
❌ Log every loop iteration
❌ Log every conditional check
```

**Log Strategic Points:**

```
✓ Process start and end
✓ Decision points (if/else outcomes)
✓ External system interactions
✓ Error conditions
✓ Performance checkpoints (elapsed time)
```

### 5. Include Contextual Information

**Minimal (Not Useful):**

```
Log: "Processing record"
```

**Contextual (Actionable):**

```
Log: "Processing Account record (Id: 001xxx, Name: Acme Corp) 
      for territory assignment. Current territory: West, New territory: East"
```

## Nesting with Spans

Transactions don't nest—there are no parent or child transactions. To show which work happened inside which, Triton uses **spans**: every log carries a Span Id and a Parent Span Id, and together they turn a flat list of logs into a tree. The LWC logger builds this tree for you. In Apex, performance marks do it: logs written between `Triton.startMark('...')` and `Triton.endMark()` are parented to that mark, and marks can nest inside one another.

**Example: Bulk Order Import** — one transaction for the whole import, one mark per order

```mermaid
graph TD
    P[Transaction ID: abc-123 - bulk order import]
    C1[Mark: Order ORD-001]
    C2[Mark: Order ORD-002]
    C3[Mark: Order ORD-003]
    P --> C1
    P --> C2
    P --> C3
    C1 --> L1a[Validate order]
    C1 --> L1b[Check inventory]
    C1 --> L1c[Create fulfillment]
    C2 --> L2a[Validate order]
    C2 --> L2b[Check inventory]
    C2 --> L2c[Create fulfillment]
    C3 --> L3a[Validate order]
    C3 --> L3b[WARN: Low inventory - only 2 units]
    C3 --> L3c[Create backorder]
```

**Benefits:**

* Trace individual order processing within bulk operation
* Identify which specific orders failed in a batch
* Maintain high-level summary + detailed drill-down capability

See [Spans & Distributed Tracing](https://triton.pharos.ai/end-to-end/spans-and-tracing) and [Performance Marks](https://triton.pharos.ai/common-apex-usage-patters/performance-marks) in the Triton docs.

## Transaction Performance Metrics

Transaction logs automatically track performance metrics:

* **Duration:** Total time from first log to last log
* **Log Count:** Number of log entries in transaction
* **Error Count:** Number of logs with severity ERROR or higher
* **Related Records:** Count of records involved in transaction

These metrics help identify performance bottlenecks and high-impact processes.

## Integration with Pharos Issue Tracker

When errors occur within a transaction:

1. Individual error logs are fingerprinted and grouped into Issues
2. Issues maintain reference to the Transaction ID
3. From an Issue, you can view all transactions that experienced the error
4. From a Transaction log, you can see related Issues

This bidirectional relationship enables:

* Understanding how many transactions are affected by an issue
* Tracing the complete context around an error occurrence

## Summary

Transaction logging with Pharos Triton enables end-to-end tracing of logical business processes that span multiple Salesforce transactions or extend into external systems.

**Key Capabilities:**

* **Logical Transactions:** Group related logs across triggers, queueables, flows, and external callouts using shared Transaction ID
* **End-to-End Tracing:** Visual execution timeline showing complete workflow from initiation to completion
* **Cross-Platform Visibility:** Track processes that span Salesforce and external systems
* **Performance Analysis:** Cumulative statistics across all child logs (total CPU, SOQL, DML, duration)
* **Failure Isolation:** Pinpoint which step in multi-step process failed
* **Issue Correlation:** Link transaction patterns to recurring issues

**The Result:** By using a consistent Transaction ID across execution contexts, you gain complete visibility into complex workflows, pinpoint failure points quickly, and understand performance characteristics of your business processes.

{% hint style="info" %}
**For Developers:** Detailed API documentation on creating and managing transactions in Apex, LWC, and Flows is available in the dedicated Triton documentation site.
{% endhint %}
