# Измерить задержку API и пропускную способность загрузки

Запустите один измеренный поиск, суммируйте сохраненные образцы или доставку медиа-времени на ваше хранилище.

Каноническая ссылка: https://flashdata.dev/ru/docs/guides/performance
Разработчик: 2026-11-05 by FlashData

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

## Выберите измерение

| метрический | Оригинальное название: finish |
| --- | --- |
| Время поиска ответа | Запустите запрос HTTP → прочитайте полный текст. Используйте шаги 1–3 ниже. |
| Пропускная способность СМИ | Поставленные медиа байты ÷ CLI секунды от начала до результата. Включает проверки доступа, представление, опросы и экспорт результатов. |
| Async API тайминг | Запись приемки (запрос → работа ID) отдельно от завершения (запрос → завершенный статус). Используйте рабочий процесс асинхронизации и сохраните его интервал опроса. |

- [Измерить поиск](https://flashdata.dev/ru/docs/guides/performance/reference.md#method)
- [Меры по доставке средств массовой информации](https://flashdata.dev/ru/docs/guides/performance/reference.md#download)
- [Async API рабочий процесс](https://flashdata.dev/ru/docs/reference/realtime-and-async/reference.md#async)

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

## 1. Подготовьте образец поиска

Используйте Python 3.10+ и ключ с разрешением google_search в FLASHDATA_API_KEY. Дополнительные пакеты Python не требуются. Используйте python3 вместо python, если это ваше имя переводчика.

Создайте рабочую папку. Сохраните все сценарии ниже в этой папке и запустите их команды здесь. Каждый новый образец поиска отправляет один запрос без автоматических повторных запросов; применяется обычная цена запроса.

### Терминал · создание рабочей папки

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

- [Установите ключ API](https://flashdata.dev/ru/docs/guides/http-quickstart/reference.md#prepare)
- [Проверьте кредиты и стоимость запроса](https://flashdata.dev/ru/docs/guides/credits-and-billing/reference.md)

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

### Сохранить запрос

Сохраните это как request.json внутри flashdata-benchmark/.

#### request.json

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


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

## 2. Время полного ответа

Сохраните measure.py рядом с request.json. Он копирует запрос в новую папку с образцами, а затем записывает полное время ответа, статус HTTP, запрос ID и Retry-After при возврате. Операции сокетов используют 120-секундный тайм-аут. Существующая папка с образцом останавливает выполнение перед отправкой запроса.

### 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>

### Беги и проверяй

Замените область клиента на область вашей клиентской машины, такую как eu-west-1. Запускайте первую команду один раз, вторая команда только читает сохраненное время.

#### Один поиск, затем местное чтение

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


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

### Проверьте сохраненные файлы

Успех заканчивается с кодом 0 и записывает http_status: 200 и outcome: completed. Орган ответа имеет status: done и массив результатов. неудавшиеся или неизвестные выходы с кодом 1; проверьте файлы, прежде чем принимать решение о другом запросе.

| Файл | Что проверить |
| --- | --- |
| sample-01/request.json | Точный ввод сохранен перед отправкой. |
| sample-01/response.json | Сырой ответный орган; ошибка HTTP может возвращать содержимое, не являющееся JSON. |
| sample-01/timing.json | elapsed_ms, результат, http_status, request_id и retry_after. null elapsed_ms означает, что процесс не записывал finish. |

- [Проверка ошибок без другого запроса](https://flashdata.dev/ru/docs/errors/reference.md#diagnostics)

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

## 3. Обобщение сохраненных образцов

Сохраните summarize.py рядом с measure.py. Он считывает локальные образцы и отклоняет дубликаты папок, неполные сроки и несоответствующие настройки запроса, регион клиента или версию Python.

p50/p95 использует процентили с самым близким рангом завершенных ответов. Неудачные и неизвестные попытки остаются в общей сложности. Один успешный образец дает те же p50 и p95; ни один успешный образец не дает 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))
```

### Прочитайте первый образец

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


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

### Добавить образцы намеренно

Первая команда ниже отправляет еще один поиск. Сохраняйте те же параметры клиент-региона и настройки запроса. Чтобы измерить различные входы, измените только запрос в request.json перед его запуском. В отчете маркируется схема ввода и учитывается отдельный вход.

Для оценки агентом сначала согласуйте выборку и кредитный бюджет. Проверяйте образцы последовательно; в этом примере записывается параллель: 1. Сохраните резюме с примерными папками.

#### Дополнительный поиск

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

#### Комбинировать сохраненные образцы · никаких новых запросов

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


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

## Измерение доставки мультимедиа с помощью CLI

Этот отдельный пример доставляет один MP3 на ваше хранилище. Установите CLI, используйте сохраненный профиль владельца с разрешения youtube_download и сохраните его каталог состояния. Таймер повторно использует этот профиль и игнорирует FLASHDATA_API_KEY. Применяется стандартная цена загрузки.

В flashdata-benchmark / сохраните пункт назначения в качестве частного storage.json. В этом примере S3 нужны ваши учетные данные ведёрки, области и хранилища; используйте существующий частный файл, если он у вас уже есть.

### storage.json

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

- [Установка и аутентификация CLI](https://flashdata.dev/ru/docs/guides/flashdata-cli/reference.md)
- [Защита storage.json от OS](https://flashdata.dev/ru/docs/guides/cli-automation/reference.md#storage)
- [Другие поставщики услуг хранения](https://flashdata.dev/ru/docs/sources/youtube_download/reference.md#storage)

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

### Сохранить таймер доставки

Сохраните measure-download.py рядом с storage.json. Он сохраняет новый запуск ID перед запуском CLI, выжидает до 10 минут для команды и записывает прошедшее время через экспорт результатов. Повторное использование папки образца прекращается перед запуском 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>

### Запуск одной доставки

Замените исследование сохраненным именем профиля и клиент-областью на область этой машины. Видео ID можно заменить на одно, которое можно обработать. Завершенный запуск сохраняет файлы вывода download-01/delivery.json, timing.json и CLI.

Команда использует каталог состояния CLI по умолчанию. Если ваш профиль использует пользовательский каталог, добавьте его путь в качестве последнего аргумента после клиент-региона.

#### Одна 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>

## Расчет пропускной способности сохраненных результатов

Сохраните throughput.py в флеш-метке/, рядом с measure-download.py. Он считывает завершенную доставку и таймер с download-01/ без отправки запросов. Пропускная способность - это сумма значений file_size, деленная на elapsed_seconds; Mbps использует байты × 8 ÷ секунды ÷ 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))
```

### Прочитайте сохраненные измерения

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

- [Проверить доставленные СМИ](https://flashdata.dev/ru/docs/guides/youtube-download-guide/reference.md#verify-media)

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

### Если доставка не finish

Читайте download-01/cli-error.json и run_id в timing.json. Используйте runs show и runs recover с этим ID и исходным профилем. Восстановление извлекает принятую работу; не допускать эту попытку из сводок с завершенной пропускной способностью вместо перезапуска таймера или отправки другой загрузки.

#### Проверить сохраненную попытку - местные чтения

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

- [Восстановить принятый CLI Run](https://flashdata.dev/ru/docs/guides/agent-recovery/reference.md#recover)

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

### Отчёт о коллекции Bulk

Суммируйте file_size для заполненных медиа-записей и разделите на общие прошедшие секунды коллекции. Также записывают принятые, завершенные и неудавшиеся подсчеты, интервалы опросов и паузы. Сохраняйте источник IDs, параметры вывода и регион назначения с отчетом. Медиа-поиск из вашего ведра — это отдельное измерение.

- [Результаты и счетчики Bulk](https://flashdata.dev/ru/docs/guides/bulk/reference.md#results)
