[feat] add top-level CLI spans to pull request dashboard scripts (#506)

Follow the OpenTelemetry semantic conventions for CLI programs so each
script run and each spawned command shows in the workflow trace.

- Wrap each entry point in an INTERNAL span named by the script file,
  with process.executable.name, process.pid, process.exit.code and
  error.type; any non-zero exit code sets the status to ERROR
- Add CLIENT spans around the commands process_queue_batch starts; the
  child gets this span as its TRACEPARENT parent
- Run drain_queue jobs in a copy of the current context
- Record no command arguments, exception messages or stack traces
- Keep export off by default; spans are no-ops without the SDK
- Document span names and attributes in the README

Author: adrielp

.github/scripts/pull-request-dashboard/dashboard.py

@@ -1053,5 +1053,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="dashboard.py"):
         sys.exit(main())

.github/scripts/pull-request-dashboard/delivery.py

@@ -382,5 +382,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="delivery.py"):
         sys.exit(main())

.github/scripts/pull-request-dashboard/drain_queue.py

@@ -2,6 +2,8 @@
 
 import argparse
 import concurrent.futures
+import contextvars
+import functools
 import json
 import os
 import subprocess
@@ -166,7 +168,10 @@ def return_claims(claims: list[Claim]) -> None:
                         ])
                         break
                     jobs += 1
-                    future = executor.submit(process_job, repository_claims, jobs)
+                    # Run each job in a copy of this thread's context, so spans and
+                    # propagation in process_job keep the run's parent context.
+                    in_context = functools.partial(contextvars.copy_context().run, process_job)
+                    future = executor.submit(in_context, repository_claims, jobs)
                     active[future] = repository
 
             if not active:
@@ -522,5 +527,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="drain_queue.py"):
         raise SystemExit(main())

.github/scripts/pull-request-dashboard/enqueue_dashboard.py

@@ -106,5 +106,5 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="enqueue_dashboard.py"):
         main()

.github/scripts/pull-request-dashboard/process_queue_batch.py

@@ -21,7 +21,7 @@
 from execution_process import run_monitored, subprocess_options
 from queue_worker_client import QueueWorkerClient, acknowledge_results
 import state_branch as state_branch_git
-from telemetry import child_environment
+from telemetry import child_environment, child_process_span
 from telemetry import session as telemetry_session
 
 SCRIPT_DIR = Path(__file__).resolve().parent
@@ -705,19 +705,23 @@ def _run(
         env: dict[str, str],
         print_stdout: bool = True,
     ) -> subprocess.CompletedProcess[str]:
-        env = child_environment(env)
-        if self.lease_check is None:
-            result = self.run(
-                command,
-                cwd=self.repository_root,
-                env=env,
-                text=True,
-                encoding="utf-8",
-                capture_output=True,
-                **subprocess_options(),
-            )
-        else:
-            result = run_monitored(command, self.lease_check, cwd=self.repository_root, env=env)
+        with child_process_span(command) as record_exit:
+            env = child_environment(env)
+            if self.lease_check is None:
+                result = self.run(
+                    command,
+                    cwd=self.repository_root,
+                    env=env,
+                    text=True,
+                    encoding="utf-8",
+                    capture_output=True,
+                    **subprocess_options(),
+                )
+            else:
+                result = run_monitored(
+                    command, self.lease_check, cwd=self.repository_root, env=env
+                )
+            record_exit(result.returncode)
         if result.stdout and print_stdout:
             print(result.stdout, end="")
         if result.stderr:
@@ -833,5 +837,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="process_queue_batch.py"):
         sys.exit(main())

.github/scripts/pull-request-dashboard/promote_rollout.py

@@ -75,5 +75,5 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="promote_rollout.py"):
         main()

.github/scripts/pull-request-dashboard/publish_dashboard.py

@@ -322,5 +322,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="publish_dashboard.py"):
         sys.exit(main())

.github/scripts/pull-request-dashboard/refresh_author_nudges.py

@@ -306,5 +306,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="refresh_author_nudges.py"):
         raise SystemExit(main())

.github/scripts/pull-request-dashboard/report_rate_limits.py

@@ -61,5 +61,5 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="report_rate_limits.py"):
         main()

.github/scripts/pull-request-dashboard/state.py

@@ -1454,5 +1454,5 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    with telemetry_session():
+    with telemetry_session(name="state.py"):
         sys.exit(main())