> 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/tracing/issue-tracing/trace-schedules.md).

# Trace Schedules

Understand the data model behind trace schedules and trace request structure.

A trace schedule defines when and how Pharos should capture debug logs for a specific issue. It controls the time windows during which tracing is active and automatically manages trace flags in Salesforce.

## Overview

Trace schedules consist of:

1. **Trace Schedule Record (`pharos__Trace_Schedule__c`):** The parent configuration that defines the overall tracing strategy for an Issue
2. **Trace Windows (`pharos__Trace_Request__c`):** Individual time periods when tracing is actively running (like calendar appointments) — each window is its own record, not a second date pair stored on the schedule itself
3. **Trace Results (`pharos__Trace_Result__c`):** The captured debug logs that match your criteria

## Trace Schedule Structure

### One Active Schedule Per Issue

Each issue can have only **one active trace schedule** at a time. To change your tracing strategy, deactivate the existing schedule and create a new one—this prevents conflicting trace flag configurations.

### Multiple Trace Windows

Within a single trace schedule, you can have **multiple trace windows**:

**Think of trace windows as calendar appointments:**

```mermaid
graph TD
    A[Trace Schedule: Opportunity Trigger Error]
    A --> W1[Trace Window 1: Today 9 AM - 5 PM]
    A --> W2[Trace Window 2: Tomorrow 9 AM - 5 PM]
    A --> W3[Trace Window 3: Friday 9 AM - 5 PM]
```

**Why Multiple Windows?**

* **Targeted monitoring:** Only trace during business hours when error is likely
* **API efficiency:** Avoid consuming API calls during off-peak times
* **User coordination:** Align with when specific users will be testing

**Under the Hood:**

* Each window is a separate `pharos__Trace_Request__c` record, linked to its parent schedule via the `pharos__Trace_Schedule__c` lookup, with its own `Start_Date__c`/`End_Date__c`
* Windows can be chained one to the next using `pharos__Parent__c` (a self-lookup pointing at the prior window) together with `pharos__Next_Trace_Start_Date__c`/`pharos__Next_Trace_End_Date__c`, which mark when the next window in that chain is due
* The schedule's own `Trace_Start_Date__c`/`Trace_End_Date__c` are a rollup — the earliest window start and latest window end across all its trace requests — not independently configured

## Automatic Completion

A trace schedule's `Status__c` isn't set directly — it's derived automatically from the state of its trace windows (`pharos__Trace_Request__c` records):

**Completion Behavior:**

```
Schedule with 3 trace windows:
  Window 1: Monday 9-5 → Completes
  Window 2: Tuesday 9-5 → Completes  
  Window 3: Wednesday 9-5 → Completes
  
Result: Schedule Status__c becomes "Completed" after Wednesday 5 PM
```

**Important:**

* This happens **regardless of whether logs were captured or not**
* After the last trace window passes, the schedule's status moves to `Completed`
* Trace flags are automatically removed from Salesforce
* To run another trace, you must create a new schedule (or add another trace window before the schedule completes)

## Creating a Trace Schedule

### From an Issue

1. **Navigate to the Issue** where you need debug logs
2. **Open the Tracing tab** (or Trace section)
3. **Click "New Trace Schedule"** or "Create Trace Schedule"
4. **Configure the schedule** (see configuration options below)
5. **Save** to activate

### Configuration Options

When creating a trace schedule, you'll configure:

**Target Users:**

* Which users to trace (all affected by issue, specific users, etc.)
* Profile-based targeting
* Individual user selection

**Trace Windows:**

* Start and end date/time for each window
* Multiple windows for intermittent monitoring
* Timezone specification

**Log Levels:**

* NONE
* ERROR
* WARN
* INFO (minimal)
* DEBUG (standard, recommended)
* FINE (detailed)
* FINER
* FINEST (maximum detail, largest logs)

**Captured Log Window Size:**

