# Mesurer la latence API et le débit de téléchargement

Chronométrez une recherche, résumez les mesures enregistrées ou mesurez la livraison des médias vers votre stockage.

Référence canonique : https://flashdata.dev/fr/docs/guides/performance
Vérifié le 2026-11-05 par FlashData

<a id="scope"></a>

## Choisir la mesure

| Mesure | Début → fin |
| --- | --- |
| Temps de réponse d’une recherche | Démarrage de la requête HTTP → lecture du corps complet de la réponse. Suivez les étapes 1 à 3 ci-dessous. |
| Débit de livraison des médias | Octets de médias livrés ÷ secondes écoulées entre le lancement de la CLI et l’enregistrement du résultat. Inclut les vérifications d’accès, la soumission, le suivi périodique de l’état et l’export du résultat. |
| Délais de l’API asynchrone | Mesurez séparément l’acceptation (requête → identifiant de tâche) et la fin du traitement (requête → état terminé). Utilisez le workflow asynchrone et conservez son intervalle de vérification de l’état. |

- [Mesurer une recherche](https://flashdata.dev/fr/docs/guides/performance/reference.md#method)
- [Mesurer la livraison des médias](https://flashdata.dev/fr/docs/guides/performance/reference.md#download)
- [Workflow API asynchrone](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#async)

<a id="method"></a>

## 1. Préparer un échantillon de recherche

Utilisez Python 3.10+ et une clé autorisant google_search dans FLASHDATA_API_KEY. Aucun paquet Python supplémentaire n’est nécessaire. Remplacez python par python3 si votre interpréteur porte ce nom.

Créez un dossier de travail. Enregistrez-y tous les scripts ci-dessous et exécutez leurs commandes depuis ce dossier. Chaque nouvel échantillon de recherche envoie une requête, sans nouvelle tentative automatique ; la tarification habituelle s’applique.

### Terminal · créer le dossier de travail

```bash
mkdir flashdata-benchmark
cd flashdata-benchmark
python --version
```

- [Définir une clé API](https://flashdata.dev/fr/docs/guides/http-quickstart/reference.md#prepare)
- [Vérifier les crédits et le coût de la requête](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md)

<a id="request"></a>

### Enregistrer la requête

Enregistrez ce contenu dans request.json, à l’intérieur de flashdata-benchmark/.

#### request.json

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


<a id="measure"></a>

## 2. Chronométrer la réponse complète

Enregistrez measure.py à côté de request.json. Le script copie la requête dans un nouveau dossier d’échantillon, puis enregistre le temps de réponse complet, le statut HTTP, l’identifiant de requête et Retry-After lorsqu’ils sont renvoyés. Les opérations réseau utilisent un délai d’expiration de 120 secondes. Si le dossier d’échantillon existe déjà, le script s’arrête avant d’envoyer une requête.

### measure.py

```python
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)
```


<a id="run"></a>

### Exécuter et inspecter

Remplacez client-region par la région de votre machine cliente, par exemple eu-west-1. Exécutez la première commande une seule fois ; la seconde lit uniquement la mesure enregistrée.

#### Une recherche, puis une lecture locale

```bash
python measure.py request.json sample-01 client-region
python -m json.tool sample-01/timing.json
```


<a id="read-sample"></a>

### Vérifier les fichiers enregistrés

En cas de succès, le code de sortie est 0 et le script enregistre http_status: 200 et outcome: completed. Le corps de la réponse contient status: done et un tableau results. Avec failed ou unknown, le code de sortie est 1 ; examinez les fichiers avant de décider d’envoyer une autre requête.

| Fichier | Point à vérifier |
| --- | --- |
| sample-01/request.json | Les données exactes enregistrées avant la soumission. |
| sample-01/response.json | Corps brut de la réponse ; une erreur HTTP peut renvoyer un contenu autre que JSON. |
| sample-01/timing.json | elapsed_ms, outcome, http_status, request_id et retry_after. Une valeur elapsed_ms à null signifie que le processus n’a pas terminé l’enregistrement. |

- [Examiner les erreurs sans nouvelle requête](https://flashdata.dev/fr/docs/errors/reference.md#diagnostics)

<a id="report"></a>

## 3. Résumer les échantillons enregistrés

Enregistrez summarize.py à côté de measure.py. Le script lit les échantillons locaux et refuse les dossiers en double, les mesures incomplètes et les différences de paramètres de requête, de région cliente ou de version Python.

p50/p95 sont calculés sur les réponses terminées, selon la méthode des rangs les plus proches. Les tentatives échouées ou de résultat inconnu restent comptées dans les totaux. Un seul échantillon réussi donne les mêmes valeurs p50 et p95 ; sans échantillon réussi, les deux valent null.

### summarize.py

```python
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))
```

### Lire le premier échantillon

```bash
python summarize.py sample-01
```


<a id="more-samples"></a>

### Ajouter des échantillons au besoin

La première commande ci-dessous envoie une recherche supplémentaire. Conservez la même valeur client-region et les mêmes paramètres de requête. Pour mesurer des entrées variées, modifiez uniquement query dans request.json avant l’exécution. Le rapport indique le type d’entrées et compte les entrées distinctes.

Pour une évaluation exécutée par un agent, convenez d’abord du nombre d’échantillons et du budget de crédits. Exécutez les échantillons l’un après l’autre ; cet exemple enregistre concurrency: 1. Conservez le résumé avec les dossiers d’échantillons.

#### Une recherche supplémentaire

```bash
python measure.py request.json sample-02 client-region
```

#### Combiner les échantillons enregistrés · aucune nouvelle requête

```bash
python summarize.py sample-01 sample-02 > summary.json
python -m json.tool summary.json
```


<a id="download"></a>

## Mesurer la livraison des médias avec la CLI

Cet exemple distinct livre un MP3 dans votre stockage. Installez la CLI, utilisez un profil propriétaire enregistré avec l’autorisation youtube_download et conservez son répertoire d’état. Le script de mesure réutilise ce profil et ignore FLASHDATA_API_KEY. La tarification habituelle des téléchargements s’applique.

Dans flashdata-benchmark/, enregistrez votre destination dans un fichier privé storage.json. Cet exemple S3 nécessite le nom du bucket, sa région et vos identifiants de stockage ; réutilisez votre fichier privé si vous en avez déjà un.

### storage.json

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

- [Installation et authentification de la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md)
- [Protéger storage.json sur votre système](https://flashdata.dev/fr/docs/guides/cli-automation/reference.md#storage)
- [Autres fournisseurs de stockage](https://flashdata.dev/fr/docs/sources/youtube_download/reference.md#storage)

<a id="download-script"></a>

### Enregistrer le script de mesure de la livraison

Enregistrez measure-download.py à côté de storage.json. Le script enregistre un nouvel identifiant d’exécution avant de lancer la CLI, attend la commande jusqu’à 10 minutes et mesure le temps écoulé jusqu’à l’export du résultat. Si le dossier d’échantillon existe déjà, il s’arrête avant de lancer la CLI.

#### measure-download.py

```python
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)
```


<a id="download-run"></a>

### Exécuter une livraison

Remplacez research par le nom de votre profil enregistré et client-region par la région de cette machine. Vous pouvez remplacer l’identifiant vidéo par celui d’une vidéo que vous pouvez traiter. Une exécution terminée enregistre download-01/delivery.json, timing.json et les fichiers de sortie de la CLI.

La commande utilise le répertoire d’état par défaut de la CLI. Si votre profil utilise un répertoire personnalisé, ajoutez son chemin comme dernier argument, après client-region.

#### Une livraison MP3

```bash
python measure-download.py jNQXAC9IVRw storage.json download-01 research client-region
python -m json.tool download-01/timing.json
```


<a id="throughput"></a>

## Calculer le débit à partir des résultats enregistrés

Enregistrez throughput.py dans flashdata-benchmark/, à côté de measure-download.py. Il lit la livraison terminée et sa mesure dans download-01/, sans envoyer de requête. Le débit correspond à la somme des valeurs file_size des médias divisée par elapsed_seconds ; les Mbps se calculent par octets × 8 ÷ secondes ÷ 1 000 000.

### throughput.py

```python
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))
```

### Lire la mesure enregistrée

```bash
python throughput.py download-01
```

- [Vérifier les médias livrés](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md#verify-media)

<a id="download-recovery"></a>

### Si la livraison ne s’est pas terminée

Lisez download-01/cli-error.json et le champ run_id dans timing.json. Utilisez runs show et runs recover avec cet identifiant et le profil d’origine. La récupération retrouve la tâche acceptée. Excluez cette tentative des mesures de débit des exécutions terminées, sans remettre le chronomètre à zéro ni soumettre un nouveau téléchargement.

#### Inspecter la tentative enregistrée · lectures locales

```bash
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'))"
```

- [Récupérer une exécution CLI acceptée](https://flashdata.dev/fr/docs/guides/agent-recovery/reference.md#recover)

<a id="bulk"></a>

### Établir le bilan d’une collecte Bulk

Additionnez file_size pour les médias terminés et divisez cette somme par la durée totale de la collecte en secondes. Consignez aussi les nombres de tâches acceptées, terminées et échouées, l’intervalle de vérification de l’état et les pauses. Conservez les identifiants des sources, les options de sortie et la région de destination avec le rapport. La récupération des médias depuis votre bucket se mesure séparément.

- [Lire les résultats et les compteurs Bulk](https://flashdata.dev/fr/docs/guides/bulk/reference.md#results)
