{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# S2 lab notebook — latency, the edge and instance sizing\n",
    "\n",
    "Measure the same JPEG from your laptop to the Singapore origin and through the Cloudflare edge — cold and on a reused connection — compute the p95, read the cache status, benchmark the Droplet before and after the resize, and write `latency_results.json`.\n",
    "\n",
    "The bundled `data/latency_sample.csv`, `data/benchmark_sample.csv` and `data/cache_sample.csv` are worked samples. Replace them with your own measurements from the lab; the assertions check the shape, not your exact numbers.\n",
    "\n",
    "**You submit:** `latency_results.json`, `latency_p95.png`, the benchmark table, a 150–250 word *what this proves* note, and the teardown log.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "สมุดบันทึกนี้วัดภาพ JPEG เดียวกันสองเส้นทาง คือจากเครื่องของคุณไปยังเครื่องต้นทางที่สิงคโปร์ และผ่านขอบเครือข่ายของ Cloudflare คำนวณ p95 อ่านสถานะแคช ทดสอบ Droplet ก่อนและหลังปรับขนาด แล้วเขียนไฟล์ latency_results.json ข้อมูลตัวอย่างที่มาพร้อมบทเรียนใช้ทดลองได้ก่อน แต่ให้แทนที่ด้วยค่าที่คุณวัดเอง การตรวจสอบในสมุดบันทึกตรวจรูปร่างของข้อมูล ไม่ได้ตรวจว่าตัวเลขตรงกับตัวอย่าง\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "这个 notebook 沿两条路径测量同一张 JPEG：从你的电脑到新加坡的源站，以及经过 Cloudflare 的边缘。它计算 p95、读取缓存状态、在调整规格前后分别对 Droplet 做基准测试，然后写出 latency_results.json。随课程提供的示例数据可以先用来试跑，但要用你自己测得的值替换它。notebook 中的断言检查数据的形状，而不检查数字是否与示例一致。\n",
    "</details>\n"
   ],
   "id": "s2-01"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import os\n",
    "import random\n",
    "import sys\n",
    "from pathlib import Path\n",
    "\n",
    "import matplotlib\n",
    "matplotlib.use(\"Agg\")\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "SEED = 42\n",
    "random.seed(SEED)\n",
    "np.random.seed(SEED)\n",
    "print(\"seed\", SEED)\n",
    "print(\"Python\", sys.version.split()[0])\n",
    "assert sys.version_info >= (3, 11)\n",
    "DEVICE = \"cpu\"\n",
    "print(\"device\", DEVICE, \"(S2 has no accelerator path)\")\n"
   ],
   "id": "s2-02"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Resolve the data and check its shape\n",
    "\n",
    "The notebook prefers your measured files and falls back to the bundled samples, so it still runs offline. A measured file and its sample have the same columns; only the numbers change.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "สมุดบันทึกเลือกไฟล์ที่คุณวัดก่อน ถ้าไม่มีจึงใช้ไฟล์ตัวอย่างที่มาพร้อมบทเรียน ทั้งสองแบบมีคอลัมน์เหมือนกัน ต่างกันแค่ตัวเลข\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "notebook 优先选择你测量的文件；如果没有，就使用随课程提供的示例文件。两者的列相同，只有数字不同。\n",
    "</details>\n"
   ],
   "id": "s2-03"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def search_folders():\n",
    "    folders = [Path(\"data\"), Path(\"results\"), Path(\"/kaggle/input/performance-latency\")]\n",
    "    env = os.environ.get(\"COURSE_DATA\")\n",
    "    if env:\n",
    "        folders.append(Path(env))\n",
    "    return folders\n",
    "\n",
    "def load(measured, sample):\n",
    "    for folder in search_folders():\n",
    "        if (folder / measured).exists():\n",
    "            print(\"reading\", folder / measured)\n",
    "            return pd.read_csv(folder / measured), measured\n",
    "    for folder in search_folders():\n",
    "        if (folder / sample).exists():\n",
    "            print(\"reading\", folder / sample, \"(bundled sample)\")\n",
    "            return pd.read_csv(folder / sample), sample\n",
    "    raise FileNotFoundError(f\"neither {measured} nor {sample} found\")\n",
    "\n",
    "latency, latency_file = load(\"latency_measured.csv\", \"latency_sample.csv\")\n",
    "print(latency.head().to_string(index=False))\n",
    "print(latency.groupby(\"path\").size().to_string())\n",
    "assert {\"path\", \"sample\", \"dns_ms\", \"connect_ms\", \"tls_ms\", \"ttfb_ms\", \"total_ms\"} <= set(latency.columns)\n",
    "assert set(latency[\"path\"]) == {\"origin-direct\", \"cloudflare-edge\", \"cloudflare-edge-warm\"}\n",
    "assert (latency.groupby(\"path\").size() >= 10).all()\n"
   ],
   "id": "s2-04"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Compute p50 and p95 and draw the tail\n",
    "\n",
    "A p95 is the value 95% of requests finish within. All three paths are compared with the Chiang Mai viewer target of 30 ms. The origin-direct path is expected to miss it; the cold edge is lower; the warm edge is the state a browser reaches after reusing its TLS connection and may meet it. The 50 ms Bangkok and 80 ms Singapore targets describe other viewers, not this measurement.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "p95 คือค่าที่คำขอ 95% เสร็จภายใน เส้นทางตรงไปยังเครื่องต้นทางคาดว่าจะไม่ผ่านเป้า 30 มิลลิวินาที ส่วนเส้นทางผ่านขอบเครือข่ายอาจผ่าน เป้า 50 มิลลิวินาทีของกรุงเทพฯ และ 80 ของสิงคโปร์ใช้อธิบายผู้ชมในเมืองนั้น ไม่ใช่การวัดครั้งนี้\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "p95 是 95% 的请求在其中完成的值。直连源站的路径预计达不到 30 毫秒的目标；经过边缘的路径则可能达到。曼谷的 50 毫秒和新加坡的 80 毫秒目标描述的是那些城市的观众，而不是本次测量。\n",
    "</details>\n"
   ],
   "id": "s2-05"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "TARGET_P95_MS = 30\n",
    "summary = (latency.groupby(\"path\")\n",
    "                  .agg(p50_ms=(\"total_ms\", lambda s: np.percentile(s, 50)),\n",
    "                       p95_ms=(\"total_ms\", lambda s: np.percentile(s, 95)),\n",
    "                       samples=(\"total_ms\", \"size\"))\n",
    "                  .round(1))\n",
    "summary[\"target_p95_ms\"] = TARGET_P95_MS\n",
    "summary[\"within_target\"] = summary[\"p95_ms\"] <= TARGET_P95_MS\n",
    "print(summary.to_string())\n",
    "assert (summary[\"p95_ms\"] > 0).all()\n",
    "assert summary.loc[\"cloudflare-edge\", \"p95_ms\"] < summary.loc[\"origin-direct\", \"p95_ms\"]\n",
    "assert summary.loc[\"cloudflare-edge-warm\", \"p95_ms\"] < summary.loc[\"cloudflare-edge\", \"p95_ms\"]\n",
    "\n",
    "ax = summary[\"p95_ms\"].plot(kind=\"bar\", color=[\"#0891b2\", \"#2563eb\", \"#16a34a\"], figsize=(7, 3.5))\n",
    "ax.axhline(TARGET_P95_MS, color=\"#ea580c\", linestyle=\"--\", linewidth=1.5)\n",
    "ax.text(2.45, TARGET_P95_MS + 1, \"Chiang Mai target 30 ms\", color=\"#9a3412\", fontsize=9)\n",
    "ax.set_ylabel(\"p95 total (ms)\")\n",
    "ax.set_xlabel(\"\")\n",
    "ax.set_title(\"Tail latency by request path\")\n",
    "plt.tight_layout()\n",
    "plt.savefig(\"latency_p95.png\", dpi=144)\n",
    "plt.show()\n"
   ],
   "id": "s2-06"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Read the cache evidence\n",
    "\n",
    "The JPEG should be a `MISS` on the first request and a `HIT` on the second; the HTML control should not be a `HIT`. The colo is the edge Cloudflare actually used, read from `/cdn-cgi/trace`. Replace the sample with the headers you saw.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "ภาพ JPEG ควรเป็น MISS ในคำขอแรกและ HIT ในคำขอที่สอง ส่วนหน้า HTML ไม่ควรเป็น HIT ค่า colo คือขอบเครือข่ายที่ Cloudflare เลือกใช้จริง อ่านได้จาก /cdn-cgi/trace ให้แทนที่ตัวอย่างด้วยหัวข้อตอบกลับที่คุณเห็น\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "JPEG 在第一次请求时应该是 MISS，在第二次请求时是 HIT；HTML 页面则不应是 HIT。colo 是 Cloudflare 实际选用的边缘，可以从 /cdn-cgi/trace 读取。请用你看到的响应头替换示例。\n",
    "</details>\n"
   ],
   "id": "s2-07"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cache, cache_file = load(\"cache_measured.csv\", \"cache_sample.csv\")\n",
    "print(cache.to_string(index=False))\n",
    "jpeg = cache.loc[cache[\"path\"].str.endswith(\".jpg\")].iloc[0]\n",
    "html = cache.loc[cache[\"path\"].str.endswith(\".html\")].iloc[0]\n",
    "assert jpeg[\"first_cache\"].upper() == \"MISS\"\n",
    "assert jpeg[\"second_cache\"].upper() == \"HIT\"\n",
    "assert str(html[\"second_cache\"]).upper() not in {\"HIT\", \"REVALIDATED\"}\n",
    "assert jpeg[\"colo\"] in {\"CNX\", \"BKK\", \"SIN\"}\n",
    "print(\"edge colo\", jpeg[\"colo\"], \"| jpeg\", jpeg[\"first_cache\"], \"->\", jpeg[\"second_cache\"],\n",
    "      \"| html\", html[\"second_cache\"] or \"(no header)\")\n"
   ],
   "id": "s2-08"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Compare the instance before and after the resize\n",
    "\n",
    "`benchmark_sample.csv` has one row per measurement: CPU with one and two workers, disk read and write, and whether the 1.5 GiB allocation succeeded. The resize changes vCPU and RAM only; the disk size stays 25 GiB. Shared-vCPU throughput moves with the host and may not rise linearly, so the CPU rows are informative, not a clean multiplier. The hard proof of the resize is `nproc`, `free -h` and the memory recovery.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "ไฟล์ benchmark_sample.csv มีหนึ่งแถวต่อการวัด ได้แก่ CPU หนึ่งและสองเวิร์กเกอร์ ดิสก์อ่านและเขียน และการจองหน่วยความจำ 1.5 GiB ว่าสำเร็จหรือไม่ การปรับขนาดเปลี่ยนเฉพาะ vCPU และแรม ขนาดดิสก์ยังคง 25 GiB\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "benchmark_sample.csv 每次测量一行，包括 CPU 单 worker 和双 worker、磁盘读写，以及 1.5 GiB 内存分配是否成功。调整规格只改变 vCPU 和内存，磁盘大小仍为 25 GiB。\n",
    "</details>\n"
   ],
   "id": "s2-09"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bench, bench_file = load(\"benchmark_measured.csv\", \"benchmark_sample.csv\")\n",
    "values = bench.set_index([\"phase\", \"measure\"])[\"value\"]\n",
    "print(bench.to_string(index=False))\n",
    "\n",
    "required = {(\"before\", \"cpu_single\"), (\"before\", \"cpu_parallel\"),\n",
    "            (\"before\", \"disk_write\"), (\"before\", \"disk_read\"),\n",
    "            (\"before\", \"alloc_1500mb\"), (\"after\", \"cpu_single\"),\n",
    "            (\"after\", \"cpu_parallel\"), (\"after\", \"disk_write\"),\n",
    "            (\"after\", \"disk_read\"), (\"after\", \"alloc_1200mb\")}\n",
    "assert required <= set(values.index)\n",
    "\n",
    "before_single = float(values[(\"before\", \"cpu_single\")])\n",
    "before_parallel = float(values[(\"before\", \"cpu_parallel\")])\n",
    "after_single = float(values[(\"after\", \"cpu_single\")])\n",
    "after_parallel = float(values[(\"after\", \"cpu_parallel\")])\n",
    "\n",
    "speedup_before = round(before_parallel / before_single, 2)\n",
    "speedup_after = round(after_parallel / after_single, 2)\n",
    "print(\"parallel speedup before\", speedup_before, \"after\", speedup_after)\n",
    "\n",
    "assert after_parallel > 0 and after_single > 0\n",
    "assert str(values[(\"before\", \"alloc_1500mb\")]).lower() == \"no\"\n",
    "assert str(values[(\"after\", \"alloc_1200mb\")]).lower() == \"yes\"\n",
    "assert float(values[(\"after\", \"disk_write\")]) > 0\n",
    "assert float(values[(\"after\", \"disk_read\")]) > 0\n"
   ],
   "id": "s2-10"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Write the result file\n",
    "\n",
    "The JSON is the artifact your evidence bundle points to. It records the seed, which file was read, the latency summary, the cache result, the benchmark and the instance facts, so a marker can reproduce the calculation.\n",
    "\n",
    "<details class=\"th\" lang=\"th\">\n",
    "<summary>สรุปภาษาไทย</summary>\n",
    "\n",
    "ไฟล์ JSON คือชิ้นงานที่ชุดหลักฐานอ้างถึง บันทึก seed ไฟล์ที่อ่าน สรุปความหน่วง ผลแคช ผลทดสอบ และข้อมูลเครื่อง เพื่อให้ผู้ตรวจคำนวณซ้ำได้\n",
    "</details>\n",
    "\n",
    "<details class=\"zh\" lang=\"zh-Hans\"><summary>中文总结</summary>\n",
    "\n",
    "JSON 文件是证据包所引用的产物。它记录 seed、读取的文件、延迟摘要、缓存结果、基准测试结果以及机器信息，以便评分者重新计算。\n",
    "</details>\n"
   ],
   "id": "s2-11"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def number(value):\n",
    "    try:\n",
    "        return float(value)\n",
    "    except (TypeError, ValueError):\n",
    "        return value\n",
    "\n",
    "def plan_for(phase):\n",
    "    return bench.loc[bench[\"phase\"] == phase, \"plan\"].iloc[0]\n",
    "\n",
    "results = {\n",
    "    \"seed\": SEED,\n",
    "    \"device\": DEVICE,\n",
    "    \"data\": {\n",
    "        \"latency\": latency_file,\n",
    "        \"benchmark\": bench_file,\n",
    "        \"cache\": cache_file,\n",
    "    },\n",
    "    \"viewer_target_p95_ms\": TARGET_P95_MS,\n",
    "    \"latency\": summary.round(1).to_dict(orient=\"index\"),\n",
    "    \"cache\": {\n",
    "        \"jpeg\": {\"first\": jpeg[\"first_cache\"], \"second\": jpeg[\"second_cache\"]},\n",
    "        \"html_cached\": str(html[\"second_cache\"]).upper() in {\"HIT\", \"REVALIDATED\"},\n",
    "        \"colo\": jpeg[\"colo\"],\n",
    "    },\n",
    "    \"benchmark\": {\n",
    "        \"before\": {\"single_ips\": before_single, \"parallel_ips\": before_parallel,\n",
    "                   \"speedup\": speedup_before},\n",
    "        \"after\": {\"single_ips\": after_single, \"parallel_ips\": after_parallel,\n",
    "                  \"speedup\": speedup_after},\n",
    "        \"disk_write_mbs\": {\"before\": number(values[(\"before\", \"disk_write\")]),\n",
    "                           \"after\": number(values[(\"after\", \"disk_write\")])},\n",
    "        \"disk_read_mbs\": {\"before\": number(values[(\"before\", \"disk_read\")]),\n",
    "                          \"after\": number(values[(\"after\", \"disk_read\")])},\n",
    "    },\n",
    "    \"instance\": {\n",
    "        \"before\": {\"plan\": plan_for(\"before\"), \"vcpus\": 1, \"memory_gb\": 1, \"disk_gb\": 25},\n",
    "        \"after\": {\"plan\": plan_for(\"after\"), \"vcpus\": 2, \"memory_gb\": 2, \"disk_gb\": 25},\n",
    "        \"resize_grew_disk\": False,\n",
    "    },\n",
    "    \"failure_and_recovery\": {\n",
    "        \"before_allocation_mb\": 1500,\n",
    "        \"after_allocation_mb\": 1200,\n",
    "        \"before\": str(values[(\"before\", \"alloc_1500mb\")]),\n",
    "        \"after\": str(values[(\"after\", \"alloc_1200mb\")]),\n",
    "    },\n",
    "    \"cost_ceiling_usd\": 0.10,\n",
    "}\n",
    "Path(\"latency_results.json\").write_text(json.dumps(results, indent=2, default=number))\n",
    "print(json.dumps(results, indent=2, default=number))\n",
    "assert results[\"latency\"][\"cloudflare-edge\"][\"p95_ms\"] < results[\"latency\"][\"origin-direct\"][\"p95_ms\"]\n",
    "assert results[\"cache\"][\"jpeg\"] == {\"first\": \"MISS\", \"second\": \"HIT\"}\n",
    "assert results[\"failure_and_recovery\"] == {\"before_allocation_mb\": 1500, \"after_allocation_mb\": 1200, \"before\": \"no\", \"after\": \"yes\"}\n"
   ],
   "id": "s2-12"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What this proves\n",
    "\n",
    "Write 150–250 words: which path meets the 30 ms target and why, where the missing milliseconds go on the origin-direct path, why the cold edge and the warm edge differ, what the colo tells you about Cloudflare's choice, why the JPEG moves `MISS → HIT` while the HTML does not, how the resize changed the benchmark, and what the memory failure proved. Attach the JSON, the chart and the teardown log.\n",
    "\n",
    "## Verification\n",
    "\n",
    "**Mac (M1 Max, Python 3.14.2, pandas 3.1.1, numpy 2.5.4, matplotlib 3.11.2):** the notebook runs end to end headlessly on the three bundled samples, exits 0 and passes every assertion; replace them with your own measurements. S2 has no accelerator path.\n",
    "\n",
    "**Run status:** the notebook records which files it read in the `data` block of `latency_results.json`.\n"
   ],
   "id": "s2-13"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