* Number of logs to capture around the error occurrence
* Default is **5** logs: a couple before the matching log, the matching log itself, and a couple after
* Configurable in **Pharos Admin → Tracing settings**

**Error Pattern:**

* Exact error message to match
* Stack trace elements
* Custom patterns

## Managing Trace Schedules

### Viewing All Schedules

You can review every trace schedule in one place, not just those tied to a single issue.

**Trace Schedules View:**

* Accessible from Pharos Admin or Tracing section
* Provides a big-picture view of all traces running across all issues
* Includes a **calendar view** to visualize when trace windows are active

**Calendar View Benefits:**

* See all active trace windows at a glance
* Identify overlapping traces (avoid trace flag limit)
* Plan new trace windows around existing ones

### Monitoring Active Schedules

While a schedule runs, several indicators show its current state at a glance.

**Active Schedule Indicators:**

* **Status field:** Scheduled, In Progress, Completed, or Inactive
* **Current window:** Which trace window is currently running (if any)
* **Logs captured:** Count of matching logs found so far
* **Next window:** When the next trace window will start

### Manually Stopping a Schedule

If you need to stop a schedule before it completes:

1. Navigate to the trace schedule record
2. Click "Stop" or "Deactivate"
3. Pharos removes trace flags from Salesforce
4. Schedule and its remaining trace windows are marked `Inactive`
5. Already-captured trace results remain available

**When to Manually Stop:**

* Issue is resolved before schedule completes
* You've captured enough logs for analysis
* You need to create a new schedule with different settings

## Trace Window Timing

### Time Window Behavior

A trace window turns tracing on at its start time and off at its end time, so monitoring only runs when you expect it to.

**During Active Window:**

```
Window: Monday 9 AM - 5 PM

At 9:00 AM:
  - Pharos creates trace flags for target users
  - Monitoring begins
  
Between 9 AM - 5 PM:
  - Pharos polls for new debug logs
  - Downloads and parses logs
  - Checks for error pattern match
  - Notifies when match found
  
At 5:00 PM:
  - Trace flags removed
  - Monitoring pauses until next window
```

**Between Windows:**

```
Gap: Monday 5 PM - Tuesday 9 AM

No trace flags active:
  - No new logs captured
  - API consumption stops
  - Users not being traced
  
Tuesday 9 AM:
  - Next window activates automatically
  - Trace flags recreated
  - Monitoring resumes
```

### Polling Frequency

Pharos checks for new debug logs at configurable intervals:

**Typical Settings:**

* **Every 5 minutes:** Active debugging, need immediate notification
* **Every 15 minutes:** Standard monitoring (default)
* **Every hour:** Low-priority issues, conserve API calls

This polling frequency is configured in Pharos Admin settings and applies to all trace schedules.

## Best Practices

### Start with Short Windows

**Strategy:**

```
First Attempt:
  - Single 4-hour window during peak usage
  - See if you capture the error
  
If no match:
  - Extend to 8-hour window
  - Or add multiple daily windows
```

**Reasoning:**

* Conserves API calls
* Limits trace flag usage
* Easier to analyze smaller set of logs

### Use Multiple Short Windows vs. One Long Window

**Multiple Short Windows (Recommended):**

```
Schedule:
  - Window 1: Monday 9-12 PM
  - Window 2: Tuesday 9-12 PM
  - Window 3: Wednesday 9-12 PM
  
Benefits:
  - Only trace during peak error occurrence time
  - Lower API consumption
  - More targeted log capture
```

**One Long Window:**

```
Schedule:
  - Window 1: Monday 9 AM - Wednesday 5 PM (continuous)
  
Drawbacks:
  - Higher API consumption
  - More logs to sort through
  - Trace flags active even during off-peak times
```

### Align with User Activity

If you know when users typically encounter the error:

