> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/events.md).
# Events
Events is the searchable history and diagnostics viewer for CrossWatch sync activity.
Use it to understand what CrossWatch attempted, what succeeded, what failed, and why.
{% hint style="info" %}
Events is diagnostic only. It does not change provider data, repair items, or retry operations.
{% endhint %}
### When to use Events
Use Events to:
* Confirm that a sync started and completed.
* Investigate failed, unresolved, or blackboxed operations.
* Trace an item across runs and provider routes.
* Compare a historical event with current CrossWatch state.
* Copy diagnostic data for a support request.
Use [Analyzer](/crosswatch/main-dashboard/tools/analyzer.md) to compare current provider baselines.
### Open Events
Open the CrossWatch Main dashboard, then select **Events**.
The window has two panels:
* The event list.
* Details for the selected thread or event.
Drag the divider to resize the panels. The browser remembers the selected size.
### How Events works
CrossWatch records structured sync activity in a local SQLite archive.
It correlates related records into readable run and item threads. Opening a thread also loads current configuration and local state.
Historical timelines remain unchanged. Current context is calculated when you open a thread.
This means a historical **Unresolved** thread can show no current unresolved state.
### Choose a view
#### Grouped
**Grouped** is the default view. It combines related records into threads.
A thread can represent a sync run, item operation, provider health result, or planning sequence.
Sync runs appear as parent threads. Problem items appear below their run when available.
Each row can show:
* Status and readable summary.
* Event count, feature, route, and latest event time.
* Whether you acknowledged the record.
Select the arrow next to a run to show or hide its problem items.
#### Raw events
Select **Raw events** to view each archived record separately.
Use Raw events when you need the exact event order, a specific event type, technical identifiers, or the original structured payload.
Records can include sync starts and finishes, provider health checks, write attempts and outcomes, unresolved changes, blackbox decisions, tombstones, and rating updates.
Switching views never changes the archive.
### Find the right record
#### Visibility
The visibility selector controls acknowledged records.
* **Open** shows records you have not acknowledged.
* **Acknowledged** shows reviewed records.
* **All** shows both.
Open does not mean currently failing. A completed thread remains open until you acknowledge it.
Acknowledging only organizes the Events archive. It never retries, resolves, or changes an item.
#### Search and filters
Search by title, item key, failure reason, reason code, or run information.
Search also checks related archived events. It runs shortly after you stop typing.
In Grouped view, use the outcome filter:
* **Successful** shows completed or resolved threads.
* **Problems** shows failed, unresolved, and blackboxed threads.
* **Informational** shows pending, running, and informational threads.
Select **More filters** to filter by date range, event type, provider, origin, feature, or pair.
Use **Problems** and **Last 24 hours** first when investigating a new failure.
#### Sorting and pagination
Sort by newest or oldest first.
The list shows 25 threads or events per page. Problem items within large runs load and paginate separately.
### Understand statuses
#### Completed
The sync reached its finish event without recorded errors.
#### Resolved
The latest relevant event indicates a successful write or cleared unresolved state.
#### Failed
A write or sync operation reported an error.
A run is failed when its final summary contains errors.
#### Unresolved
CrossWatch could not complete the operation. It recorded the item for a later attempt.
#### Blackboxed
CrossWatch blocked the item after repeated failures. This prevents the same failure cycle.
#### Running or pending
**Running** has a start event but no finish event.
**Pending** has a planned or attempted operation without a final result.
### Review a thread
Select a thread to open its details.
The summary shows the outcome, provider route, item key, and current thread state. Titles and episode details appear when the recorder captured them.
#### Timeline
The **Timeline** tab lists thread events in chronological order.
Each entry can show its time, name, type, description, and reason code.
Run threads list their problem items. Select an item to open its full item thread.
#### Details
The **Details** tab groups information into:
* **Event** — status, item, reason, counts, and timestamps.
* **Route** — feature, operation, providers, origin, pair, and sync mode.
* **Current context** — current CrossWatch state, marked **live now**.
#### Raw data
The **Raw data** tab contains the archived payload and available identifiers.
These can include thread, run, event, pair, and item IDs. You can copy raw data, the item key, or the run ID.
{% hint style="warning" %}
Raw data can contain provider names, identifiers, and diagnostics. Remove sensitive information before sharing it publicly.
{% endhint %}
### Current context
For item threads, Events compares the historical record with current local state.
It can show:
* **Pair state** — whether the matching pair still exists and is active.
* **Provider health** — the latest available health state.
* **Unresolved, blackbox, and tombstone state** — whether current local records remain.
* **Analyzer findings** — current baseline findings for the item.
Select **View in Analyzer** when you need a current provider comparison.
A pair can show as unmatched after it is removed, recreated, or changed.
### Related threads
Threads with the same item key appear under **Related threads**.
Use them to identify earlier attempts, later successes, repeated unresolved results, or blackbox promotion.
Select a related thread to open it directly.
### Refresh and clear
Select **Refresh** to reload the archive, providers, and configured pairs.
Refresh keeps the active search, filters, page, and view where possible. Use it after a sync completes.
Select **Clear** to delete every archived event, thread, run summary, and import-tracking record.
{% hint style="danger" %}
Clear cannot be undone. It does not remove provider data, pair configuration, unresolved state, blackbox state, or tombstones.
{% endhint %}
New syncs record into a new archive after clearing.
### Recommended workflow
{% stepper %}
{% step %}
### Run the affected pair
Reproduce the issue with a normal sync.
{% endstep %}
{% step %}
### Open Problems
Open Events, select **Grouped**, then select **Problems**.
Limit the date range to **Last 24 hours** when needed.
{% endstep %}
{% step %}
### Review the item
Open the latest run, then select the affected item.
Read the Timeline and recorded reason.
{% endstep %}
{% step %}
### Compare current state
Review **Current context**.
Open Analyzer if you need a provider baseline comparison.
{% endstep %}
{% step %}
### Correct and verify
Correct the configuration, matching, or provider problem.
Run the pair again and confirm a later completed or resolved event.
{% endstep %}
{% step %}
### Acknowledge the thread
Acknowledge the reviewed record when investigation is complete.
{% endstep %}
{% endstepper %}
### Events and other tools
#### Events and Analyzer
Events explains what happened during a sync. Analyzer compares what exists now.
Use Events for operation history, routes, outcomes, and recorded reasons. Use Analyzer for current provider baselines, missing items, and identifier gaps.
#### Events and View details
Use View details while observing a running or recent operation.
Use Events for persistent history, repeated attempts, and item investigation. Application logs may still be needed for exception traces not represented by structured events.
### Local storage and maintenance
Events stores its SQLite archive at:
`/.cw_databases/events.sqlite3`
A standard container installation usually uses:
`/config/.cw_databases/events.sqlite3`
Set `CROSSWATCH_EVENTS_DB` to override the archive location.
The archive remains local unless you store or back up the configuration directory elsewhere.
Use [Maintenance](/crosswatch/settings/maintenance.md) to check, optimize, or rebuild the archive.
* **Health check** verifies availability, integrity, schema, consistency, counts, timestamps, and storage size.
* **Optimize** checkpoints the write-ahead log and runs SQLite maintenance.
* **Rebuild** recreates the archive and can import supported local state records.
Rebuild does not restore every historical sync sequence. Use it only for a damaged archive or a health-check problem that Optimize cannot correct.
### Troubleshooting
#### A completed run appears in Open
The run is not acknowledged. Open means unacknowledged, not currently failing.
#### An unresolved event no longer matches current state
The event is historical. Check **Current context** to see whether the unresolved record still exists.
#### No events are visible
Run a sync, select **Refresh**, then select **All**.
Clear filters, widen the date range, and check archive health in Maintenance.
#### Provider health records are missing
Provider-health-only threads are hidden by default to reduce noise.
Select **All** or filter by provider or event type.
#### What to send with a support request
Copy the thread summary or raw data. Include the status, feature, route, item key, reason, run ID, and relevant timeline.
Remove credentials and other private information first.
### Limitations
* Events only shows structured information CrossWatch recorded.
* It does not replace application logs.
* Activity before Events existed can be incomplete.
* Rebuilding cannot guarantee every historical run.
* Current context can differ from the historical event.
* Acknowledgement never resolves, retries, or modifies an item.
### Related topics
* [Analyzer](/crosswatch/main-dashboard/tools/analyzer.md)
* [Maintenance](/crosswatch/settings/maintenance.md)
* [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* [Scheduling](/crosswatch/settings/scheduling.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/events.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.