Document iter_deployment_logs in README and logs example

Signed-off-by: Honglin Cao <hocao@nvidia.com>

Author: V2arK

README.md

@@ -55,13 +55,19 @@ delete the deployment automatically.
 
 ### Deployment logs SDK example
 
-Logs are read per pod. Discover pod names with `get_deployment_pods()` (terminated
-pods still within log retention are included), then read with a
-`deployment_log_session()`: `fetch_older()` pages toward the beginning of history and
-`fetch_newer()` returns only new lines, while the session keeps the merged, ordered
-log in `.events`. `get_deployment_logs_range()` fetches a specific time window
-(epoch-millisecond bounds, both optional) and, with `pod=None`, merges every pod's
-stream chronologically. The same paging is available statelessly through
+`iter_deployment_logs()` streams a revision's logs lazily, oldest first, each line
+exactly once, with bounded memory however long the log is — by default merging every
+pod chronologically (each event carries its pod name). `follow=False` returns once
+caught up; `follow=True` keeps tailing and picks up new pods of the revision as they
+first log. `start_time` (epoch ms) bounds the beginning and `pod=` restricts to one
+pod — discover names with `get_deployment_pods()` (terminated pods still within log
+retention are included).
+
+For non-streaming access: `get_deployment_logs_range()` fetches a specific time
+window as a list (epoch-millisecond bounds, both optional; `pod=None` merges every
+pod). A `deployment_log_session()` pages one pod statefully — `fetch_older()` toward
+the beginning of history, `fetch_newer()` for only-new lines — keeping the merged,
+ordered log in `.events`. The same paging is available statelessly through
 `get_deployment_logs(before=..., after=...)`, anchored on events you already hold
 or on a bare epoch-millisecond boundary:
 

examples/sdk/get_deployment_logs.py

@@ -1,60 +1,54 @@
-import time
+import itertools
 from datetime import datetime, timezone
 
 from centml.sdk.api import get_centml_client
 
 # --- Configuration ---
 DEPLOYMENT_ID = 1234  # Replace with your deployment ID
 REVISION_NUMBER = 10
-TAIL_SECONDS = 30  # How long to keep polling for new lines after reading history
-TAIL_LINES = 20  # How much history to print before tailing
+FOLLOW_LINES = 20  # How many tailed lines to print before stopping the follow
 
 
 def format_event(event) -> str:
     ts = datetime.fromtimestamp(event.timestamp / 1000, tz=timezone.utc).isoformat()
-    return f"[{ts}] {event.message}"
+    return f"[{ts}] {event.pod} {event.message}"
 
 
 def main():
     with get_centml_client() as cclient:
-        # Logs are read per pod: discover the pods that have logged for this revision
-        # (terminated pods within log retention are included).
-        pods = cclient.get_deployment_pods(DEPLOYMENT_ID, REVISION_NUMBER)
-        if not pods:
-            print("No pods have logged for this revision yet.")
-            return
-
-        pod = pods[0]
-        print(f"Reading logs for deployment {DEPLOYMENT_ID} revision {REVISION_NUMBER}, pod {pod}\n")
-
-        # The session tracks what it has fetched and anchors every request itself.
-        session = cclient.deployment_log_session(DEPLOYMENT_ID, REVISION_NUMBER, pod)
-
-        # Read the full history: newest page first, then page back to the beginning.
-        while session.fetch_older():
-            pass
-        events = session.events
-        print(f"Found {len(events)} log entries; showing the last {TAIL_LINES}:\n")
-        for event in events[-TAIL_LINES:]:
+        # Stream the revision's full history, all pods merged chronologically.
+        # The iterator is lazy: pages are fetched as you consume it, and its held
+        # state stays bounded no matter how many lines stream by.
+        print(f"Logs for deployment {DEPLOYMENT_ID} revision {REVISION_NUMBER}:\n")
+        count = 0
+        for event in cclient.iter_deployment_logs(DEPLOYMENT_ID, REVISION_NUMBER):
+            print(format_event(event))
+            count += 1
+        print(f"\nCaught up after {count} lines.")
+
+        # follow=True keeps tailing instead of returning: it re-polls caught-up pods
+        # every poll_interval seconds and picks up new pods of the revision as they
+        # first log. Stop by breaking out (or just abandon the iterator).
+        print(f"\nFollowing; stopping after {FOLLOW_LINES} new lines...")
+        stream = cclient.iter_deployment_logs(DEPLOYMENT_ID, REVISION_NUMBER, follow=True)
+        for event in itertools.islice(stream, FOLLOW_LINES):
             print(format_event(event))
 
-        # Keep tailing: each call returns only the lines the session does not hold yet.
-        print(f"\nPolling for new lines for {TAIL_SECONDS}s...")
-        deadline = time.monotonic() + TAIL_SECONDS
-        while time.monotonic() < deadline:
-            for event in session.fetch_newer():
-                print(format_event(event))
-            time.sleep(2)
-
-        # The same paging is available statelessly via get_deployment_logs, anchored
-        # on events you already hold — useful when you manage storage yourself:
-        #   page  = cclient.get_deployment_logs(DEPLOYMENT_ID, REVISION_NUMBER, pod=pod)  # tail
-        #   older = cclient.get_deployment_logs(..., pod=pod, before=page)  # empty return = beginning
-        #   newer = cclient.get_deployment_logs(..., pod=pod, after=page)   # empty return = nothing new
-        # A specific time window (all pods merged, oldest first, pod on each event):
+        # A single pod (discover names with get_deployment_pods) or a bounded start:
+        #   pods = cclient.get_deployment_pods(DEPLOYMENT_ID, REVISION_NUMBER)
+        #   for event in cclient.iter_deployment_logs(
+        #       DEPLOYMENT_ID, REVISION_NUMBER, pod=pods[0], start_time=t1_ms
+        #   ):
+        #       ...
+        # A specific time window as a list (all pods merged, oldest first):
         #   window = cclient.get_deployment_logs_range(
         #       DEPLOYMENT_ID, REVISION_NUMBER, start_time=t1_ms, end_time=t2_ms
         #   )
+        # Manual paging, anchored on events you already hold — useful when you
+        # manage storage yourself (deployment_log_session wraps this statefully):
+        #   page  = cclient.get_deployment_logs(DEPLOYMENT_ID, REVISION_NUMBER, pod=pods[0])  # tail
+        #   older = cclient.get_deployment_logs(..., pod=pods[0], before=page)  # empty return = beginning
+        #   newer = cclient.get_deployment_logs(..., pod=pods[0], after=page)   # empty return = nothing new
 
 
 if __name__ == "__main__":