[cueweb/docs] Add optional Loki backend for frame log viewing (#2447)

## Related Issues
- #2456

## Summarize your change.

[cueweb] Add optional Loki backend for frame log viewing

When NEXT_PUBLIC_LOKI_URL is set, the frame log viewer queries Loki by
frame_id instead of reading the on-disk .rqlog file, mirroring CueGUI's
LokiViewPlugin. Falls back to the file-based viewer when unset.

- [x] lib/loki.ts: Loki HTTP API client (label values for frame
attempts, query_range for log lines)
- [x] frames/[frame-name]: branch on the env flag; new LokiLogView
reuses the same Monaco editor, version dropdown, and empty/loading
states
- [x] Document NEXT_PUBLIC_LOKI_URL in README.md and .env.example
- [x] Add lib/loki.ts unit tests

[cueweb/docs] Document the optional Loki frame-log backend

The frame log viewer now has two interchangeable backends: the default
file-based reader (.rqlog on disk) and an optional Loki backend selected
by NEXT_PUBLIC_LOKI_URL, mirroring CueGUI's Loki log viewer. Document it
across all guides:

- [x] quick-starts: a NEXT_PUBLIC_LOKI_URL note in the .env example and
the "View Logs" step.
- [x] concepts: "Frame logs (file-based and Loki)" — the two read paths
and why the backend is a single deploy-time switch.
- [x] getting-started: "Frame log viewing (file-based or Loki)" deploy
section (build arg, browser-read, CORS, the log mount becomes optional)
plus a Loki entry in the .env config block.
- [x] user-guide: expand the Frame Log Viewer section to cover both
backends (Loki "log versions" are frame attempts, with a Refresh
button).
- [x] other-guides: a feature-list entry for the optional Loki backend.
- [x] reference: a NEXT_PUBLIC_LOKI_URL env-var row, a "Frame log
backends" comparison table + lib/loki.ts API summary, and updated the
log-viewer and volume-mount notes.
- [x] tutorials: note that the viewer behaves the same on the Loki
backend.
- [x] developer-guide: a "Frame log backends (file-based and Loki)"
section (isLokiEnabled() branch, lib/loki.ts, LokiLogView) and the
FrameViewer bullet.

## LLM usage disclosure
Parts of this solution's implementation were developed with assistance
from Claude Opus.

Author: ramonfigueiredo

cueweb/.env.example

@@ -1,5 +1,10 @@
 NEXT_PUBLIC_OPENCUE_ENDPOINT=http://your-rest-gateway-url.com
 
+# Optional: Loki log backend. When set, the frame log viewer queries this Loki
+# server (by frame id) instead of reading the on-disk .rqlog file. Leave unset
+# to use the default file-based log viewer.
+# NEXT_PUBLIC_LOKI_URL=http://your-loki-host:3100
+
 # Short Git SHA shown in the "About CueWeb" dialog (Help -> About CueWeb).
 # Build-time only; CI injects it, e.g.
 #   docker build --build-arg NEXT_PUBLIC_GIT_SHA=$(git rev-parse --short HEAD) ...

cueweb/README.md

@@ -250,11 +250,23 @@ Next is the process to install and use the CueWeb system.
         SENTRY_PROJECT = sentryproject
         ```
 
+    - Loki log backend (optional)
+        - NEXT_PUBLIC_LOKI_URL
+            - When set, the frame log viewer queries a [Grafana Loki](https://grafana.com/oss/loki/) server for a frame's logs (by `frame_id`) instead of reading the on-disk `.rqlog` file. This mirrors CueGUI's `LokiViewPlugin` (`cuegui/cuegui/plugins/LokiViewPlugin.py`) and requires RQD to be configured to ship frame logs to Loki.
+            - Set it to the base URL of your Loki HTTP API, e.g. `http://your-loki-host:3100` (no trailing path; CueWeb appends `/loki/api/v1/...`). The viewer lists each frame attempt as a selectable "log version" (Loki's `session_start_time` label), newest first.
+            - **If `NEXT_PUBLIC_LOKI_URL` is not set, CueWeb falls back to the default file-based log viewer.** No other configuration is required to keep the existing behavior.
+            - Because this is a `NEXT_PUBLIC_*` variable it is read in the browser, so the Loki server must be reachable from clients and must permit cross-origin (CORS) requests from the CueWeb origin.
+
 Example of `.env` file (`cueweb/.env.example`):
 
 ```env
 NEXT_PUBLIC_OPENCUE_ENDPOINT=http://your-rest-gateway-url.com
 
+# Optional: Loki log backend. When set, the frame log viewer queries Loki by
+# frame id instead of reading the on-disk .rqlog file. Leave unset to use the
+# default file-based log viewer.
+# NEXT_PUBLIC_LOKI_URL=http://your-loki-host:3100
+
 # Sentry values
 SENTRY_ENVIRONMENT='development'
 SENTRY_DSN = sentrydsn

cueweb/app/__tests__/loki.test.ts

@@ -0,0 +1,187 @@
+/*
+ * Copyright Contributors to the OpenCue Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  getFrameLogLines,
+  getFrameLogVersions,
+  getLokiUrl,
+  isLokiEnabled,
+} from '@/lib/loki';
+
+// The module reads process.env.NEXT_PUBLIC_LOKI_URL at call time (not at
+// import time), so each test just sets the env var before exercising the API.
+const ORIGINAL_LOKI_URL = process.env.NEXT_PUBLIC_LOKI_URL;
+
+function setLokiUrl(lokiUrl?: string) {
+  if (lokiUrl === undefined) {
+    delete process.env.NEXT_PUBLIC_LOKI_URL;
+  } else {
+    process.env.NEXT_PUBLIC_LOKI_URL = lokiUrl;
+  }
+}
+
+afterEach(() => {
+  setLokiUrl(ORIGINAL_LOKI_URL);
+  jest.restoreAllMocks();
+});
+
+function mockFetch(jsonByUrl: (url: string) => unknown, ok = true, status = 200) {
+  const fn = jest.fn(async (url: string) => ({
+    ok,
+    status,
+    json: async () => jsonByUrl(url),
+  }));
+  // @ts-expect-error - assigning a test double to the global fetch.
+  global.fetch = fn;
+  return fn;
+}
+
+describe('isLokiEnabled / getLokiUrl', () => {
+  it('reports disabled when the env var is unset', () => {
+    setLokiUrl(undefined);
+    expect(isLokiEnabled()).toBe(false);
+    expect(getLokiUrl()).toBe('');
+  });
+
+  it('reports disabled for a blank/whitespace value', () => {
+    setLokiUrl('   ');
+    expect(isLokiEnabled()).toBe(false);
+  });
+
+  it('reports enabled and strips trailing slashes', () => {
+    setLokiUrl('http://loki:3100/');
+    expect(isLokiEnabled()).toBe(true);
+    expect(getLokiUrl()).toBe('http://loki:3100');
+  });
+});
+
+describe('getFrameLogVersions', () => {
+  it('returns attempts newest-first with human-readable labels', async () => {
+    setLokiUrl('http://loki:3100');
+    const fetchFn = mockFetch(() => ({
+      status: 'success',
+      data: ['1700000000', '1700009999', '1700005000'],
+    }));
+
+    const versions = await getFrameLogVersions('frame-123', 1699999999);
+
+    // Sorted descending by the unix timestamp.
+    expect(versions.map((v) => v.sessionStartTime)).toEqual([
+      '1700009999',
+      '1700005000',
+      '1700000000',
+    ]);
+    // Each gets a formatted label (not just the raw number).
+    expect(versions[0].label).toMatch(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/);
+
+    // Hits the label_values endpoint with a frame_id selector + start bound.
+    const calledUrl = fetchFn.mock.calls[0][0] as string;
+    expect(calledUrl).toContain('/loki/api/v1/label/session_start_time/values');
+    expect(decodeURIComponent(calledUrl)).toContain('{frame_id="frame-123"}');
+    expect(calledUrl).toContain('start=1699999999000000000');
+  });
+
+  it('returns an empty list when frameId is missing (no fetch)', async () => {
+    setLokiUrl('http://loki:3100');
+    const fetchFn = mockFetch(() => ({ status: 'success', data: [] }));
+    expect(await getFrameLogVersions('')).toEqual([]);
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+});
+
+describe('getFrameLogLines', () => {
+  it('concatenates the line values across streams', async () => {
+    setLokiUrl('http://loki:3100');
+    const fetchFn = mockFetch(() => ({
+      status: 'success',
+      data: {
+        resultType: 'streams',
+        result: [
+          {
+            stream: { frame_id: 'frame-123' },
+            values: [
+              ['1700000001000000000', 'line one'],
+              ['1700000002000000000', 'line two'],
+            ],
+          },
+        ],
+      },
+    }));
+
+    const text = await getFrameLogLines('frame-123', '1700000000');
+
+    expect(text).toBe('line one\nline two');
+    const calledUrl = fetchFn.mock.calls[0][0] as string;
+    expect(calledUrl).toContain('/loki/api/v1/query_range');
+    // URLSearchParams form-encodes spaces as '+'; Loki decodes them back.
+    expect(decodeURIComponent(calledUrl).replace(/\+/g, ' ')).toContain(
+      '{session_start_time="1700000000", frame_id="frame-123"}',
+    );
+    expect(calledUrl).toContain('direction=backward');
+  });
+
+  it('interleaves multiple streams in chronological order', async () => {
+    setLokiUrl('http://loki:3100');
+    // stdout and stderr arrive as separate streams, out of order relative to
+    // each other. Timestamps exceed Number.MAX_SAFE_INTEGER on purpose.
+    mockFetch(() => ({
+      status: 'success',
+      data: {
+        resultType: 'streams',
+        result: [
+          {
+            stream: { stream: 'stdout' },
+            values: [
+              ['1700000001000000000', 'out-1'],
+              ['1700000003000000000', 'out-3'],
+            ],
+          },
+          {
+            stream: { stream: 'stderr' },
+            values: [
+              ['1700000002000000000', 'err-2'],
+              ['1700000004000000000', 'err-4'],
+            ],
+          },
+        ],
+      },
+    }));
+
+    const text = await getFrameLogLines('frame-123', '1700000000');
+    expect(text).toBe('out-1\nerr-2\nout-3\nerr-4');
+  });
+
+  it('returns an empty string when Loki has no streams', async () => {
+    setLokiUrl('http://loki:3100');
+    mockFetch(() => ({ status: 'success', data: { result: [] } }));
+    expect(await getFrameLogLines('frame-123', '1700000000')).toBe('');
+  });
+
+  it('throws when the Loki request fails', async () => {
+    setLokiUrl('http://loki:3100');
+    mockFetch(() => ({}), false, 502);
+    await expect(getFrameLogLines('frame-123', '1700000000')).rejects.toThrow(
+      /Loki request failed \(502\)/,
+    );
+  });
+
+  it('throws when Loki is not configured', async () => {
+    setLokiUrl(undefined);
+    await expect(getFrameLogLines('frame-123')).rejects.toThrow(
+      /not configured/,
+    );
+  });
+});