Logs and commands
A box's logcat as a zip, live, a root shell, or a picture of its screen — from the device page.
Four items in a device page's ⋯ menu, all needing the box online: Logcat (.zip), Live logs, Execute and Screenshot.
Logcat (.zip)
A snapshot, collected on demand and downloaded through the browser.
| Entry | What it is |
|---|---|
logcat.txt | logcat -d -v time, last 50 000 lines |
agent.log | The agent's own log, from /data/adb/magnemite/ |
agent.log.1 | The rotated one, when the box has been up long enough |
device.txt | Serial, model, Android, ABI, LAN address, uptime, disk, memory, load, installed packages |
could not upload the bundle: HTTP 404
The box built the zip and had nowhere to put it: the edge is not routing POST /api/logs/* to the
hub, so it is running an image built before that route existed. Rebuild the edge, see deploying
without dropping the fleet.
Collected automatically after an outage
Both tools above need the box online, which is exactly what it was not
while the thing you are investigating happened. The box's own agent.log
survives the gap on its disk, so the fix is to fetch it on the way back rather
than to ask for it afterwards.
Turn on Collect logs on recovery in Settings → Tuning. When a box returns from an outage long enough to have flipped it offline, the hub collects a bundle by itself and files it against that episode — it then hangs off the row in Connectivity, see where a box went.
It ships off. It runs a collection on a box in somebody's living room and costs that box's uplink, so it is something to turn on deliberately. Once on, three limits keep it sane: nothing is collected for a gap shorter than the offline timeout, at most one capture per box an hour, and a fleet-wide ceiling per hour so that an outage at the hub end does not bring fifty simultaneous uploads back with the fleet.
Automatic captures are kept separately from the ones you ask for, so a box that flapped three times cannot evict the bundle you were waiting on.
Live logs
A log as it is written, streamed while the panel is open. The source picker
offers logcat, the agent's log, the scanner's, plus whatever .log files the
box turns out to have; Another file… takes any absolute path. Both start
from the last 200 lines rather than replaying everything, and lines are
coloured by level.
What it costs:
- One follow per source on the box: everyone watching logcat shares one.
- Closing the panel stops it, so does the box disconnecting, and so does a five-minute deadline the agent renews while anyone is watching, a browser that vanished cannot leave a follow running on someone's box.
- The panel keeps 2000 lines and stores nothing. For something to keep, use the zip.
- Lines batch roughly once a second; a box logging faster than the socket drains has lines dropped, and the panel says how many.
Execute
A shell command run as root on that box, the same sh -c the install hooks
use, invoked by hand. The dialog keeps the ones people were opening adb for:
am force-stop com.nianticlabs.pokemongo
am force-stop com.pokemod.aegis
monkey -p com.pokemod.aegis -c android.intent.category.LAUNCHER 1; sleep 3; am start-foreground-service com.pokemod.aegis/com.pokemod.aegis.services.MappingServiceWhy the third one is three commands
Each part is there because the shorter version was tried on a box and did not work. monkey takes
the app out of the stopped state the force-stop above left it in — Android delivers no intent to
a stopped package, so the obvious "stop it, then start the mapping" pair could never have worked.
start-foreground-service rather than startservice, because a plain service start from the
background is refused on Android 8 and later with app is in background uid null. And the
foreground variant on its own is the worst of the three: it exits 0 and starts nothing.
A box that has never run Aegis needs it started by hand once before any of this works.
Anything else can be typed; Ctrl/Cmd+Enter runs it. Output is stdout and
stderr together, capped at 64 KB with the tail kept, because the end is the
part that says what happened.
60 seconds and the box gives up (a command that needs longer belongs in a script on the box).
This is a root shell on hardware,rm -rf does exactly what you would expect.
Screenshot
One screencap, taken when you ask. It answers the question no reading can: a
box can be online, heartbeating, with the scanner's process alive, and sitting
on a dialog nobody has read. APP_NOT_FOREGROUND says the launcher owns the
screen; this says what is on it — the login that expired, the crash dialog,
the Play Store page, the black screen.
Opening the dialog takes the capture, and Capture again takes another.
- Nothing is captured on a schedule, and nothing is captured on an alert. These are boxes in somebody's living room. One capture, because a person pressed a button, with their name on the audit row.
- The PNG goes up over HTTP with the box's own device token, the same road a log bundle takes and for the same reason: a socket frame is capped at 1 MB and a 1080p capture is regularly more.
- The last five per box are kept, for a day. Tighter than the log bundles' week, deliberately: a log is evidence about something that happened, and a picture of somebody's television is not worth keeping once it has answered the question.
- The menu item is absent, not greyed, on a box whose agent predates the feature — the fix is an agent update, which is not on that menu.
screencap wrote an empty file
The box has no display to capture. On hardware that is a ROM without screencap or a display
service that is not up; in a Redroid container it is an image with no
virtual display. The agent checks the PNG's first eight bytes before it uploads anything, so this
arrives as that sentence rather than as a broken image in the dialog.
could not upload the screenshot: HTTP 404
Same cause as the bundle's 404 above, on a different path: the edge is not routing POST /api/screenshots/* to the hub, so the capture had nowhere to go. It is the newer of the two
routes, so an edge built before screenshots existed forwards logs and refuses pictures. Rebuild
the edge, see deploying without dropping the
fleet.
What to look for in logs?
| Symptom | Where |
|---|---|
| An install that failed | agent.log (the pm install-create/write/commit session and its exact error) |
| A self-update that did not happen | agent.log, lines starting self-update: . . . |
| The scanner crashing/no response | logcat.txt or agent log |
| A box that will not connect | agent.log, TLS and dial errors, plus the reconnect backoff |