Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

Mide la latencia de la API y el rendimiento de las descargas

Mide una búsqueda, resume las muestras guardadas o calcula el tiempo de entrega de archivos a tu almacenamiento.

En esta página

Elija la medición

métricaInicio → acabado
Tiempo de respuesta a la búsquedaIniciar la solicitud HTTP → leer el cuerpo completo. Use los pasos 1–3 a continuación.
Media delivery throughputEntrega de bytes de medios ÷ CLI de inicio a consulta segundos. Incluye cheques de acceso, presentación, votación y exportación de resultados.
Tiempos de Async APIAceptación del registro (Solicitud → trabajo ID) separadamente de la terminación (Solicitud → estado completado). Utilice el flujo de trabajo asinc y retener su intervalo de votación.

1. Preparar una muestra de búsqueda

Utilice Python 3.10+ y una clave con permiso google_search en FLASHDATA_API_KEY. No se necesitan paquetes Python adicionales. Use python3 en lugar de python si ese es su nombre de intérprete.

Crear una carpeta de trabajo. Guardar todos los scripts abajo en esta carpeta y ejecutar sus comandos aquí. Cada nueva muestra de búsqueda envía una consulta sin registros automáticos; se aplica el precio normal de la consulta.

Terminal · crear la carpeta de trabajo
mkdir flashdata-benchmark
cd flashdata-benchmark
python --version

Guardar la solicitud

Guarda esto como request.json dentro de flashdata-benchmark/.

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

2. Hora de la respuesta completa

Guardar measure.py junto a request.json. Copia la solicitud en una nueva carpeta de muestra, luego registra el tiempo de respuesta completo, estado HTTP, solicitar ID y Retry-After cuando se devuelve. Las operaciones de bolsillo usan un timeout 120-second. Una carpeta de muestra existente detiene la ejecución antes de enviar una solicitud.

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)

Correr e inspeccionar

Reemplazar la lista de clientes con la región de su máquina cliente, como eu-west-1. Ejecutar el primer comando una vez; el segundo comando sólo lee el tiempo guardado.

Una búsqueda, luego una lectura local
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.json

Compruebe los archivos guardados

Salidas de éxito con código 0 y registros http_status: 200 y resultado: completado. El cuerpo de respuesta tiene status: done y una matriz de resultados. salidas fallidas o desconocidas con código 1; inspeccionar los archivos antes de decidir sobre otra consulta.

ArchivoQué comprobar
sample-01/request.jsonLa entrada exacta guardada antes de la presentación.
sample-01/response.jsonCuerpo de respuesta bruto; un error HTTP puede devolver contenido no JSON.
sample-01/timing.jsonelapsed_ms, resultado, http_status, request_id y retry_after. Un elapsed_ms null significa que el proceso no terminó la grabación.

3. Summarize muestras guardadas

Guarda summarize.py junto a measure.py. Lee muestras locales y rechaza carpetas duplicadas, fechas incompletas y ajustes de solicitud desatendidos, región cliente o versión Python.

p50/p95 utiliza percentiles de rango más cercano de las respuestas completadas. Los intentos fallidos y desconocidos permanecen en los totales. Una muestra exitosa da el mismo p50 y p95; ninguna muestra exitosa da null para ambos.

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))
Lea la primera muestra
python summarize.py sample-01

Añadir muestras deliberadamente

El primer comando a continuación envía una búsqueda más. Mantenga la misma configuración de valor de registro de cliente y solicitud. Para medir entradas variadas, cambiar sólo la consulta en request.json antes de ejecutarla. El informe etiqueta el patrón de entrada y cuenta entradas distintas.

Para una evaluación administrada por agentes, acuerde primero en un recuento de muestras y presupuesto de crédito. Ejecute muestras secuencialmente; este ejemplo registra concurrencia: 1. Guarda el resumen con las carpetas de muestra.

Una búsqueda adicional
python measure.py request.json sample-02 client-region
Combina muestras guardadas · no nuevas solicitudes
python summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.json

Entrega de medios de medición con CLI

Este ejemplo separado ofrece un MP3 a su almacenamiento. Instalar el CLI, utilizar un perfil de propietario guardado con el permiso youtube_download, y mantener su directorio de estado disponible. El temporizador reutiliza ese perfil e ignora FLASHDATA_API_KEY. Se aplica un precio normal de descarga.

En flashdata-benchmark/, ahorre su destino como un storage.json privado. Este ejemplo S3 necesita sus credenciales de cubo, región y almacenamiento; utilice su archivo privado existente si ya tiene uno.

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

Guardar el cronograma de entrega

Guarda measure-download.py junto a storage.json. Guarda una nueva ejecución ID antes de iniciar el CLI, espera hasta los minutos de 10 para el comando, y los registros de tiempo transcurrido a través de la exportación de resultados. Reutilizar una carpeta de muestra se detiene antes de lanzar el CLI.

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)

Ejecutar una entrega

Sustituye research por el nombre de tu perfil guardado y client-region por la región de esta máquina. Puedes cambiar el ID de vídeo por uno que puedas procesar. Una ejecución completada guarda download-01/delivery.json, timing.json y los archivos de salida de la CLI.

El comando utiliza el directorio de estado predeterminado de CLI. Si su perfil utiliza un directorio personalizado, anexa su ruta como el último argumento, después de la lista de clientes.

Entrega de un MP3
python measure-download.py jNQXAC9IVRw storage.json download-01 research client-region
python -m json.tool download-01/timing.json

Calcular la rentabilidad de los resultados salvados

Guardar throughput.py en flashdata-benchmark/, al lado measure-download.py. Lee la entrega completa y el temporizador de descarga-01/ sin enviar solicitudes. La entrada es la suma de los medios file_size valores divididos por elapsed_seconds; Mbps utiliza bytes × 8 ♫ Segundos ♫ 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))
Lea la medición guardada
python throughput.py download-01

Si la entrega no termina

Lee download-01/cli-error.json y el run_id de timing.json. Usa runs show y runs recover con ese ID y el perfil original. La recuperación consulta el trabajo aceptado. Excluye este intento de los resúmenes de rendimiento de ejecuciones completadas, en lugar de reiniciar el cronómetro o enviar otra descarga.

Inspeccione el intento salvado · lecturas locales
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'))"

Informe una colección Bulk

Sum file_size para los registros multimedia completados y dividir por el total de segundos transcurridos de la colección. También registre los conteos aceptados, completados y fallidos, intervalo de votación y pausas. Mantenga la fuente IDs, opciones de salida y región de destino con el informe. La recuperación de medios de su cubo es una medición separada.