Collecting a Reader Debug Bundle
Part of: Devices — gathering a reader's logs and Tagnet's own records of it into one file for support.
A debug bundle is a single zip file that collects the evidence needed to diagnose a misbehaving reader: the reader's own log archives, Tagnet's recent deployment logs for that reader, and a snapshot of the reader's record and live state. You collect it from Tagnet in one step instead of logging in to the reader's console and pulling logs by hand.
When to Use It
Collect a bundle when a reader behaves strangely and you want Stratum Global support to look at it. A typical case: the reader's heartbeats report an error count, but its own web console is unreachable, so you cannot read its logs yourself. The bundle also helps when a deploy keeps failing, a reader reboots on its own, or tag reads stop without an obvious cause.
Attach the downloaded zip to your support request.
Who Can Run It, and on Which Readers
Only administrators can collect a bundle, because the reader's log archives leave the reader and Tagnet.
The Collect debug bundle button appears on the reader's Reader control tab, with the other reader operations, when the reader is:
- Active. Deactivated readers do not offer it.
- Locally managed. Cloud-managed readers do not offer it, because Tagnet cannot reach them.
- A supported model: Zebra FX7500, FX9600, FXR90, ATR7000, or Impinj R700.
Collecting a Bundle
- Open the reader's detail page and go to the Reader control tab.
- Select Collect debug bundle in the Reader group of operations.
- Read the confirmation dialog and select Collect. Progress shows below, one step at a time.
- When the steps finish, a Debug bundle section appears under the progress display with a Download bundle button.
The collection runs like a deploy or reboot. It continues if you navigate away, and reopening Reader control picks up its progress. Only one operation runs on a reader at a time, so a collection is refused while a deploy, reboot, or another collection is in progress on the same reader.
The steps are:
| Step | What it does |
|---|---|
| Authentication | Zebra readers only. Logs in to the reader's IoT Connector for a bearer token. |
| Reader Logs | Downloads the reader's own log archives. |
| Deployment Logs | Exports Tagnet's deployment logs for this reader from the last 7 days. |
| Reader State | Captures the reader's device record and current state. |
| Write Bundle | Builds the zip and makes it available to download. |
Note: Collecting a bundle changes nothing on the reader. Tagnet sends read-only requests, never deletes or clears the reader's logs, and never changes its log levels.
What Is in the Bundle
| Path | Contents |
|---|---|
manifest.json | Reader name, id, vendor, model, model number, serial, and firmware. Also the Tagnet version, when it was collected (UTC), who collected it, a note, and one entry per item with its status. |
reader/ | The reader's own log archives, included as-is and not unpacked, each in a folder named for the item (for example reader/syslog/), with the file name the reader gave it. See below for each vendor. |
tagnet/deployments/ | One JSON file per deployment log for this reader from the last 7 days, with credentials removed. |
tagnet/state.json | The reader's device record (without credentials) and its current state: CPU, RAM, temperature, uptime, antennas, radio status, error and warning counts, and the rest of the heartbeat data. |
Reader Items by Vendor
| Vendor | Items in reader/ |
|---|---|
| Zebra FX7500, FX9600, FXR90, ATR7000 | syslog, RcLog, RgWarningLog, RgErrorLog, and radioPacketLog (each a .tar.gz), plus log-levels.json, the reader's current log levels. |
| Impinj R700 | debug-bundle (a .zip the reader generates when asked) and watchdog-bundle, which exists only after the reader has rebooted because of its watchdog. |
Reading the Manifest
Which items a reader offers varies by model and firmware, so Tagnet tries every item and records the answer in manifest.json. Each item has one of these statuses:
| Status | Meaning |
|---|---|
collected | The item is in the bundle. The entry gives the file name and size. |
none | The reader answered that it has nothing stored. For example, an R700 that has never had a watchdog reboot has no watchdog-bundle, and a Zebra reader with radio packet logging off has no radioPacketLog. |
not-supported | The reader answered that it does not offer this item (HTTP 404 or 405). Its firmware is usually older than the feature. |
failed | Anything else: an error, a timeout, or an unreachable reader. The entry includes the status code and message. |
One failing item never fails the whole bundle. If the reader login fails, for example, every reader/ item is listed as failed with the reason, and the Tagnet-side items are still included.
What Is Removed
In the deployment logs, every request and response is scrubbed: passwords, usernames, session ids, and tokens are replaced with [REDACTED] or [JWT-REDACTED], and the session id and JWT fields are left out entirely. There is no option to include the raw logs.
The reader's own log archives are different. They are included unmodified and may contain host names, IP addresses, or reader settings.
Downloading the Bundle
After collection finishes, select Download bundle. The file is named tagnet-debug-<reader name>-<yyyyMMdd-HHmmss>.zip.
Below the button, Tagnet shows this note:
Tagnet's own logs in this bundle have credentials removed. The reader's log archives are included unmodified and may contain host names, IP addresses, or reader settings. Look the bundle over before sending it.
Open the zip and review it before you send it, especially the reader/ archives.
A bundle can be downloaded once. It is deleted from the server:
- as soon as you download it,
- after one hour if nobody downloads it, and
- whenever Tagnet restarts.
Bundles are held temporarily on the server and are never stored in the database. If you need another copy, or the hour has passed, collect again.
Audit Trail
Each collection records a ReaderDebugBundleCollected security event. The actor is the administrator who ran it, and the details list the reader and the status of each item. Neither the security event nor Tagnet's own log ever contains the bundle's contents.
Troubleshooting
The button is not on the Reader control tab: confirm you are signed in as an administrator, and that the reader is active, locally managed, has a reader login stored, and is one of the supported models listed above.
Every reader/ item is failed with a login error: Tagnet could not log in to the reader, so it could not fetch any logs. Check that the reader's stored credential is still valid, and for a Zebra reader confirm its IoT Connector is running. The Tagnet-side items are still in the bundle, and the reader's heartbeat state may be enough for support to start with.
Items are failed as unreachable or timed out: Tagnet could not reach the reader over the network. This is common when the reader is in the state you are trying to diagnose. Check power and network, then collect again once the reader is reachable. The partial bundle is still worth sending.
The collection is refused because another operation is running: a deploy, reboot, or earlier collection is still running on this reader. Open Reader control to watch it, and collect again after it finishes.
Items are not-supported: the reader's firmware does not offer that log. This is expected on older firmware and does not mean anything is wrong. Newer firmware may offer more of them.
Zebra items are failed with HTTP 500 and "returned NULL without setting an error": the reader's own log collector could not answer. On firmware 3.30 this happens while the reader's IoT Connector is restarting or not running, and the reader stops sending heartbeats at the same time, so check the reader's last check-in on its Overview tab. Tagnet already retries, after 2 and then 20 seconds. If the reader is checking in again, collect once more; if it is not, the reader needs attention first. The logs that did come back are in the bundle.
Items are failed with "Not attempted: the reader stopped answering": two requests in a row timed out, which means the reader's connector is accepting connections but not answering them. Tagnet stops asking for the remaining logs rather than waiting several minutes on each. Treat it like the entry above: get the reader checking in again, then collect once more.
The Download bundle button is gone, or the download fails: the bundle was already downloaded, an hour passed, or Tagnet restarted. Collect again.
Related Guides
- Devices: the reader detail page and Reader control.
- Deploying Reader Configuration: the deploy operation whose logs are included in the bundle.