What Data Does the RunLog Struct Contain in OpenResearch?

The RunLog struct in alphaXiv/OpenResearch encapsulates eight fields that store raw log bytes alongside pagination metadata, including byte offsets, truncation indicators, and source identifiers.

The alphaXiv/OpenResearch CLI relies on the RunLog struct to represent discrete excerpts from execution logs. Defined in src/plane.rs at lines 45‑54, this structure serves as the primary data transfer object between the storage layer and the orx logs command, enabling paginated log views with full positional context.

RunLog Struct Location and Purpose

According to the alphaXiv/OpenResearch source code, the RunLog struct resides in src/plane.rs and represents a single log excerpt for a run. It bridges raw log streams from various sources—local files, containers, or remote hosts—with the terminal interface, preserving both the content slice and its exact position within the complete log file.

Data Fields in the RunLog Struct

The struct contains eight fields that divide logically into content data, positional metadata, and status flags.

Raw Content and Byte Positioning

These four fields define exactly what bytes were read and where they sit in the original file:

• content: Vec<u8> — The raw bytes of the log segment that were read from the source.
• start_byte: i64 — The zero‑based byte offset where this slice begins in the original log.
• end_byte: i64 — The exclusive byte offset where this slice ends.
• total_bytes: i64 — The full size of the underlying log file or stream in bytes, enabling percentage calculations and progress indicators.

Source Identification and Truncation Flags

These four fields provide context about the log source and whether the excerpt represents the complete file:

• source: String — Identifier of the log source, such as a file name, container ID, or remote host name.
• truncated_before: bool — Set to true when earlier bytes were omitted, indicating the excerpt starts after the beginning of the log.
• truncated_after: bool — Set to true when later bytes were omitted, indicating the excerpt ends before the full log.
• missing_local: bool — Set to true when the log cannot be fetched locally, typically because the run executed on a remote compute node.

Working with RunLog in Practice

The CLI constructs RunLog instances through the storage layer defined in src/store.rs and renders them via the command handler in src/commands/logs.rs. The runtime logic in src/local/run.rs populates these structs during log streaming.

Fetching a RunLog via the API

When retrieving logs programmatically, you construct a LogRequest and await the RunLog response:

// Example: fetching a run's log via the CLI API
let log_req = LogRequest {
    mode: "text".into(),
    max_bytes: Some(1024),          // limit to 1 KB
    start_byte: None,
    end_byte: None,
};

let run_log: RunLog = client.get_run_log("run-id-123", log_req).await?;

// Inspect the returned fields
println!("Source: {}", run_log.source);
println!("Bytes {}-{} of {}", run_log.start_byte, run_log.end_byte, run_log.total_bytes);
println!("Has more above? {}", run_log.truncated_before);
println!("Has more below? {}", run_log.truncated_after);
println!("Log excerpt:\n{}", String::from_utf8_lossy(&run_log.content));

Rendering the Log Footer

The RunLog struct provides the footer() method to generate human‑readable pagination metadata used by the orx logs output:

// Rendering the footer (used by `orx logs` output)
println!("{}", run_log.footer());
// Example output:
// [my_container] bytes 0-1024 of 58732 (more below)

Architecture and Related Components

The RunLog struct does not exist in isolation. Several files in the alphaXiv/OpenResearch repository collaborate to populate and display it:

• src/plane.rs — Defines RunLog, its fields, and the footer helper used for CLI display.
• src/commands/logs.rs — Implements the orx logs command that retrieves RunLog instances and prints them to the terminal.
• src/store.rs — Provides StoredRun and persistence logic; RunLog is built from data fetched via this layer.
• src/local/run.rs — Contains the runtime logic for executing runs and streaming logs, which ultimately populate a RunLog.

Summary

• The RunLog struct in src/plane.rs contains eight fields: four for byte positioning (content, start_byte, end_byte, total_bytes) and four for context (source, truncated_before, truncated_after, missing_local).
• It represents a paginated excerpt rather than a full log file, explicitly tracking whether data was truncated at the beginning or end.
• The footer() method consumes these fields to generate human‑readable output like [source] bytes X-Y of Z (more below).
• The struct is populated by src/store.rs and src/local/run.rs, then rendered by src/commands/logs.rs.

Frequently Asked Questions

How is RunLog different from a raw log file?

Unlike a raw log file handle, RunLog explicitly tracks pagination through start_byte, end_byte, and total_bytes fields. It also carries boolean flags indicating truncation, allowing the CLI to tell users when additional log content exists above or below the current view.

What does the missing_local field indicate?

The missing_local field is set to true when the log cannot be retrieved from the local filesystem, typically because the run executed on a remote compute node. This signals to the CLI that it must fetch logs via a remote API rather than reading local disk.

How does the footer method format output?

The RunLog::footer() method, implemented in src/plane.rs, combines the source string with byte range information and truncation flags to produce strings like [container_id] bytes 0-1024 of 58732 (more below), giving users immediate context about their position in the log stream.

Where does RunLog get its byte offset information?

Byte offsets originate in the storage layer (src/store.rs) and runtime execution layer (src/local/run.rs). When the CLI requests a log segment via src/commands/logs.rs, these lower layers calculate the appropriate slice boundaries based on the LogRequest parameters and populate the start_byte and end_byte fields accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}