> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Rede

> Leia analytics de borda, erros, logs de requisições e desempenho de uma aplicação web, verifique o DNS, configure um domínio personalizado e limpe o cache com client.apps.network.

`client.apps.network` funciona **apenas com aplicações web**. Todo método recebe o id da aplicação primeiro.

## Janelas de tempo

`analytics`, `errors`, `logs` e `performance` recebem um `start` e um `end`, cada um uma string ISO 8601 ou um `datetime`. Um `datetime` naive é horário local, convertido para UTC. Uma janela tem no máximo **7 dias**, e `start` é limitado à data de criação da aplicação. Uma janela inválida resulta em 400 `INVALID_TIME_RANGE`.

```python theme={"system"}
from datetime import UTC, datetime, timedelta

end = datetime.now(UTC)
start = end - timedelta(hours=24)  # last 24 h
```

Os resultados ficam em cache em intervalos de 5 minutos. Os cache misses desses quatro métodos compartilham um limite de 20 requisições a cada 60 segundos por conta: ultrapassá-lo resulta em 429 `RATE_LIMITED`.

## Analytics

`network.analytics(app_id, start, end, **filters)` retorna os totais de tráfego e seus detalhamentos. Retorna `None` para uma janela sem tráfego.

```python theme={"system"}
analytics = client.apps.network.analytics(app_id, start, end)

if analytics:
    print(analytics["visits"])     # [{'visits', 'requests', 'bytes', 'date'}]
    print(analytics["countries"])  # [{'type': 'BR', 'visits', 'requests', 'bytes'}]
```

Os detalhamentos são `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` e `content_types`. Cada grupo tem `type`, `visits`, `requests` e `bytes`.

### Filtros

Os filtros são argumentos nomeados e restringem todos os detalhamentos. Cada um recebe o valor exato de `type` do seu detalhamento:

```python theme={"system"}
brazil = client.apps.network.analytics(
    app_id,
    start,
    end,
    country="BR",
    path="/api",
    provider="GOOGLE (15169)",
)
```

| Filtro                             | Exemplo                                        |
| ---------------------------------- | ---------------------------------------------- |
| `country`                          | `"BR"` (código de 2 letras)                    |
| `ip`                               | `"203.0.113.7"`                                |
| `path`                             | `"/api"` (prefixo de caminho)                  |
| `status`                           | `"404"`                                        |
| `os`, `browser`, `protocol`, `bot` | O `type` do detalhamento                       |
| `referer`                          | `"Direct"` significa sem referer               |
| `provider`                         | `"NAME (ASN)"`, por exemplo `"GOOGLE (15169)"` |
| `content_type`                     | O `type` do detalhamento                       |

Um filtro inválido resulta em 400 `INVALID_FILTER`. Um filtro definido como `None` ou `''` não é enviado.

## Erros

`network.errors(app_id, start, end, include_4xx=False)` retorna as respostas 5xx da janela, além das 4xx com `include_4xx=True` (keyword-only). Retorna `None` para uma janela vazia.

```python theme={"system"}
errors = client.apps.network.errors(app_id, start, end, include_4xx=True)

if errors:
    print(errors["summary"]["total"], errors["summary"]["by_class"])
    print(errors["top_paths"])
```

## Logs de requisições

`network.logs(app_id, start, end)` retorna requisições individuais com detalhes do cliente, da requisição e da resposta. Disponível nos planos Pro e Enterprise (caso contrário, 403 `UPGRADE_REQUIRED`).

```python theme={"system"}
for log in client.apps.network.logs(app_id, start, end):
    print(log["timestamp"], log["request"]["method"], log["request"]["path"], log["response"]["status"])
```

## Desempenho

`network.performance(app_id, start, end)` retorna percentis de latência (`p50`, `p95`, `p99`, em ms) na borda e na origem, por país, por localização e para os caminhos mais lentos. Retorna `None` para uma janela vazia. Disponível nos planos Pro e Enterprise.

```python theme={"system"}
performance = client.apps.network.performance(app_id, start, end)

if performance:
    print(performance["summary"]["edge"]["p95"], performance["summary"]["origin"]["p95"])
```

## DNS

`network.dns(app_id)` retorna os registros DNS de que seu domínio personalizado precisa, com seus status. Sem um domínio personalizado, resulta em 400 `NO_CUSTOM_DOMAIN`.

```python theme={"system"}
for record in client.apps.network.dns(app_id):
    print(record["type"], record["name"], record["value"], record["status"])  # type: "txt" | "cname"
```

## Domínio personalizado

`network.set_domain(app_id, domain)` associa um domínio personalizado (plano Standard ou superior). Passe `"@"` para removê-lo.

```python theme={"system"}
client.apps.network.set_domain(app_id, "www.example.com")

# Remove it
client.apps.network.set_domain(app_id, "@")
```

| Status | Código                        | Quando                                                     |
| ------ | ----------------------------- | ---------------------------------------------------------- |
| 400    | `INVALID_DOMAIN`              | Não é um nome de domínio válido                            |
| 400    | `RESERVED_DOMAIN`             | Um domínio da Square Cloud                                 |
| 403    | `UPGRADE_REQUIRED`            | O plano não tem domínios personalizados                    |
| 403    | `LOAD_BALANCER_LIMIT_REACHED` | O limite de aplicações do plano neste domínio foi atingido |
| 409    | `DOMAIN_ALREADY_EXISTS`       | O domínio pertence a uma aplicação de outra conta          |
| 502    | `DNS_FAILED`                  | O provedor de borda recusou o domínio                      |

## Limpando o cache

`network.purge_cache(app_id)` limpa o cache de borda da aplicação. É limitado a uma limpeza a cada 60 segundos (429 `KEEP_CALM`).

```python theme={"system"}
client.apps.network.purge_cache(app_id)
```

## Erros dos métodos de analytics

| Status | Código                                                                               | Quando                                                                      |
| ------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| 400    | `INVALID_TIME_RANGE`                                                                 | `start`/`end` ausente, malformado ou invertido                              |
| 400    | `INVALID_FILTER`                                                                     | Um filtro não corresponde ao seu formato (`analytics`)                      |
| 403    | `UPGRADE_REQUIRED`                                                                   | `logs` e `performance` fora dos planos Pro e Enterprise                     |
| 429    | `RATE_LIMITED`                                                                       | Limite compartilhado de cache misses atingido                               |
| 500    | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | O provedor de borda falhou                                                  |
| 503    | `ANALYTICS_BUSY`                                                                     | Os analytics de borda estão ocupados: tentado novamente de forma automática |