> For the complete documentation index, see [llms.txt](https://help.tillit.cloud/tillit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tillit.cloud/tillit/tools/ignition-module/troubleshooting/logs-and-diagnostics.md).

# Logs and diagnostics

## Logs and Diagnostics

The TilliT Ignition Module writes its log entries through the standard Ignition logging system. Every TilliT logger name begins with `TilliT.` so you can filter the gateway log to just the module's output.

### Viewing logs in the Gateway

In the Ignition Gateway, navigate to **Status → Diagnostics → Logs**.

<figure><img src="/files/muiq69D3TmlcMCUQZo4v" alt=""><figcaption><p>The Gateway Logs page with the Logger filter set to TilliT, showing only entries emitted by the TilliT module.</p></figcaption></figure>

* Use the **Logger** filter and type `TilliT` to show only the module's entries.
* The log includes a level column - `INFO`, `WARN`, `ERROR` and (when enabled) `DEBUG` and `TRACE`.
* Use the date/time controls to narrow to the period when the issue occurred.

The gateway log file itself is stored under the Ignition install directory at `logs/wrapper.log` and is rolled over automatically. Older log archives can be downloaded from the same Logs page.

### Useful TilliT loggers

The module is split into focused components, each with its own logger. When investigating a specific symptom, raising the level on just the relevant logger keeps the noise down.

| Logger                                       | What it logs                                                        |
| -------------------------------------------- | ------------------------------------------------------------------- |
| `TilliT`                                     | Module lifecycle - startup, shutdown, configuration loading         |
| `TilliT.TilliTTagProvider`                   | Tag provider creation and updates to the **System Status** tags     |
| `TilliT.PubSubHandlerImpl`                   | MQTT connect/disconnect, subscriptions, low-level connection errors |
| `TilliT.PubSubHandlerWorker`                 | Worker thread that processes incoming MQTT messages                 |
| `TilliT.MqttMessageRouter`                   | Routing of incoming MQTT messages to the correct handler            |
| `TilliT.OrderMessageHandler`                 | Order lifecycle messages (start / suspend / complete)               |
| `TilliT.OrderStatsMessageHandler`            | OEE and progress updates from TilliT                                |
| `TilliT.EventMessageHandler`                 | Subscribed events arriving from TilliT                              |
| `TilliT.ControlParamMessageHandler`          | Control parameter updates pushed from TilliT                        |
| `TilliT.AssetTagOrchestrator`                | Asset hierarchy build and refresh                                   |
| `TilliT.TagStructureBuilder`                 | Detailed tag-tree construction logs                                 |
| `TilliT.BatchTagReader`                      | Bulk tag reads against the Ignition tag system                      |
| `TilliT.ApiCall`                             | Outbound REST calls to TilliT - URLs, status codes, error bodies    |
| `TilliT.CountTagWriteHandler`                | Production count tag writes                                         |
| `TilliT.ActiveTagWriteHandler`               | `Active` tag writes per asset                                       |
| `TilliT.AssetStatusTagWriteHandler`          | Asset status tag writes                                             |
| `TilliT.EventTriggerTagWriteHandler`         | Event trigger tag writes                                            |
| `TilliT.TagWriteHandlerRegistry`             | Registration of write handlers when an asset is added or refreshed  |
| `TilliT.ControlParameterTagStructureService` | Tag structure for control parameters                                |

### Raising the log level

By default each logger sits at `INFO`. To capture more detail for an investigation:

1. Open **Status → Diagnostics → Logs** in the Gateway.
2. Click **Settings** (the cog icon at the top right of the log view).
3. Find the relevant logger from the table above. If it is not in the list yet, type its name into the **Add Logger** field.
4. Set the level to `DEBUG` (or `TRACE` for very detailed diagnostics).
5. Reproduce the issue.
6. **Important**: lower the level back to `INFO` once you are done. `DEBUG` and `TRACE` produce a high volume of output and will fill the log files quickly on a busy gateway.

{% hint style="warning" %}
Do not leave loggers at `DEBUG` or `TRACE` in production for extended periods. The `TilliT.BatchTagReader` and `TilliT.PubSubHandlerWorker` loggers in particular emit a large amount of output at debug levels.
{% endhint %}

### Targeted log levels by symptom

| Symptom                           | Loggers to set to `DEBUG`                                       |
| --------------------------------- | --------------------------------------------------------------- |
| Module won't start                | `TilliT`, `TilliT.TilliTTagProvider`                            |
| MQTT will not connect             | `TilliT.PubSubHandlerImpl`, `TilliT.PubSubHandlerWorker`        |
| REST calls fail                   | `TilliT.ApiCall`                                                |
| Asset hierarchy is wrong or empty | `TilliT.AssetTagOrchestrator`, `TilliT.TagStructureBuilder`     |
| Counts not flowing                | `TilliT.CountTagWriteHandler`, `TilliT.ActiveTagWriteHandler`   |
| Events not firing from Ignition   | `TilliT.EventTriggerTagWriteHandler`                            |
| Events not arriving from TilliT   | `TilliT.EventMessageHandler`, `TilliT.MqttMessageRouter`        |
| Order data missing                | `TilliT.OrderMessageHandler`, `TilliT.OrderStatsMessageHandler` |

### Useful System Status tag values

The **System Status** folder of the TilliT tag provider holds a live view of module health. These tags are also a quick alternative to digging through logs:

* `Connected` and `Connection status` - MQTT connection state
* `Module ready` and `Module status` - module lifecycle state
* `Error code` - the last error code published by the module (`0` is healthy)
* `Messages received`, `Last topic`, `Last message` - confirm MQTT traffic is flowing

See [Verifying the installation](/tillit/tools/ignition-module/troubleshooting/verifying-the-installation.md) for the healthy values of each.

### Information to capture for a support ticket

When raising an issue with TilliT support, please include:

1. **Module version** from the **TilliT → Settings** page in the Gateway. (This is the same value the module sends in the `Tillit-Client-Version` HTTP header.)
2. **Ignition version** and edition (Standard / Edge / Maker).
3. **System Status tag values** at the time of the issue:
   * `Module ready`
   * `Module status`
   * `Connected`
   * `Connection status`
   * `Error code`
   * `Messages received`
4. **TilliT environment** (production / stage / development), tenant and region.
5. **Tenant Edge / Thing ID** the gateway is configured against.
6. **Approximate time** the issue first occurred (with timezone).
7. **Gateway log excerpt** filtered to logger `TilliT` covering the period of the issue. If you have already raised relevant loggers to `DEBUG` based on the table above, include those entries too.
8. **Screenshots** of the **TilliT → Settings** page (mask the password) and of the affected tag(s) in the Designer.

Providing this up front allows TilliT support to triage without a back-and-forth round trip.