```
E-commerce Example:
  Error: Checkout flow failure
  Peak times: Weekday lunch hours
  
Optimal Schedule:
  - Monday 11 AM - 2 PM
  - Tuesday 11 AM - 2 PM
  - Wednesday 11 AM - 2 PM
```

### Monitor API Usage

Each trace schedule consumes API calls:

* Creating trace flags
* Polling for logs
* Downloading logs
* Removing trace flags

**Monitoring:**

* Check API usage in Setup → System Overview
* Pharos typically uses <1% of daily API limit
* Scale back polling frequency if needed

## Trace Schedule Lifecycle

A trace schedule's `Status__c` reflects the state of its trace windows (`pharos__Trace_Request__c` records) and updates automatically as those windows progress.

**Lifecycle States (`Status__c`):**

```
1. Scheduled   → At least one trace window is still upcoming
2. In Progress → A trace window is currently active, flags active
3. Completed   → All trace windows have ended
4. Inactive    → Manually stopped
```

**State Transitions:**

```
Scheduled → In Progress:
  - A trace window's start time is reached
  - That window's Trace_Request__c status becomes "In Progress"
  - Trace flags created

In Progress → Scheduled or Completed:
  - Trace window's end time is reached, its status becomes "Inactive"
  - Schedule status reflects whichever trace windows remain
    (a later "Scheduled" window, or "Completed" if none remain)
  - Trace flags removed

Any State → Completed:
  - The last trace window's end time has passed
  - Set automatically regardless of whether logs were captured

Any State → Inactive:
  - User manually stops the schedule
  - Its trace windows are marked Inactive too
  - Trace flags removed (if active)
```

## Troubleshooting

### Schedule Not Capturing Logs

**Possible Causes:**

1. **Error pattern mismatch:** Debug log doesn't contain exact error message
2. **Error not occurring:** Issue hasn't happened during trace window
3. **Wrong users traced:** Error occurring for users not included in schedule
4. **Log level too low:** INFO level may not capture necessary detail

**Solutions:**

* Broaden error pattern (use partial match instead of exact)
* Extend trace windows or add more windows
* Expand user targeting
* Increase log level to DEBUG or FINE

### Trace Flag Limit Reached

**Salesforce Limit:** Subject to Salesforce's trace-flag limits per org

**Symptoms:**

* Error message when creating trace schedule
* Trace window's `Status__c` stays `New` and never moves to `In Progress`

**Solutions:**

* Stop other active trace schedules
* Reduce number of target users
* Coordinate with other admins on trace flag usage
* Pharos rotates trace flags when possible (prioritizes users most likely to hit error)

### Schedule Didn't Auto-Complete

**Possible Causes:**

* Trace window end time in the future
* System job delay

**Solution:**

* Wait up to 1 hour for scheduled job to run
* Manually stop the schedule if urgent

## Viewing Trace Schedules

### From an Issue

**Issue Detail Page → Tracing Tab:**

* Shows trace schedules for this specific issue only
* Quick access to create new schedule
* View results linked to this issue

### From Admin Section

**Pharos Admin → Notifications → Trace Results** (or Trace Schedules):

* Shows all trace schedules across all issues
* Org-wide view
* Filter by status, date range, etc.

**Calendar View:**

* Visual representation of all trace windows
* Click a window to see schedule details
* Helps plan new traces to avoid conflicts

## Integration with Trace Results

Once a trace schedule captures matching debug logs, [Trace Results](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md) are created:

* Each captured log becomes a Trace Result record (`pharos__Trace_Result__c`)
* Results are linked to the specific trace window that captured them (`pharos__Trace_Request__c`) as well as the parent Trace Schedule (`pharos__Trace_Schedule__c`)
* Results are also linked to the Issue
* Notification sent when result created (if configured)

## Next Steps

* Learn how to [view and analyze Trace Results](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md)
* Review the main [Tracing documentation](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md) for broader context
* Explore [AI Analysis](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis.md) capabilities for automated log analysis
