# What Data Does the RunLog Struct Contain in OpenResearch?

> Discover the eight fields within the RunLog struct in alphaXiv/OpenResearch. Understand how it stores raw log bytes and pagination metadata for efficient data management.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: api-reference
- Published: 2026-09-13

---

**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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs) and renders them via the command handler in [`src/commands/logs.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/logs.rs). The runtime logic in [`src/local/run.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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:

```rust
// 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:

```rust
// 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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs)** — Defines `RunLog`, its fields, and the `footer` helper used for CLI display.
- **[`src/commands/logs.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/logs.rs)** — Implements the `orx logs` command that retrieves `RunLog` instances and prints them to the terminal.
- **[`src/store.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)** — Provides `StoredRun` and persistence logic; `RunLog` is built from data fetched via this layer.
- **[`src/local/run.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)** and **[`src/local/run.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/run.rs)**, then rendered by **[`src/commands/logs.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/store.rs)) and runtime execution layer ([`src/local/run.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/run.rs)). When the CLI requests a log segment via [`src/commands/logs.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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.