Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

feat(diagnostics): save the bundle as a zip with the whole log files

Marc Diaz94423eb806cf
diff --git a/electron/diagnostics/main-log-file.test.ts b/electron/diagnostics/main-log-file.test.ts
index b714863c4..1ffe326c7 100644
--- a/electron/diagnostics/main-log-file.test.ts
+++ b/electron/diagnostics/main-log-file.test.ts
@@ -150,6 +150,29 @@ describe("MainLogFile", () => {
expect(lines()).toHaveLength(1);
});
+ it("readFiles returns both files whole, oldest first", () => {
+ silenceConsole();
+ const log = make();
+ fs.writeFileSync(path.join(dir, "main.old.log"), "old\n");
+ log.install(dir, "launch");
+ console.info("new");
+
+ const files = log.readFiles();
+ expect(files.map((f) => f.name)).toEqual(["main.old.log", "main.log"]);
+ expect(files[0].data.toString()).toBe("old\n");
+ expect(files[1].data.toString()).toMatch(/--- launch ---\n.* info new\n$/);
+ expect(log.lastError).toBeNull();
+ });
+
+ it("readFiles leaves out a missing file without an error", () => {
+ silenceConsole();
+ const log = make();
+ log.install(dir, "launch");
+
+ expect(log.readFiles().map((f) => f.name)).toEqual(["main.log"]);
+ expect(log.lastError).toBeNull();
+ });
+
it("reports a failed read and keeps writing", () => {
silenceConsole();
const log = make();
diff --git a/electron/diagnostics/main-log-file.ts b/electron/diagnostics/main-log-file.ts
index 926f02f3c..d366ba27c 100644
--- a/electron/diagnostics/main-log-file.ts
+++ b/electron/diagnostics/main-log-file.ts
@@ -130,6 +130,23 @@ export class MainLogFile {
return whole ? text : text.slice(text.indexOf("\n") + 1);
}
+ /** `main.old.log` and `main.log` whole, for the zipped bundle; a missing one is left out. */
+ readFiles(): { name: string; data: Buffer }[] {
+ if (!this.dir) return [];
+ this.flush();
+ const files: { name: string; data: Buffer }[] = [];
+ for (const name of [OLD_LOG_FILE, LOG_FILE]) {
+ try {
+ files.push({ name, data: fs.readFileSync(path.join(this.dir, name)) });
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+ this.error = describeError(error);
+ }
+ }
+ }
+ return files;
+ }
+
private record(level: Level, rawText: string): void {
if (this.fd === null) return;
const now = Date.now();
diff --git a/electron/diagnostics/zip.test.ts b/electron/diagnostics/zip.test.ts
new file mode 100644
index 000000000..65ca6324e
--- /dev/null
+++ b/electron/diagnostics/zip.test.ts
@@ -0,0 +1,72 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { describe, expect, it } from "vitest";
+import { createZip } from "./zip";
+
+/** Reads the archive back through its central directory, the way an unzip tool does. */
+function readZip(zip: Buffer) {
+ const end = zip.length - 22;
+ expect(zip.readUInt32LE(end)).toBe(0x06054b50);
+ const count = zip.readUInt16LE(end + 10);
+ let at = zip.readUInt32LE(end + 16);
+ const files: Record<string, string> = {};
+ for (let i = 0; i < count; i++) {
+ expect(zip.readUInt32LE(at)).toBe(0x02014b50);
+ const crc = zip.readUInt32LE(at + 16);
+ const size = zip.readUInt32LE(at + 20);
+ const nameLength = zip.readUInt16LE(at + 28);
+ const local = zip.readUInt32LE(at + 42);
+ const name = zip.toString("utf-8", at + 46, at + 46 + nameLength);
+ expect(zip.readUInt32LE(local)).toBe(0x04034b50);
+ const start = local + 30 + zip.readUInt16LE(local + 26);
+ const data = zlib.inflateRawSync(zip.subarray(start, start + size));
+ expect(zlib.crc32(data)).toBe(crc);
+ files[name] = data.toString("utf-8");
+ at += 46 + nameLength;
+ }
+ return files;
+}
+
+describe("createZip", () => {
+ it("round-trips every entry", () => {
+ const big = "line\n".repeat(100_000);
+ const zip = createZip([
+ { name: "diagnostic.json", data: Buffer.from('{"a":1}') },
+ { name: "main.log", data: Buffer.from(big) },
+ { name: "empty.log", data: Buffer.alloc(0) },
+ { name: "é.txt", data: Buffer.from("ü") },
+ ]);
+
+ expect(readZip(zip)).toEqual({
+ "diagnostic.json": '{"a":1}',
+ "main.log": big,
+ "empty.log": "",
+ "é.txt": "ü",
+ });
+ expect(zip.length).toBeLessThan(big.length / 10);
+ });
+
+ it("opens with the system unzip, where there is one", () => {
+ let unzip = true;
+ try {
+ execFileSync("unzip", ["-v"], { stdio: "ignore" });
+ } catch {
+ unzip = false;
+ }
+ if (!unzip) return;
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "openscreen-zip-"));
+ try {
+ const file = path.join(dir, "bundle.zip");
+ fs.writeFileSync(file, createZip([{ name: "main.log", data: Buffer.from("hello\n") }]));
+ execFileSync("unzip", ["-tq", file], { stdio: "ignore" });
+ expect(execFileSync("unzip", ["-p", file, "main.log"], { encoding: "utf-8" })).toBe(
+ "hello\n",
+ );
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/electron/diagnostics/zip.ts b/electron/diagnostics/zip.ts
new file mode 100644
index 000000000..b1ab4ac07
--- /dev/null
+++ b/electron/diagnostics/zip.ts
@@ -0,0 +1,63 @@
+import zlib from "node:zlib";
+
+export interface ZipEntry {
+ name: string;
+ data: Buffer;
+}
+
+/**
+ * A deflated `.zip` of `entries`, for the diagnostic bundle. Only what that needs: no
+ * folders, no ZIP64 (every entry and the whole archive stay under 4 GiB), UTF-8 names.
+ */
+export function createZip(entries: ZipEntry[], date = new Date()): Buffer {
+ const time = (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1);
+ const day = ((date.getFullYear() - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+ const locals: Buffer[] = [];
+ const centrals: Buffer[] = [];
+ let offset = 0;
+
+ for (const entry of entries) {
+ const name = Buffer.from(entry.name, "utf-8");
+ const compressed = zlib.deflateRawSync(entry.data);
+ const crc = zlib.crc32(entry.data);
+
+ const local = Buffer.alloc(30);
+ local.writeUInt32LE(0x04034b50, 0);
+ local.writeUInt16LE(20, 4); // version needed: deflate
+ local.writeUInt16LE(0x0800, 6); // UTF-8 name
+ local.writeUInt16LE(8, 8); // deflate
+ local.writeUInt16LE(time, 10);
+ local.writeUInt16LE(day, 12);
+ local.writeUInt32LE(crc, 14);
+ local.writeUInt32LE(compressed.length, 18);
+ local.writeUInt32LE(entry.data.length, 22);
+ local.writeUInt16LE(name.length, 26);
+ locals.push(local, name, compressed);
+
+ const central = Buffer.alloc(46);
+ central.writeUInt32LE(0x02014b50, 0);
+ central.writeUInt16LE(20, 4); // version made by
+ central.writeUInt16LE(20, 6);
+ central.writeUInt16LE(0x0800, 8);
+ central.writeUInt16LE(8, 10);
+ central.writeUInt16LE(time, 12);
+ central.writeUInt16LE(day, 14);
+ central.writeUInt32LE(crc, 16);
+ central.writeUInt32LE(compressed.length, 20);
+ central.writeUInt32LE(entry.data.length, 24);
+ central.writeUInt16LE(name.length, 28);
+ central.writeUInt32LE(offset, 42);
+ centrals.push(central, name);
+
+ offset += local.length + name.length + compressed.length;
+ }
+
+ const directory = Buffer.concat(centrals);
+ const end = Buffer.alloc(22);
+ end.writeUInt32LE(0x06054b50, 0);
+ end.writeUInt16LE(entries.length, 8);
+ end.writeUInt16LE(entries.length, 10);
+ end.writeUInt32LE(directory.length, 12);
+ end.writeUInt32LE(offset, 16);
+ return Buffer.concat([...locals, directory, end]);
+}
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index e39760b40..7eae3fcaa 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -72,6 +72,7 @@ import { AppSettingsStore } from "../app-settings";
import { createRunnerHost } from "../cli/runnerHost";
import { hideCountdownOverlay } from "../countdownOverlay";
import { isDiagnosticModeEnabled, mainLogFile } from "../diagnostics/main-log-file";
+import { createZip } from "../diagnostics/zip";
import { mainT } from "../i18n";
import { getInstallChannel } from "../install-channel";
import {
@@ -1914,10 +1915,11 @@ async function resolveMediaLinksForVideo(videoPath: string): Promise<{
}
/**
- * Writes the diagnostic bundle a bug report needs: app/OS facts, the native
- * helpers' raw stdout/stderr (which is where `[stop-timing]` and
- * `encoder-selection` land — see nativeWindowsCaptureStop.ts), and the tail of the
- * main process's log file, which reaches back into the previous launch. Shared by the renderer's IPC call and
+ * Writes the diagnostic bundle a bug report needs, as a `.zip`: `diagnostic.json` with
+ * app/OS facts, the native helpers' raw stdout/stderr (which is where `[stop-timing]` and
+ * `encoder-selection` land — see nativeWindowsCaptureStop.ts) and the tail of the main
+ * process's log, next to that log's files whole (`main.log`, and `main.old.log` once it
+ * has rotated), which reach back into earlier launches. Shared by the renderer's IPC call and
* the menu/tray "Save Diagnostics" entry point in main.ts, which has no
* renderer-side `projectState`/`logs` to offer and does not need to.
*/
@@ -1929,8 +1931,8 @@ export async function exportDiagnosticFile(payload: {
}) {
const { filePath, canceled } = await dialog.showSaveDialog({
title: "Save Diagnostic File",
- defaultPath: `openscreen-diagnostic-${Date.now()}.json`,
- filters: [{ name: "JSON", extensions: ["json"] }],
+ defaultPath: `openscreen-diagnostic-${Date.now()}.zip`,
+ filters: [{ name: "ZIP", extensions: ["zip"] }],
});
if (canceled || !filePath) return { success: false, canceled: true };
@@ -1938,6 +1940,8 @@ export async function exportDiagnosticFile(payload: {
const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
const MAIN_PROCESS_LOGS_MAX_BYTES = 256 * 1024;
const tail = (s: string, max: number) => (s.length <= max ? s : s.slice(s.length - max));
+ // Read before `logFileError` below, so a failed read is reported in the same bundle.
+ const logFiles = mainLogFile.readFiles();
const diagnostic = {
timestamp: new Date().toISOString(),
@@ -1969,7 +1973,8 @@ export async function exportDiagnosticFile(payload: {
};
try {
- await fs.writeFile(filePath, JSON.stringify(diagnostic, null, 2), "utf-8");
+ const json = Buffer.from(JSON.stringify(diagnostic, null, 2), "utf-8");
+ await fs.writeFile(filePath, createZip([{ name: "diagnostic.json", data: json }, ...logFiles]));
return { success: true, path: filePath };
} catch (error) {
console.error("Failed to write diagnostic file:", error);
diff --git a/technical-documentation/testing/manual-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md
index 0e87378c0..729750983 100644
--- a/technical-documentation/testing/manual-e2e-checklist.md
+++ b/technical-documentation/testing/manual-e2e-checklist.md
@@ -97,7 +97,7 @@ gh run download <run-id> -R getopenscreen/openscreen -n openscreen-windows-x64
- AppImage: `chmod +x Openscreen-Linux-<version>.AppImage`, then run it; add `--no-sandbox` if Chromium's sandbox cannot start. A package: install it with the distribution's tool (`sudo apt install ./Openscreen-Linux-<version>.deb`, `sudo dnf install ./Openscreen-Linux-<version>.rpm`, `sudo pacman -U Openscreen-Linux-<version>.pacman`), then run `openscreen`.
- No flag is needed. Which name to grant is **to confirm on the first run**: a package installs a desktop entry, an AppImage has none until it is integrated.
-**Logs of a packaged build.** The main process logs to its standard output, so a launch from a terminal shows it there, `[content-protection] OFF for the HUD window` included; whether the Windows executable prints into the PowerShell that started it is **to confirm on the first run**. However it was launched, the same lines are appended to `main.log` in `~/Library/Logs/Openscreen`, `%APPDATA%\Openscreen\logs` or `~/.config/openscreen/logs`, one `--- launch <version> pid <pid> ---` header per launch. Past 5 MiB it becomes `main.old.log` and starts over, so the folder never holds more than two files. Tray → *Save Diagnostics* writes the last 256 KiB of them to a JSON file of your choice (`mainProcessLogs`, with `logFile` and, if the file could not be written, `logFileError`), with the capture helper's recent output (`helperOutput.windows`, `.mac` or `.linux`). It leaves the open project out; a project file is in `userData/projects`. The renderer's `console` calls are stripped from packaged builds. Recordings and their `.cursor.json` and `.session.json` sidecars are in the `recordings` folder of `%APPDATA%\Openscreen`, `~/Library/Application Support/Openscreen` or `~/.config/openscreen`.
+**Logs of a packaged build.** The main process logs to its standard output, so a launch from a terminal shows it there, `[content-protection] OFF for the HUD window` included; whether the Windows executable prints into the PowerShell that started it is **to confirm on the first run**. However it was launched, the same lines are appended to `main.log` in `~/Library/Logs/Openscreen`, `%APPDATA%\Openscreen\logs` or `~/.config/openscreen/logs`, one `--- launch <version> pid <pid> ---` header per launch. Past 5 MiB it becomes `main.old.log` and starts over, so the folder never holds more than two files. Tray → *Save Diagnostics* writes a `.zip` of your choice: both log files whole, and `diagnostic.json` with the last 256 KiB of them (`mainProcessLogs`, with `logFile` and, if the file could not be written or read, `logFileError`) and the capture helper's recent output (`helperOutput.windows`, `.mac` or `.linux`). It leaves the open project out; a project file is in `userData/projects`. The renderer's `console` calls are stripped from packaged builds. Recordings and their `.cursor.json` and `.session.json` sidecars are in the `recordings` folder of `%APPDATA%\Openscreen`, `~/Library/Application Support/Openscreen` or `~/.config/openscreen`.
## Launch and HUD