تصفح الوثائق
الأدلة
أجري بحثاً واحداً مقاساً، أو تلخيص العينات المحفوظة، أو تسليم وسائل الإعلام إلى مخزنك.
في هذه الصفحة
اختر القياس
| Metric | ابدأوا finish |
|---|---|
| وقت الرد على البحث | ابدأوا HTTP أطلب قراءه الجسم الكامل خطوات الاستخدام 1–3 أسفل. |
| منافذ إيصال وسائط الإعلام | وسائل الإعلام المُسلّمة CLI بداية لثواني تشمل عمليات التحقق من إمكانية الوصول، وتقديم التقارير، والاقتراع، والتصدير من النتائج. |
| Async API timings | سجّل قبول الطلب (الطلب → معرّف المهمة) منفصلًا عن اكتماله (الطلب → حالة الاكتمال). استخدم سير عمل async واحتفظ بفاصل الاستعلام الدوري عن الحالة. |
1. إعداد عينة بحث
Use Python 3.10+ and a key with google_search permission in FLASHDATA_API_KEY. ولا توجد حاجة إلى حزم إضافية من طراز Python. استخدمي الـ(بيثون3) بدلاً من (بيثون) إذا كان هذا هو إسم مترجمك
اصنع ملف عمل وفروا جميع النصوص في هذا الملف وأديروا أوامرهم هنا وترسل كل عينة بحثية جديدة استفسارا واحدا دون إعادة النظر تلقائيا؛ ويطبق تسعير الاستفسارات العادية.
mkdir flashdata-benchmark
cd flashdata-benchmark
python --versionاحفظ الطلب
احفظ هذا request.json بالداخل flashdata-benchmark/.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}2. توقيت الاستجابة الكاملة
انقذوا measure.py بجانبك request.json. وتنسخ الطلب إلى ملف عينة جديد، ثم تسجل وقت الاستجابة الكامل، ومركز HTTP، وتطلب إلى ID و Retry-After عند إعادتها. وتستخدم عمليات التصفيات مرحلتين مرحلتين من طراز 120-ثانية. ويتوقف ملف العينة الحالي عن التنفيذ قبل إرسال الطلب.
import hashlib
import json
import os
import platform
import sys
import time
from datetime import datetime, timezone
from http.client import HTTPException
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import HTTPRedirectHandler, Request, build_opener
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
if len(sys.argv) != 4:
raise SystemExit("Usage: python measure.py request.json NEW_DIRECTORY CLIENT_REGION")
key = os.environ.get("FLASHDATA_API_KEY")
if not key:
raise SystemExit("Set FLASHDATA_API_KEY first")
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
if not isinstance(payload, dict) or payload.get("source") != "google_search" \
or set(payload) - {"source", "query", "params"} \
or not isinstance(payload.get("query"), str) or not payload["query"].strip() \
or not isinstance(payload.get("params", {}), dict):
raise SystemExit("This example measures one realtime google_search request")
body = json.dumps(payload, sort_keys=True, allow_nan=False).encode()
settings = json.dumps({"source": payload["source"], "params": payload.get("params", {})},
sort_keys=True, allow_nan=False).encode()
folder = Path(sys.argv[2])
try:
folder.mkdir(mode=0o700)
except FileExistsError:
raise SystemExit("Sample directory already exists; no request sent. Inspect its saved files.")
(folder / "request.json").write_bytes(body)
request = Request("https://data.flashdata.dev/v1/queries/realtime", data=body,
headers={"X-API-Key": key, "Content-Type": "application/json", "Accept": "application/json"})
report = {"started_at": datetime.now(timezone.utc).isoformat(),
"region": sys.argv[3], "source": payload["source"], "mode": "realtime",
"input_sha256": hashlib.sha256(body).hexdigest(),
"settings_sha256": hashlib.sha256(settings).hexdigest(), "concurrency": 1,
"python_version": platform.python_version(), "timeout_seconds": 120,
"http_status": None, "request_id": None, "retry_after": None,
"elapsed_ms": None, "outcome": "unknown"}
(folder / "timing.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
raw = b""
start = time.perf_counter()
try:
try:
response = build_opener(NoRedirect()).open(request, timeout=120)
except HTTPError as error:
response = error
with response:
report["http_status"] = response.status
report["request_id"] = response.headers.get("X-Request-Id")
report["retry_after"] = response.headers.get("Retry-After")
raw = response.read()
except (URLError, OSError, HTTPException):
report["error"] = "transport_error_or_timeout"
report["elapsed_ms"] = round((time.perf_counter() - start) * 1000, 3)
try:
result = json.loads(raw)
except (ValueError, UnicodeDecodeError):
result = {}
if report["http_status"] is not None and "error" not in report:
complete = report["http_status"] == 200 and isinstance(result, dict) \
and result.get("status") == "done" and isinstance(result.get("results"), list)
report["outcome"] = "completed" if complete else "failed"
(folder / "response.json").write_bytes(raw)
(folder / "timing.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps(report, indent=2))
raise SystemExit(0 if report["outcome"] == "completed" else 1)تشغيل وفحص
إستبدلْ مُنظّمَ زبونَ بمنطقةِ عملائكَ، مثل eu-west-1. اديروا القيادة الأولى مرة واحدة، والقيادة الثانية تقرأ فقط التوقيت المنقذ.
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.jsonتحقق من الملفات المحفوظة
ينتهي النجاح برمز 0 ويسجّل http_status: 200 وoutcome: completed. يحتوي جسم الاستجابة status: done ومصفوفة results. تنتهي حالتا failed أو unknown برمز 1؛ افحص الملفات قبل تقرير إرسال استعلام آخر.
| File | ما الذي سيتحقق منه؟ |
|---|---|
| sample-01/request.json | المُدخل الدقيق الذي تم إنقاذه قبل التقديم. |
| sample-01/response.json | هيئة استجابة راو؛ HTTP الخطأ قد يعودJSON المحتوى |
| sample-01/timing.json | elapsed_ms وoutcome وhttp_status وrequest_id وretry_after. إذا كانت elapsed_ms تساوي null، فهذا يعني أن العملية لم تُكمل التسجيل. |
3. Summarize Save samples
انقذوا summarize.py بجانبك measure.py. ويقرأ التقرير عينات محلية ويرفض الملفات المزدوجة، والتوقيتات غير المكتملة، والإطارات غير المطابقة للطلبات، أو منطقة العملاء، أو نسخة Python.
وتستعمل شركة p50/p95 أقرب المائين من الردود المنجزة. ولا تزال المحاولات غير المعروفة في المجاميع. وتعطي عينة ناجحة واحدة نفس الجرعة من طراز P50 و p95؛ ولا تعطي عينات ناجحة لرقم null لكليهما.
import json
import math
import sys
from pathlib import Path
if len(sys.argv) < 2:
raise SystemExit("Usage: python summarize.py SAMPLE_DIRECTORY [SAMPLE_DIRECTORY ...]")
folders = [Path(value).resolve() for value in sys.argv[1:]]
if len(set(folders)) != len(folders):
raise SystemExit("Pass each sample directory only once")
rows = [json.loads((folder / "timing.json").read_text(encoding="utf-8")) for folder in folders]
fields = ("source", "mode", "region", "concurrency", "timeout_seconds", "settings_sha256", "python_version")
for row in rows:
if not isinstance(row, dict) or any(field not in row for field in (*fields, "input_sha256")):
raise SystemExit("Use timing.json files written by this measure.py")
elapsed = row.get("elapsed_ms")
if row.get("outcome") not in ("completed", "failed", "unknown") \
or type(elapsed) not in (int, float) or not math.isfinite(elapsed) or elapsed < 0:
raise SystemExit("Incomplete or invalid timing record; inspect it before summarizing")
if len({json.dumps([row[field] for field in fields], sort_keys=True) for row in rows}) != 1:
raise SystemExit("Compare runs separately when source, mode, region or settings differ")
times = sorted(row["elapsed_ms"] for row in rows if row["outcome"] == "completed")
inputs = len({row["input_sha256"] for row in rows})
def percentile(percent):
return times[math.ceil(len(times) * percent / 100) - 1] if times else None
print(json.dumps({"context": {field: rows[0][field] for field in fields},
"attempted": len(rows), "completed": len(times),
"failed": sum(row["outcome"] == "failed" for row in rows),
"unknown": sum(row["outcome"] == "unknown" for row in rows),
"success_rate": len(times) / len(rows), "distinct_inputs": inputs,
"input_pattern": "repeated_input" if inputs == 1 else "varied_inputs",
"successful_latency_ms": {"p50": percentile(50), "p95": percentile(95)}}, indent=2))python summarize.py sample-01يضاف العينات عمدا
القيادة الأولى التي تحتها ترسل بحثاً آخر حافظ على نفس قيمة العملاء و طلباتهم ولتقييم المدخلات المتنوعة، لا يغير سوى الاستفسارات في request.json قبل تشغيله. ويصف التقرير نمط المدخلات ويحسب مدخلات متميزة.
وللتقييم الذي يجريه العملاء، الاتفاق على حساب العينات وميزانية الائتمان أولا. إجراء العينات بالتتابع؛ ويسجل هذا المثال تطابقاً: 1. وفر الملخص مع ملف العينة.
python measure.py request.json sample-02 client-regionpython summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.jsonMeasure media delivery with the CLI
يسلّم هذا المثال المستقل ملف MP3 واحدًا إلى تخزينك. ثبّت CLI واستخدم ملفًا شخصيًا محفوظًا للمالك بصلاحية youtube_download، وأبقِ دليل الحالة متاحًا. يعيد المؤقّت استخدام ذلك الملف الشخصي ويتجاهل FLASHDATA_API_KEY. تنطبق أسعار التنزيل المعتادة.
في "فلاشتاتا بينشمارك" و احفظ مقصدك كفرد storage.json. هذا هو S3 على سبيل المثال، تحتاج إلى دلوكم، منطقة ووثائق تفويض التخزين؛ استخدام ملفك الخاص الحالي إذا كان لديك بالفعل ملف واحد.
{
"storage_type": "s3",
"storage_url": "YOUR_BUCKET",
"access_key": "YOUR_ACCESS_KEY",
"secret_key": "YOUR_SECRET_KEY",
"region": "us-east-1"
}وفر وقت التسليم
انقذوا measure-download.py بجانبك storage.json. ويحتفظ بطائرة جديدة من طراز ID قبل أن تبدأ شركة CLI، وينتظر حتى دقائق من أجل القيادة في 10، وقد انقضت السجلات وقتها من خلال تصدير النتائج. إعادة استخدام ملف العينة يتوقف قبل إطلاق CLI.
import json
import os
import shutil
import subprocess
import sys
import time
import uuid
from datetime import datetime, timezone
from pathlib import Path
if len(sys.argv) not in (6, 7):
raise SystemExit("Usage: python measure-download.py VIDEO_ID storage.json NEW_DIRECTORY PROFILE CLIENT_REGION [STATE_DIRECTORY]")
video, storage, directory, profile, region = sys.argv[1:6]
binary = shutil.which("flashdata")
if not binary or not Path(storage).is_file():
raise SystemExit("Install flashdata on PATH and create the private storage.json first")
folder = Path(directory)
try:
folder.mkdir(mode=0o700)
except FileExistsError:
raise SystemExit("Sample directory already exists; inspect timing.json and recover its run_id.")
report = {"run_id": "perf-" + uuid.uuid4().hex, "profile": profile,
"started_at": datetime.now(timezone.utc).isoformat(),
"source": "youtube_download", "video_id": video, "output_format": "mp3",
"region": region, "metric": "cli_start_to_result_saved",
"timeout_seconds": 600, "elapsed_seconds": None, "outcome": "unknown"}
timing = folder / "timing.json"
timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
print("Saved run_id in " + str(timing), flush=True)
command = [binary, "youtube", "download", video, "--format", "mp3",
"--storage-config", str(Path(storage).resolve()), "--mode", "async", "--wait",
"--run-id", report["run_id"], "--output", str(folder / "delivery.json"),
"--profile", profile, "--timeout", "10m", "--json", "--non-interactive"]
if len(sys.argv) == 7:
report["state_directory"] = str(Path(sys.argv[6]).resolve())
command.extend(["--state-dir", report["state_directory"]])
timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
environment = dict(os.environ)
environment.pop("FLASHDATA_API_KEY", None) # Reuse the named profile's stored key.
start = time.perf_counter()
with (folder / "cli.json").open("wb") as output, (folder / "cli-error.json").open("wb") as errors:
try:
completed = subprocess.run(command, env=environment, stdout=output, stderr=errors,
timeout=620, check=False)
report["exit_code"] = completed.returncode
report["outcome"] = "completed" if completed.returncode == 0 else "not_completed"
except (OSError, subprocess.TimeoutExpired):
report["error"] = "process_error_or_timeout"
report["elapsed_seconds"] = time.perf_counter() - start
timing.write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps(report, indent=2))
raise SystemExit(0 if report["outcome"] == "completed" else 1)اجري عملية واحدة
إستبدلوا البحث بإسمك المنقذ واسم العميل في منطقة الآلة الفيديو ID يمكن استبداله مع واحد يمكنك تجهيزه. A completed run saves download-01/delivery.json, timing.json and CLI output files.
القيادة تستخدم CLIدليل الدولة الافتراضي. إذا كان ملفك يستعمل دليل تقليدي، يذيع طريقه كآخر حجة، بعد تنظيم العملاء.
python measure-download.py jNQXAC9IVRw storage.json download-01 research client-region
python -m json.tool download-01/timing.jsonحساب الناتج من النتائج المنقذة
احفظ throughput.py داخل flashdata-benchmark/ بجانب measure-download.py. يقرأ السكربت سجل التسليم المكتمل والمؤقّت من download-01/ دون إرسال طلبات. معدل النقل هو مجموع قيم file_size لملفات الوسائط مقسومًا على elapsed_seconds؛ ويُحسب Mbps بالصيغة: البايتات × 8 ÷ الثواني ÷ 1,000,000.
import json
import math
import sys
from pathlib import Path
if len(sys.argv) != 2:
raise SystemExit("Usage: python throughput.py SAMPLE_DIRECTORY")
folder = Path(sys.argv[1])
timing = json.loads((folder / "timing.json").read_text(encoding="utf-8"))
if not isinstance(timing, dict) or timing.get("outcome") != "completed" \
or timing.get("metric") != "cli_start_to_result_saved":
raise SystemExit("Use a completed sample from measure-download.py")
elapsed = timing.get("elapsed_seconds")
if type(elapsed) not in (int, float) or not math.isfinite(elapsed) or elapsed <= 0:
raise SystemExit("Missing or invalid elapsed_seconds")
result = json.loads((folder / "delivery.json").read_text(encoding="utf-8-sig"))
if not isinstance(result, dict) or result.get("status") not in ("done", "completed") \
or result.get("source") != "youtube_download":
raise SystemExit("Use the completed download result, not a submission or job-status response")
files = result.get("results")
if not isinstance(files, list) or not files or any(not isinstance(item, dict) for item in files):
raise SystemExit("No delivered media records")
sizes = [item.get("file_size") for item in files]
if any(type(size) not in (int, float) or not math.isfinite(size) or size <= 0 for size in sizes):
raise SystemExit("Missing or invalid media file_size")
total = sum(sizes)
print(json.dumps({"run_id": timing["run_id"], "metric": timing["metric"],
"delivered_media_bytes": total, "elapsed_seconds": elapsed,
"bytes_per_second": total / elapsed, "megabits_per_second": total * 8 / elapsed / 1_000_000}, indent=2))python throughput.py download-01إذا لم يكن التسليم هو finish
اقرأ download-01/cli-error.json وrun_id داخل timing.json. استخدم runs show وruns recover مع ذلك المعرّف والملف الشخصي الأصلي. تسترجع الاستعادة المهمة المقبولة؛ استبعد هذه المحاولة من ملخصات معدل النقل المكتمل بدل إعادة تشغيل المؤقّت أو إرسال تنزيل آخر.
python -m json.tool download-01/timing.json
python -c "from pathlib import Path; print(Path('download-01/cli-error.json').read_text(encoding='utf-8'))"تقرير عن مجموعة Bulk
اجمع file_size لسجلات الوسائط المكتملة واقسمه على إجمالي الثواني المنقضية للمجموعة. سجّل أيضًا أعداد العناصر المقبولة والمكتملة والفاشلة وفاصل الاستطلاع والتوقفات. احتفظ بمعرّفات المصادر وخيارات الإخراج ومنطقة الوجهة مع التقرير. استرجاع الوسائط من البكت قياس منفصل.