> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracelit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Incidents

> How Tracelit detects, opens, and manages incidents for sites and backend services — gates, severity, and the path into resolution.

Incidents are Tracelit's unit of "something broke." They are opened from frontend alerts or backend telemetry, enriched with context, and (when enabled) handed to [AI Resolutions](/agentic/resolutions).

<Tip>
  Whether incidents can open in a given environment is controlled in **Utilities → Environment**. See [Utilities](/agentic/utilities).
</Tip>

***

## Where incidents come from

| Source              | What opens an incident                                                         |
| ------------------- | ------------------------------------------------------------------------------ |
| **Frontend site**   | JavaScript errors, failed API calls, and related alert rules on the site       |
| **Backend service** | Exceptions, error spikes, and related signals from OpenTelemetry logs / traces |

Detection only runs when the environment's **Allow incidents** gate is on. Local backend traffic often keeps incidents off by design.

***

## Environments

| Asset                 | Supported environments               |
| --------------------- | ------------------------------------ |
| **Site (frontend)**   | `development`, `production`          |
| **Service (backend)** | `local`, `development`, `production` |

Incidents are scoped to the environment that produced the signal. Archiving a site or service stops new incidents for **all** of its environments.

***

## Incident lifecycle

<Steps>
  <Step title="Detected">
    Tracelit fingerprints the error or anomaly. New fingerprints (or spikes above baseline) open an incident.
  </Step>

  <Step title="Open">
    The incident appears in the Incidents list with severity, summary, and linked evidence (replay for sites; logs / traces for services).
  </Step>

  <Step title="Investigating">
    Your team reviews the timeline, attributes, and linked telemetry. Notifications can include Slack when connected.
  </Step>

  <Step title="Resolution (optional)">
    If resolutions are enabled for that environment and a repository is linked, you can start an [AI Resolution](/agentic/resolutions) from the incident.
  </Step>

  <Step title="Resolved or ignored">
    Mark resolved when fixed, or ignore known noise. Ignored fingerprints will not keep reopening as active work.
  </Step>
</Steps>

***

## What an incident includes

| Field           | Description                                            |
| --------------- | ------------------------------------------------------ |
| **Severity**    | Based on signal type and volume                        |
| **Summary**     | Short description of what failed                       |
| **Environment** | `local` / `development` / `production` (as applicable) |
| **Evidence**    | Session replay (frontend) or logs / traces (backend)   |
| **Timeline**    | Status changes and activity                            |
| **Share link**  | Optional public share for an incident (when enabled)   |

***

## Enabling incidents

<Steps>
  <Step title="Open Utilities">
    Select the site or service in the app rail, then open **Utilities**.
  </Step>

  <Step title="Environment tab">
    For each environment, enable **Allow Incidents Run**.
  </Step>

  <Step title="Save">
    Gates apply immediately to new telemetry. Existing open incidents are unchanged.
  </Step>
</Steps>

<Warning>
  If incidents never appear, check the environment gate first — then confirm ingest is reaching Tracelit for that environment.
</Warning>

***

## Notifications

Connect Slack under **Settings → Integrations**. Incident cards can include severity, summary, and a link back to the dashboard.

***

## Next

| Topic                       | Guide                                |
| --------------------------- | ------------------------------------ |
| Turn errors into PRs        | [Resolutions](/agentic/resolutions)  |
| Gates, keys, repo, archive  | [Utilities](/agentic/utilities)      |
| Backend OpenTelemetry setup | [Telemetry overview](/otel/overview) |