> 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/logs.md). # Logs Inspect live and saved CrossWatch logs, filter diagnostics, export results, and manage retention. Inspect live CrossWatch activity, search previous runs, and keep diagnostic logs when you need them for troubleshooting. The **Logs** page combines live logging with a persistent log archive. Use it to: * follow a sync while it is running * open logs from previous sync runs * filter logs by sync pair, level, provider, or text * jump directly to errors and warnings * switch between readable messages and the original log output * copy or download a filtered or complete log * keep important logs beyond normal retention * inspect Watcher and Debug logging when your account has access Open the page from CrossWatch at `/#logs`. {% tabs %} {% tab title="End users" %} ### Quick start {% stepper %} {% step %} #### 1. Choose the log channel Select the type of activity you want to inspect: * **Sync**, synchronization activity and completed sync runs * **Watcher**, continuous Watcher activity, available to administrators * **Debug**, additional diagnostic output, available to administrators when debug logging is enabled For normal sync troubleshooting, start with **Sync**. {% endstep %} {% step %} #### 2. Choose Live or Saved logs Use **Live** to follow current activity. Use **Saved logs** to open previous logs stored by CrossWatch. Logs are saved automatically on the CrossWatch server. {% endstep %} {% step %} #### 3. Narrow the log For Sync logs you can select: * **All pairs** * one configured sync pair * **Latest run**, to open the newest saved run for the selected scope You can then filter the log by search text, level, or provider. {% endstep %} {% step %} #### 4. Inspect the relevant lines Use: * **Readable view** for formatted CrossWatch events * the error or warning counters to jump to those levels * the context action beside a line to show surrounding log entries * the previous and next match buttons to move through search results {% endstep %} {% step %} #### 5. Keep or export the log when needed Open **More** to copy or download either the filtered result or the complete log. Use **Keep this log** when a saved log must remain available beyond normal automatic cleanup. {% endstep %} {% endstepper %} ### Log channels #### Sync Sync is the main log channel for synchronization activity. A saved Sync log can contain one or more sync pairs from the same run. CrossWatch records the pair context with the log lines, which allows the page to show only the selected pair when required. Use the sync pair selector to choose: * **All pairs**, activity across the complete run * a specific pair, only log lines associated with that pair The pair list can also include retained logs for a pair that has since been removed from the active configuration. #### Watcher Watcher shows continuous Watcher logging. Watcher logs are stored separately from Sync logs and do not use the sync pair selector. Watcher is available to administrators. #### Debug Debug contains additional diagnostic logging that does not belong to the normal Sync or Watcher views. The Debug channel is only shown when: * you are using an administrator account * CrossWatch debug logging is enabled Use Debug when normal Sync or Watcher logging does not contain enough information to diagnose a problem. {% hint style="warning" %} Debug logging can produce significantly more output. Enable it only when needed for troubleshooting and disable it afterwards. {% endhint %} ### Live logs Select **Live** to follow current CrossWatch activity. When a log is active, CrossWatch refreshes the view automatically every two seconds. The status at the top of the page shows whether the page is: * receiving live updates * waiting for new activity * showing a saved log * temporarily disconnected and retrying When no new activity is running, the most recent log can remain visible while the page waits for new activity. #### Follow live **Follow live** keeps the view on the latest matching log lines. Follow mode is automatically disabled when you perform actions that require a stable position, such as: * changing a filter * moving to another page * jumping through search matches * scrolling away from the latest lines Click **Resume live** to return to the newest matching lines. ### Saved logs Select **Saved logs** to browse retained logs. Each saved Sync run shows: * sync pair or run name * enabled features * start time * duration * status * error count * warning count Possible statuses include: * Completed * Completed with issues * Failed * Error * Cancelled * Interrupted * Running * Live * Saved #### Feature indicators For Sync logs, the feature indicators show which synchronization features were enabled in the run: * Watchlist * Ratings * History * Progress * Playlists * Collections When a run contains multiple pairs, the indicators are combined across those pairs unless you selected one specific pair. If the required feature information was not recorded with an older log, CrossWatch shows the feature state as unavailable. #### Latest run Select a pair and click **Latest run** to open the newest retained run for that selection. This is useful when you know which pair failed but do not want to search the saved log list manually. ### Search and filters #### Search Search performs a case insensitive text search across the original stored log text. Use it for values such as: * movie or show titles * provider names * item IDs * API endpoints * error text * sync event names * pair or feature related messages Search is applied to the complete selected log, not only the currently visible page. Use the previous and next match buttons to move through matching lines. CrossWatch can continue to the previous or next log page when needed. #### Log level Filter by: * Errors * Warnings * Info * Debug The error and warning counters above an opened log can also be clicked. They apply the corresponding level filter immediately. #### Provider Use the Provider field to show log lines associated with a specific provider. Provider information is derived from the structured log context where available. You can combine provider, level, and text filters. ### Readable view **Readable view** formats supported CrossWatch log events into a more compact diagnostic presentation. Instead of showing only the raw structured message, CrossWatch can display descriptions such as: * Provider health checked * API request * API usage summary * Sync started * Syncing pair * Sync finished * Sync failed * Feature sync started * Feature sync finished * Two way sync started * Sync changes planned * Two way sync finished * Reading provider items * Reading progress * Provider items loaded * Sync overview * HTTP activity summary * Sync state saved Relevant values can be presented separately, including provider, source, target, feature, status, endpoint, latency, item counts, changes, unresolved items, blocked items, errors, and warnings. #### Original log Readable view does not replace or modify the stored log. Each formatted entry keeps an **Original log** section so you can inspect the exact underlying message. If your search only matches text inside the original message, CrossWatch opens the original log section for that result automatically. Your Readable view preference is retained in the browser. ### Show surrounding context Each normal log line has a context action. Use it when one error or warning does not explain what happened by itself. CrossWatch loads the nearby lines around that entry while keeping the current pair and run scope. This is especially useful for: * provider errors * item resolution failures * unexpected removals * API failures * warnings that depend on the operation immediately before them ### Pagination Large logs are loaded in pages rather than rendering the complete archive at once. The current interface shows: * up to 500 log lines per page * 10 saved logs per Saved logs page The footer shows the number of matching lines and the current page. Filters are applied before pagination, so the count represents the filtered result. ### Copy and download Open **More** for export actions. #### Copy filtered log Copies only lines matching the active: * search text * level filter * provider filter * pair or run scope #### Copy full log Copies the complete selected log within the active pair or run scope, ignoring text, level, and provider filters. #### Download filtered log Downloads the filtered result as a plain text `.log` file. #### Download full log Downloads the complete selected log as a plain text `.log` file. {% hint style="warning" %} CrossWatch applies log redaction before storing diagnostic lines, but exported logs can still contain operational information such as media titles, provider names, instance names, IDs, endpoints, or other environment details. Review a log before sharing it publicly. {% endhint %} ### Keep this log Saved logs normally follow CrossWatch retention and storage cleanup rules. Click **Keep this log** to pin a log. A pinned log is protected from: * normal age based cleanup * automatic deletion to free archive capacity * **Clear older logs** Click **Unpin log** when the log no longer needs to be retained. {% hint style="info" %} Pinning applies to the entire saved log. If a sync run contains multiple pairs, keeping the log also keeps the data for the other pairs in that run. {% endhint %} ### Delete a log A completed saved log can be deleted manually. Deleting a Sync log removes the complete saved log, including data for any other pairs stored in the same run. An active log cannot be deleted while it is still being written. #### Clear older logs From the Saved logs overview, administrators can use **Clear older logs** to delete completed, unpinned logs in the current channel that are visible to the current profile. Pinned logs are preserved. The action is not shown while the Sync page is restricted to one specific pair. ### Log retention and storage CrossWatch stores the diagnostic archive on the server. The current defaults are: * **7 days retention** * **100 MB maximum archive size** The Logs page shows current storage usage and the configured retention period. #### Automatic cleanup Completed logs that are not pinned are removed when they are older than the retention period. Storage capacity is also enforced independently from age based retention. If the archive needs more space, CrossWatch removes the oldest completed, unpinned logs until enough capacity is available. Pinned logs are not removed automatically. #### Storage limit reached If CrossWatch cannot make enough room because the remaining logs are active or pinned, new lines might not be saved. The affected log is marked as truncated and the Logs page shows a warning that some lines were not stored. Delete or unpin older logs to make space. ### Logs and Events Logs and Events serve different purposes. Use **Events** when you want a summarized view of sync runs, results, counts, and problems. Use **Logs** when you need the detailed execution trail behind a run or want to follow current activity. For most troubleshooting: 1. Find the affected run in Events. 2. Open or locate its log. 3. Filter to the affected pair or provider. 4. Check Errors and Warnings. 5. Use context around the relevant line. 6. Export the log if you need to share it for support. ### Troubleshooting #### I do not see any saved logs Logs are created as new activity is recorded. If the archive is new, run the relevant sync or wait for the activity you want to inspect. #### I cannot see Watcher or Debug Watcher is restricted to administrators. Debug is restricted to administrators and only appears when debug logging is enabled. A profile scoped view only exposes Sync logs that belong to provider instances available to that profile. #### Live logs stopped scrolling Follow mode is probably paused. Click **Resume live**. Changing filters, moving between pages, or scrolling away from the bottom intentionally disables automatic following. #### Search finds fewer lines than expected Check the active level, provider, pair, and run filters. All active filters are combined. #### A saved log says some lines were not saved The archive reached its storage limit and could not free enough space. Delete or unpin older logs, then reproduce the issue if you need a complete diagnostic trace. #### I need the exact unformatted message Leave Readable view enabled and expand **Original log**, or disable Readable view to show the original messages directly. {% endtab %} {% tab title="Power users" %} ### Persistent log archive The Logs page uses a persistent SQLite archive rather than only displaying the current browser session. The archive is stored in `logs.db` alongside the main CrossWatch local database location. CrossWatch records diagnostic lines after applying its log redaction function and removing terminal formatting. Individual stored log messages are bounded in size before they are written to the archive. ### Archive sessions CrossWatch stores logging in sessions. #### Sync sessions A sync run receives its own archive session. The session retains run metadata and the pair configuration associated with that run. Individual lines also carry pair and run context where available. This makes it possible to open a complete run and then restrict the view to one pair. #### Continuous channels Watcher and Debug are continuous channels. They use daily UTC archive sessions and roll over at UTC midnight. A restarted CrossWatch instance can continue using the current daily session. ### Log classification Stored lines are normalized into the levels used by the UI: * ERROR * WARN * INFO * DEBUG CrossWatch normalizes equivalent levels before storage. For example, Critical is treated as Error, Warning as Warn, and Success as Info. Provider context is extracted from log tags or supported structured log events when available. ### Structured logging and Readable view Readable view is presentation logic in the browser. The archive stores the underlying redacted log text plus metadata such as: * timestamp * level * provider * pair ID * run ID The browser recognizes supported structured CrossWatch events and converts them into readable summaries and value pills. The raw stored message remains available under **Original log**. This means turning Readable view on or off does not change the archive itself. ### Search behavior Text search is performed server side against the stored log message and is case insensitive. Level and provider filters use normalized stored metadata. Search, level, provider, pair, and run filters can be combined before results are paginated. The normal UI requests up to 500 lines at a time. ### Context lookup The context action performs a separate archive lookup around one line. The current implementation returns up to five preceding lines, the selected line, and up to five following lines while respecting the current pair and run scope. ### Export behavior Log export is streamed from the archive in bounded chunks rather than loading the complete archive into memory first. Filtered export applies the current text, level, provider, pair, and run scope. Full export removes the text, level, and provider filters but still respects the selected pair or run scope. ### Retention behavior The archive currently uses a seven day default retention period and a 100 MB capacity limit. Cleanup only removes completed sessions that are not pinned. Two cleanup mechanisms apply: 1. age based cleanup removes completed, unpinned sessions older than the retention cutoff 2. capacity cleanup removes the oldest completed, unpinned sessions when additional space is required If capacity still cannot be created, the active session is marked as truncated and subsequent lines that do not fit are not stored. ### Access control Log visibility follows CrossWatch user and profile access. #### Administrator An administrator without profile impersonation can access: * Sync * Watcher * Debug, when debug logging is enabled #### Normal user or profile scoped view A non administrator or profile scoped view can access Sync logs only. A Sync session is visible only when the account or selected profile is allowed to access all provider instances referenced by that pair. This also applies to direct log, context, pin, delete, and download operations through the Logs API. ### Logs API The current archive API is exposed below: `/api/logs/archive` The UI uses it to: * list retained sessions * retrieve filtered log lines * retrieve context around a line * pin or unpin a session * delete a completed session * clear completed, unpinned sessions * stream log exports Archive access is validated by the backend. Hiding a channel or pair in the browser is not the security boundary. ### Route state The Logs page keeps its current scope in the hash route. Supported route state includes: * channel * pair ID * run ID * latest run request * return location This allows other CrossWatch pages to open Logs directly in the relevant diagnostic context. {% endtab %} {% endtabs %} ### Related topics * [Events](/crosswatch/main-dashboard/tools/events.md) * [Maintenance](/crosswatch/settings/maintenance.md) * [Main dashboard](/crosswatch/main-dashboard.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/logs.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.