> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Consultando métricas do Kubernetes
Leia métricas de node e pod do Kubernetes com a [API pública
(V2)](/api/v2/overview). Todos os endpoints autenticam com seu token pessoal de API,
têm escopo de um único `site_id` e recebem um intervalo de tempo `from`/`to`.
## Consultar métricas de node
Retorna um `NodesRow` por snapshot de node no intervalo de tempo.
```shell Endpoint theme={null}
POST /api/v2/kubernetes/nodes
```
### Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
| ----------- | ----------------- | ----------- | ------------------------------------------------------------------ |
| `site_id` | string | Sim | Site a ser consultado. |
| `from` | string (ISO 8601) | Sim | Início do intervalo de tempo (inclusivo). |
| `to` | string (ISO 8601) | Sim | Fim do intervalo de tempo (inclusivo). |
| `node_name` | string | Não | Filtrar para um único node. Uma string vazia significa sem filtro. |
```json body.json theme={null}
{
"site_id": "YOUR-SITE-ID",
"from": "2026-06-22T00:00:00Z",
"to": "2026-06-22T01:00:00Z",
"node_name": ""
}
```
### Resposta
Retorna um array de objetos `NodesRow`, um por snapshot de node. Cada um tem estes
campos:
| Campo | Tipo | Descrição |
| -------------------------- | ----------------- | ----------------------------------------- |
| `timestamp` | string (ISO 8601) | Quando o snapshot foi tirado. |
| `node_name` | string | Nome do node no Kubernetes. |
| `cpu_usage_nano_cores` | number | Uso de CPU em nanocores. |
| `memory_rss_bytes` | number | Memória resident set size (RSS) em bytes. |
| `memory_usage_bytes` | number | Uso total de memória em bytes. |
| `memory_working_set_bytes` | number | Working set de memória em bytes. |
| `memory_page_faults` | number | Contagem de page faults. |
| `memory_major_page_faults` | number | Contagem de major page faults. |
| `fs_used_bytes` | number | Espaço de filesystem usado em bytes. |
| `fs_available_bytes` | number | Espaço de filesystem disponível em bytes. |
| `fs_capacity_bytes` | number | Capacidade total do filesystem em bytes. |
| `fs_inodes_free` | number | Contagem de inodes de filesystem livres. |
| `fs_inodes_used` | number | Contagem de inodes de filesystem usados. |
| `fs_inodes` | number | Contagem total de inodes do filesystem. |
| `network_rx_bytes` | number | Bytes de rede recebidos. |
| `network_tx_bytes` | number | Bytes de rede transmitidos. |
| `phase` | number | Fase do node, como valor numérico. |
## Consultar métricas de pod
Retorna um `PodsRow` por snapshot de pod no intervalo de tempo.
```shell Endpoint theme={null}
POST /api/v2/kubernetes/pods
```
### Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | -------------------- | ----------- | ---------------------------------------------------------------------- |
| `site_id` | string | Sim | Site a ser consultado. |
| `from` | string (ISO 8601) | Sim | Início do intervalo de tempo (inclusivo). |
| `to` | string (ISO 8601) | Sim | Fim do intervalo de tempo (inclusivo). |
| `namespaces` | string\[] | Não | Filtrar para estes namespaces. Vazio significa todos os namespaces. |
| `pod_name` | string | Não | Filtrar para um único pod. Uma string vazia significa sem filtro. |
| `node_names` | string\[] | Não | Filtrar para estes nodes. Vazio significa todos os nodes. |
| `state` | `PodState` ou `null` | Não | Filtrar para um único estado de pod. Veja [estado do pod](#pod-state). |
### Resposta
Retorna um array de objetos `PodsRow`, um por snapshot de pod. Cada um tem estes
campos:
| Campo | Tipo | Descrição |
| ---------------------------------- | ----------------- | --------------------------------------------------------------- |
| `timestamp` | string (ISO 8601) | Quando o snapshot foi tirado. |
| `pod_name` | string | Nome do pod. |
| `pod_namespace` | string | Namespace do Kubernetes a que o pod pertence. |
| `node_name` | string | Nome do node em que este pod está rodando. |
| `cpu_usage_nano_cores` | number | Uso de CPU em nanocores. |
| `cpu_usage_core_nano_seconds` | number | Uso cumulativo de CPU em core-nanossegundos. |
| `memory_rss_bytes` | number | Memória resident set size (RSS) em bytes. |
| `memory_usage_bytes` | number | Uso total de memória em bytes. |
| `memory_working_set_bytes` | number | Working set de memória em bytes. |
| `memory_page_faults` | number | Contagem de page faults. |
| `memory_major_page_faults` | number | Contagem de major page faults. |
| `ephemeral_storage_used_bytes` | number | Armazenamento efêmero usado em bytes. |
| `ephemeral_storage_capacity_bytes` | number | Capacidade de armazenamento efêmero em bytes. |
| `network_rx_bytes` | number | Bytes de rede recebidos. |
| `network_tx_bytes` | number | Bytes de rede transmitidos. |
| `process_count` | number | Contagem de processos em execução. |
| `phase` | `PodPhase` | Fase atual do ciclo de vida. Veja [fase do pod](#pod-phase). |
| `state` | `PodState` | Estado derivado do pod. Veja [estado do pod](#pod-state). |
| `containers` | `Container[]` | Containers em execução neste pod. Veja [container](#container). |
| `pod_restart_count` | number | Total de restarts de containers deste pod. |
| `pod_uptime_seconds` | number | Uptime do pod em segundos. |
## Consultar visão geral de pods
Retorna metadados e status do pod em vez de métricas brutas, como um
`PodOverviewRow` por pod.
```shell Endpoint theme={null}
POST /api/v2/kubernetes/pods/overview
```
### Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | ----------------- | ----------- | ------------------------------------------------------------------- |
| `site_id` | string | Sim | Site a ser consultado. |
| `from` | string (ISO 8601) | Sim | Início do intervalo de tempo (inclusivo). |
| `to` | string (ISO 8601) | Sim | Fim do intervalo de tempo (inclusivo). |
| `namespaces` | string\[] | Não | Filtrar para estes namespaces. Vazio significa todos os namespaces. |
| `query` | string | Não | Query de busca de texto livre para filtrar pods. |
### Resposta
Retorna um array de objetos `PodOverviewRow`, um por pod. Cada um tem estes campos, todos **obrigatórios**:
| Campo | Tipo | Descrição |
| -------------------- | ------------------ | --------------------------------------------------------------------- |
| `timestamp` | string (ISO 8601) | Quando o snapshot foi tirado. |
| `node_name` | string | Nome do node em que este pod está rodando. |
| `pod_name` | string | Nome do pod. |
| `pod_namespace` | string | Namespace do Kubernetes a que o pod pertence. |
| `pod_uuid` | string | Identificador único do pod. |
| `phase` | `PodPhase` | Fase atual do ciclo de vida. Veja [fase do pod](#pod-phase). |
| `labels` | object | Labels do Kubernetes anexadas ao pod. |
| `owner_references` | `OwnerReference[]` | Owner references deste pod. Veja [owner reference](#owner-reference). |
| `containers` | `Container[]` | Containers em execução neste pod. Veja [container](#container). |
| `state` | `PodState` | Estado derivado do pod. Veja [estado do pod](#pod-state). |
| `pod_restart_count` | number | Total de restarts de containers deste pod. |
| `pod_uptime_seconds` | number | Uptime do pod em segundos. |
## Referência
### Fase do pod
`phase` é a fase do ciclo de vida do Kubernetes: `Running`, `Succeeded`, `Pending`,
`Failed` ou `Unknown`.
### Estado do pod
`state` é um estado derivado que combina fase e status de containers: `Running`,
`Succeeded`, `Pending`, `Failed` ou `Unknown`.
### Container
Cada entrada em `containers` tem um `name`, um `status` (`Running`, `Terminated`,
`Waiting` ou `Unknown`), um `exit_code` (`0` significa sucesso) e um `reason`
legível por humanos.
### Owner reference
Cada entrada em `owner_references` tem o `name`, o `kind` (como
`ReplicaSet` ou `DaemonSet`) e o `namespace` do recurso proprietário.