> 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/configuration-guide/issue-tracker.md).

# Issue Tracker

Configure AI-powered Issue Analysis in Pharos Admin using the Issue Tracker settings page.

The Issue Tracker page in Pharos Admin configures **AI Issue Analysis** — the feature that uses OpenAI to provide root cause analysis, severity estimates, resolution suggestions, and impact assessments for your Pharos issues.

Pharos runs analysis asynchronously in its cloud and communicates results back to your Salesforce org via a Platform Event (`pharos__AI_Event__e`). This page walks you through the one-time setup to enable that communication channel.

{% hint style="info" %}
For Issue Tracker concepts — how logs are aggregated into issues, triaging workflows, occurrence charts, and impact metrics — see [Issue Tracker Overview](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker.md).
{% endhint %}

***

## Prerequisites

| Requirement                    | Details                                                                                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI integration enabled** | Configure in [Pharos Admin → Integrations → OpenAI](https://docs.pharos.ai/configuration-guide/integrations/openai.md)                                                             |
| **OpenAI API key**             | Your own OpenAI key — or request one from <success@pharos.ai> if you don't have an OpenAI account. See [OpenAI](https://docs.pharos.ai/configuration-guide/integrations/openai.md) |
| **Admin access**               | System Administrator or equivalent in Salesforce                                                                                                                                   |

***

## Before OpenAI Is Configured

If the OpenAI integration has not been set up, the Issue Tracker page displays a prompt directing you to configure it first:

![Issue Tracker — Analysis Status showing "Setup OpenAI" button when OpenAI is not yet configured](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-f99fa0b9d956e9cdcee4b716a33820d03a0790e8%2Fissue-tracker-no-openai.png?alt=media)

Click **Setup OpenAI** to navigate to the [OpenAI integration settings](https://docs.pharos.ai/configuration-guide/integrations/openai.md), enter your API key, and save. Then return to this page to continue setup.

***

## Platform Event Setup

Once OpenAI is configured, the page shows a checkmark next to **Analysis Status** and reveals the Platform Event Setup section. Pharos uses Platform Events to communicate between its cloud system and your Salesforce org — analysis runs asynchronously in the background and requires this mechanism to deliver results back.

![Issue Tracker — Full setup page showing Analysis Status checkmark, Context User, Suspend, Resume, and Test steps](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-6ed3e4fc9e007a52f6757358e77170114a98fd99%2Fissue-tracker-setup.png?alt=media)

Complete the following steps in order:

{% stepper %}
{% step %}

### 1. Context User

Select the user on whose behalf the Platform Event subscription will execute. This is typically the **Pharos Admin** user or another admin-level user with appropriate permissions. Click **Apply** to save the selection.
{% endstep %}

{% step %}

### 2. Suspend Platform Event Subscription

Click the **Suspend** button to pause the existing `AiEventTrigger` subscription in the Salesforce Platform Event Subscription management page. The trigger state will change from **Running** to **Suspended**.
{% endstep %}

{% step %}

### 3. Resume Platform Event Subscription

After suspending, click **Resume** to re-establish the subscription under the context user you selected. This resets the subscription so it picks up the new configuration.

![AiEventTrigger Details — Suspended state with Resume and Resume from Tip buttons](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-2775955f4f26bbdd78409884e5590e6d0b02d336%2Fissue-tracker-resume.png?alt=media)
{% endstep %}

{% step %}

### 4. Run a Test

Click the **Test** button to verify that custom logs and AI events are generated correctly. This confirms the Platform Event pipeline is working end-to-end.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
This suspend-and-resume cycle is the same pattern used when configuring Pharos Triton Platform Events — it re-registers the Apex trigger subscription with the updated context user. For the Triton equivalent (the **Configuration** tab on the Pharos Admin → Advanced → Triton page), see the [Triton documentation](https://triton.pharos.ai).
{% endhint %}

***

## What AI Analysis Provides

Once configured, AI analysis is available from the **Analysis** tab on any issue detail page. You run it on demand — click the analyze button, and results are returned asynchronously.

Every analysis returns the same five components in the same order: severity assessment, problem explanation, root cause indicators, impact analysis, and recommended next steps. See [Analysis Components](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/issue-analysis.md#analysis-components) for what each one draws on and how to read it.

{% hint style="info" %}
Analysis quality depends on the amount of context available. Issues with detailed stack traces, flow metadata, or multiple occurrences produce richer results. Sparse issues may yield generic suggestions — run analysis again for potentially different (and sometimes better) output.
{% endhint %}

***

## Troubleshooting

| Issue                             | Cause                                  | Resolution                                                 |
| --------------------------------- | -------------------------------------- | ---------------------------------------------------------- |
| "Setup OpenAI" prompt still shown | OpenAI integration not saved           | Go to Integrations → OpenAI, enter API key, save           |
| Analysis never returns results    | Platform Event subscription not active | Re-run the Suspend → Resume cycle on this page             |
| Test button fails                 | Context user lacks permissions         | Select an admin-level user and re-apply                    |
| Analysis gives sparse output      | Issue has limited metadata             | Run analysis multiple times; results are non-deterministic |

***

## Related

* [OpenAI Integration](https://docs.pharos.ai/configuration-guide/integrations/openai.md) — API key setup
* [Issue Tracker Overview](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker.md) — Concepts, lifecycle, triaging
* [Notifications](https://docs.pharos.ai/configuration-guide/notifications.md) — Get alerted when new issues are created
* [Ticketing](https://docs.pharos.ai/configuration-guide/ticketing.md) — Create tickets from issues
