Ga naar de inhoud
NL
API-sleutel ophalen
Documentatie bekijken

Handleidingen

Meet API latency en download doorvoer

Voer een gemeten zoekopdracht uit, vat opgeslagen monsters samen, of tijdmedialevering aan uw opslagruimte.

Op deze pagina

Kies de meting

MetrischStart → finish
ZoekresponstijdStart de HTTP aanvraag → lees de volledige body. Stappen gebruiken 1–3 beneden.
Doorvoer van medialeveringGeleverd media bytes ›› CLI start-to-result seconden. Inclusief toegangscontroles, indiening, peiling en resultaatexport.
Async API timingsRecord acceptatie (verzoek → taak ID) gescheiden van voltooiing (verzoek → voltooide status). Gebruik de async workflow en behoud het peilingsinterval.

1. Een zoekmonster voorbereiden

Gebruik Python 3.10+ en een sleutel met google_search-permissie in FLASHDATA_API_KEY. Er zijn geen extra Python-pakketten nodig. Gebruik python3 in plaats van python als dat je tolknaam is.

Een werkmap aanmaken. Sla alle scripts hieronder op in deze map en voer hun commando's hier uit. Elke nieuwe zoeksteekproef stuurt een query zonder automatische retrieves; normale query pricing is van toepassing.

Terminal · maak de werkmap aan
mkdir flashdata-benchmark
cd flashdata-benchmark
python --version

Het verzoek opslaan

Sla dit op als request.json binnen flashdata-benchmark/.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}

2. Time het volledige antwoord

Bewaar measure.py naast request.json. Het kopieert het verzoek in een nieuwe sample map, dan registreert de volledige responstijd, HTTP status, vraag ID en Retry-After wanneer teruggekeerd. Socket operaties gebruiken een 120-second timeout. Een bestaande sample map stopt de uitvoering voordat u een verzoek verstuurt.

measure.py
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)

Uitvoeren en inspecteren

Vervang client-regio door de regio van uw klantmachine, zoals eu-west-1. Voer het eerste commando één keer uit; het tweede commando leest alleen de opgeslagen timing.

Een zoekopdracht, dan een lokale lees
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.json

Controleer de opgeslagen bestanden

Succes eindigt met code 0 en registreert http_status: 200 en outcome: completed. De response body heeft status: done en een resultaat array. mislukte of onbekende uitgangen met code 1; inspecteer de bestanden voordat u een andere query beslist.

BestandWat te controleren
sample-01/request.jsonDe exacte invoer opgeslagen voor de indiening.
sample-01/response.jsonRaw response body; een HTTP fout kan niet-JSON inhoud teruggeven.
sample-01/timing.jsonelapsed_ms, resultaat, http_status, request_id en retry_after. Een null elapsed_ms betekent dat het proces geen finish opname heeft gemaakt.

3. Samengevat opgeslagen monsters

Bewaar summarize.py naast measure.py. Het leest lokale samples en verwerpt dubbele mappen, onvolledige timings en niet-gematchte verzoekeninstellingen, client regio of Python versie.

p50/p95 gebruikt de dichtstbijzijnde subcategorieën van voltooide responsen. Mislukte en onbekende pogingen blijven in de totalen. Een succesvol monster geeft dezelfde p50 en p95; geen succesvolle samples geeft null voor beide.

summarize.py
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))
Lees het eerste monster
python summarize.py sample-01

Samples opzettelijk toevoegen

Het eerste commando hieronder stuurt nog een zoekopdracht. Houd dezelfde client-regio waarde en verzoeken instellingen. Voor het meten van gevarieerde inputs, alleen query wijzigen in request.json voordat u het uitvoert. Het rapport labelt het invoerpatroon en telt verschillende inputs.

Voor een agent-run evaluatie, overeenstemming over een steekproef tellen en krediet budget eerst. Voer samples achtereenvolgens uit; dit voorbeeld registreert concurrency: 1. Sla de samenvatting op met de sample mappen.

Een extra zoekopdracht
python measure.py request.json sample-02 client-region
Combineer opgeslagen monsters · geen nieuwe verzoeken
python summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.json

Meet de medialevering met de CLI

Dit aparte voorbeeld levert een MP3 aan uw opslag. Installeer de CLI, gebruik een opgeslagen eigenaarsprofiel met youtube_download-permissie en houd de status directory beschikbaar. De timer gebruikt dat profiel en negeert FLASHDATA_API_KEY. Normale downloadprijs is van toepassing.

In flashdata-benchmark/, sla uw bestemming op als een privé storage.json. Dit S3 voorbeeld heeft uw emmer, regio en opslaggegevens nodig; gebruik uw bestaande privé-bestand als u er al een heeft.

storage.json
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}

Bespaar de levertijd

Bewaar measure-download.py naast storage.json. Het bespaart een nieuwe run ID voordat u de CLI start, wacht tot 10 minuten voor het commando, en registreert verstreken tijd door resultaat export. Het hergebruik van een sample map stopt voordat de CLI wordt gestart.

measure-download.py
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)

Een levering uitvoeren

Vervang onderzoek door uw opgeslagen profielnaam en client-regio met de regio van deze machine. De video ID kan worden vervangen door een die u kunt verwerken. Een voltooide run slaat download-01/delivery.json, timing.json en CLI uitvoerbestanden op.

Het commando gebruikt de standaard statusmap van de CLI. Als uw profiel een aangepaste map gebruikt, voeg dan het pad toe als laatste argument, na client-regio.

Eén MP3-levering
python measure-download.py jNQXAC9IVRw storage.json download-01 research client-region
python -m json.tool download-01/timing.json

Bereken de doorvoer van opgeslagen resultaten

Bewaar throughput.py in flashdata-benchmark/, naast measure-download.py. Het leest de voltooide levering en timer van download-01 / zonder het verzenden van verzoeken. Doorvoer is de som van media file_size-waarden gedeeld door elapsed_seconds; Mbps gebruikt bytes × 8 Secundaire seconden 1,000,000.

throughput.py
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))
Lees de opgeslagen meting
python throughput.py download-01

Als de levering niet finish

Lees download-01/cli-error.json en de run_id in timing.json. Gebruik runs show en runs recover met dat ID en het oorspronkelijke profiel. Herstel haalt de geaccepteerde taak terug; houd deze poging uit complete-throughput samenvattingen in plaats van het herstarten van de timer of het indienen van een andere download.

Controleer de opgeslagen poging · lokale leesteksten
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'))"

Rapporteer een Bulk-verzameling

Sum file_size voor voltooide mediarecords en delen door de totale verstreken seconden van de collectie. Ook opnemen geaccepteerd, voltooid en mislukte tellingen, peiling interval en pauzes. Houd bron IDs, uitvoeropties en bestemmingsregio met het rapport. Media retrieval uit uw emmer is een aparte meting.