chore: import upstream snapshot with attribution

doc/source/ray-observability/doc_code/app_logging.py

@@ -0,0 +1,22 @@
+import ray
+
+# Initiate a driver.
+ray.init()
+
+
+@ray.remote
+def task():
+    print("task")
+
+
+ray.get(task.remote())
+
+
+@ray.remote
+class Actor:
+    def ready(self):
+        print("actor")
+
+
+actor = Actor.remote()
+ray.get(actor.ready.remote())

doc/source/ray-observability/doc_code/gotchas.py

@@ -0,0 +1,34 @@
+# flake8: noqa
+# __env_var_start__
+import ray
+import os
+
+ray.init()
+
+
+@ray.remote
+def myfunc():
+    myenv = os.environ.get("FOO")
+    print(f"myenv is {myenv}")
+    return 1
+
+
+ray.get(myfunc.remote())
+# this prints: "myenv is None"
+# __env_var_end__
+ray.shutdown()
+
+# __env_var_fix_start__
+ray.init(runtime_env={"env_vars": {"FOO": "bar"}})
+
+
+@ray.remote
+def myfunc():
+    myenv = os.environ.get("FOO")
+    print(f"myenv is {myenv}")
+    return 1
+
+
+ray.get(myfunc.remote())
+# this prints: "myenv is bar"
+# __env_var_fix_end__

doc/source/ray-observability/doc_code/memray_profiling.py

@@ -0,0 +1,40 @@
+# __memray_profiling_start__
+import memray
+import ray
+
+
+@ray.remote
+class Actor:
+    def __init__(self):
+        # Every memory allocation after `__enter__` method will be tracked.
+        memray.Tracker(
+            "/tmp/ray/session_latest/logs/"
+            f"{ray.get_runtime_context().get_actor_id()}_mem_profile.bin"
+        ).__enter__()
+        self.arr = [bytearray(b"1" * 1000000)]
+
+    def append(self):
+        self.arr.append(bytearray(b"1" * 1000000))
+
+
+a = Actor.remote()
+ray.get(a.append.remote())
+# __memray_profiling_end__
+
+
+# __memray_profiling_task_start__
+import memray  # noqa
+import ray  # noqa
+
+
+@ray.remote
+def task():
+    with memray.Tracker(
+        "/tmp/ray/session_latest/logs/"
+        f"{ray.get_runtime_context().get_task_id()}_mem_profile.bin"
+    ):
+        arr = bytearray(b"1" * 1000000)  # noqa
+
+
+ray.get(task.remote())
+# __memray_profiling_task_end__

doc/source/ray-observability/doc_code/metrics_example.py

@@ -0,0 +1,61 @@
+import time
+
+import ray
+from ray.util.metrics import Counter, Gauge, Histogram
+
+ray.init(_metrics_export_port=8080)
+
+
+@ray.remote
+class MyActor:
+    def __init__(self, name):
+        self._curr_count = 0
+
+        self.counter = Counter(
+            "num_requests",
+            description="Number of requests processed by the actor.",
+            tag_keys=("actor_name",),
+        )
+        self.counter.set_default_tags({"actor_name": name})
+
+        self.gauge = Gauge(
+            "curr_count",
+            description="Current count held by the actor. Goes up and down.",
+            tag_keys=("actor_name",),
+        )
+        self.gauge.set_default_tags({"actor_name": name})
+
+        self.histogram = Histogram(
+            "request_latency",
+            description="Latencies of requests in ms.",
+            boundaries=[0.1, 1],
+            tag_keys=("actor_name",),
+        )
+        self.histogram.set_default_tags({"actor_name": name})
+
+    def process_request(self, num):
+        start = time.time()
+        self._curr_count += num
+
+        # Increment the total request count.
+        self.counter.inc()
+        # Update the gauge to the new value.
+        self.gauge.set(self._curr_count)
+        # Record the latency for this request in ms.
+        self.histogram.observe(1000 * (time.time() - start))
+
+        return self._curr_count
+
+
+print("Starting actor.")
+my_actor = MyActor.remote("my_actor")
+print("Calling actor.")
+my_actor.process_request.remote(-10)
+print("Calling actor.")
+my_actor.process_request.remote(5)
+print("Metrics should be exported.")
+print("See http://localhost:8080 (this may take a few seconds to load).")
+
+# Sleep so we can look at the metrics before exiting.
+time.sleep(30)
+print("Exiting!")

doc/source/ray-observability/doc_code/ray-distributed-debugger.py

@@ -0,0 +1,30 @@
+import ray
+import sys
+
+# Add the RAY_DEBUG_POST_MORTEM=1 environment variable
+# if you want to activate post-mortem debugging
+ray.init(
+    runtime_env={
+        "env_vars": {"RAY_DEBUG_POST_MORTEM": "1"},
+    }
+)
+
+
+@ray.remote
+def my_task(x):
+    y = x * x
+    breakpoint()  # Add a breakpoint in the Ray task.
+    return y
+
+
+@ray.remote
+def post_mortem(x):
+    x += 1
+    raise Exception("An exception is raised.")
+    return x
+
+
+if len(sys.argv) == 1:
+    ray.get(my_task.remote(10))
+else:
+    ray.get(post_mortem.remote(10))