# Meça a latência do API e baixe o rendimento

Faça uma busca, resumir amostras salvas, ou entrega de mídia no seu armazenamento.

Referência canônica: https://flashdata.dev/pt/docs/guides/performance
2026-11-05 por FlashData

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

## Escolha a medida

| Metric | Começar → terminar |
| --- | --- |
| Tempo de busca de resposta | Comece o pedido HTTP → leia o corpo completo. Use os passos 1–3. |
| Produção de mídia | bytes de mídia entregues CLI de início a resultado segundos. Inclui verificação de acesso, submissão, votação e exportação de resultados. |
| Async API cronologia | Aceitação do registro (pedido → trabalho ID) separadamente da conclusão (pedido → status completado). Use o fluxo de trabalho assincronizado e mantenha seu intervalo de votação. |

- [Meça uma busca](https://flashdata.dev/pt/docs/guides/performance/reference.md#method)
- [Meça a entrega da mídia](https://flashdata.dev/pt/docs/guides/performance/reference.md#download)
- [Async API](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#async)

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

## 1. Prepare uma amostra de busca

Use Python 3.10+ e uma chave com permissão google_search em FLASHDATA_API_KEY. Nenhum pacote Python extra é necessário. Use python3 em vez de python se esse é o seu nome de intérprete.

Crie uma pasta de trabalho. Guarde todos os scripts abaixo nesta pasta e execute seus comandos aqui. Cada nova amostra de busca envia uma consulta sem repetições automáticas, o preço normal da consulta se aplica.

### Terminal · crie a pasta de trabalho

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

- [Defina uma chave API](https://flashdata.dev/pt/docs/guides/http-quickstart/reference.md#prepare)
- [Verifique os créditos e o custo do pedido](https://flashdata.dev/pt/docs/guides/credits-and-billing/reference.md)

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

### Guarde o pedido

Guarde isso como request.json dentro flashdata-benchmark/.

#### request.json

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


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

## 2. Meça o tempo da resposta completa

Salve measure.py ao lado de request.json. Ele copia o pedido em uma nova pasta de amostras, então registra o tempo de resposta completo, status HTTP, peça ID e Retry-After quando retornado. Operações de soquete usam um intervalo de segundos 120. Uma pasta de exemplo existente para a execução antes de enviar um pedido.

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

### Corra e inspecione

Substitua a região do cliente pela região da máquina do seu cliente, como eu-west-1. Execute o primeiro comando uma vez, o segundo comando só lê o tempo salvo.

#### Uma busca, depois uma leitura local

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


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

### Verifique os arquivos salvos

O sucesso sai com o código 0 e registra http_status: 200 e outcome: completed. O corpo de resposta tem status: done e uma matriz de resultados. saídas falhadas ou desconhecidas com código 1; inspecione os arquivos antes de decidir sobre outra consulta.

| Arquivo | O que verificar? |
| --- | --- |
| sample-01/request.json | A entrada exata salva antes da submissão. |
| sample-01/response.json | Um erro HTTP pode retornar conteúdo não JSON. |
| sample-01/timing.json | elapsed_ms, resultado, http_status, request_id e retry_after. Um null elapsed_ms significa que o processo não gravou finish. |

- [Inspecione erros sem outra consulta](https://flashdata.dev/pt/docs/errors/reference.md#diagnostics)

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

## 3. Resumir amostras salvas

Salve summarize.py ao lado de measure.py. Ele lê amostras locais e rejeita pastas duplicadas, timings incompletos e configurações de solicitação desiguais, região do cliente ou versão Python.

p50/p95 usa percentis de classificação mais próximos de respostas completas. Falhadas e tentativas desconhecidas permanecem no total. Uma amostra bem-sucedida dá o mesmo p50 e p95; nenhuma amostra bem-sucedida dá null para ambos.

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

### Leia a primeira amostra

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


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

### Adicione amostras deliberadamente

O primeiro comando abaixo envia mais uma busca. Mantenha o mesmo valor de cliente-região e ajuste de solicitação. Para medir entradas variadas, mude apenas a consulta em request.json antes de executá-la. O relatório rotula o padrão de entrada e conta entradas distintas.

Para uma avaliação de agente, concorde em uma contagem de amostra e orçamento de crédito primeiro. Correr amostras sequencialmente, este exemplo registra a concordância: 1. Guarde o resumo com as pastas de amostras.

#### Uma busca adicional

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

#### Combine amostras salvas sem novos pedidos

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


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

## Meça a entrega da mídia com o CLI

Este exemplo separado fornece um MP3 para o seu armazenamento. Instale o CLI, use um perfil de proprietário salvo com permissão youtube_download, e mantenha seu diretório de estado disponível. O temporizador reutiliza esse perfil e ignora FLASHDATA_API_KEY. O preço normal de download se aplica.

Em flashdata-benchmark/, salve seu destino como um storage.json privado. Este exemplo S3 precisa de seu balde, região e credenciais de armazenamento; use seu arquivo privado existente se você já tiver um.

### storage.json

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

- [Instalação e autenticação CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md)
- [Proteja storage.json em seu OS](https://flashdata.dev/pt/docs/guides/cli-automation/reference.md#storage)
- [Outros fornecedores de armazenamento](https://flashdata.dev/pt/docs/sources/youtube_download/reference.md#storage)

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

### Economize o temporizador de entrega

Salve measure-download.py ao lado de storage.json. Salva uma nova corrida ID antes de iniciar o CLI, espera até 10 minutos para o comando, e registra o tempo decorrido através da exportação de resultados. Reutilizar uma pasta de amostras para antes de lançar o 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>

### Faça uma entrega

Substitua a pesquisa por seu nome de perfil salvo e região cliente pela região desta máquina. O vídeo ID pode ser substituído por um que você pode processar. Uma execução completa salva arquivos download-01/delivery.json, timing.json e CLI.

O comando usa o diretório padrão do CLI. Se o seu perfil usa um diretório personalizado, acrescente seu caminho como o último argumento, após a região cliente.

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

## Calcule o rendimento dos resultados salvos

Salve throughput.py em flashdata-benchmark/, ao lado de measure-download.py. Ele lê a entrega completa e o temporizador de download-01/ sem enviar pedidos. O rendimento é a soma dos valores da mídia file_size dividido por elapsed_seconds; Mbps usa bytes × 8 segundos 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))
```

### Leia a medida salva

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

- [Verifique a mídia entregue](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md#verify-media)

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

### Se a entrega não terminou

Leia download-01/cli-error.json e run_id em timing.json. Use runs show e runs recover com esse ID e o perfil original. A recuperação recupera o trabalho aceito, mantém essa tentativa fora de resumos de produção completa em vez de reiniciar o temporizador ou enviar outro download.

#### Inspecione a tentativa salva de leitura local

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

- [Recupere uma corrida CLI aceita](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md#recover)

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

### Reporte uma coleção Bulk

Sum file_size para registros de mídia completos e dividir pelo total de segundos decorridos da coleção. Registro aceito, concluído e reprovado, intervalo de votação e pausas. Mantenha a fonte IDs, opções de saída e região de destino com o relatório. A recuperação de mídia do seu balde é uma medida separada.

- [Leia resultados Bulk e contadores](https://flashdata.dev/pt/docs/guides/bulk/reference.md#results)
