From 2d7a59507606edda6158007c06d3b9addfa20d94 Mon Sep 17 00:00:00 2001 From: Paulo Ponciano Date: Fri, 21 Nov 2025 11:20:39 -0300 Subject: [PATCH] [pt-br] Update concepts/cluster-administration/system-metrics.md --- .../cluster-administration/system-metrics.md | 133 ++++++++++++------ 1 file changed, 92 insertions(+), 41 deletions(-) diff --git a/content/pt-br/docs/concepts/cluster-administration/system-metrics.md b/content/pt-br/docs/concepts/cluster-administration/system-metrics.md index 0208eaff85786..c6d39b3924609 100644 --- a/content/pt-br/docs/concepts/cluster-administration/system-metrics.md +++ b/content/pt-br/docs/concepts/cluster-administration/system-metrics.md @@ -1,7 +1,7 @@ --- -title: Métricas para componentes do sistema Kubernetes +title: Métricas para Componentes do Sistema Kubernetes content_type: concept -weight: 60 +weight: 70 --- @@ -14,7 +14,7 @@ Componentes do Kubernetes emitem métricas no [formato Prometheus](https://prome ## Métricas no Kubernetes -Na maioria dos casos, as métricas estão disponíveis no _endpoint_ `/metrics` do servidor HTTP. Para componentes que não expõem o _endpoint_ por padrão, ele pode ser ativado usando a _flag_ `--bind-address`. +Na maioria dos casos, as métricas estão disponíveis no endpoint `/metrics` do servidor HTTP. Para componentes que não expõem o endpoint por padrão, ele pode ser ativado usando a flag `--bind-address`. Exemplos desses componentes: @@ -26,9 +26,9 @@ Exemplos desses componentes: Em um ambiente de produção, você pode querer configurar o [Servidor Prometheus](https://prometheus.io/) ou algum outro coletor de métricas e disponibilizá-las em algum tipo de banco de dados temporais. -Observe que o {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} também expõe métricas nos _endpoints_ `/metrics/cadvisor`, `/metrics/resource` e `/metrics/probes`. Essas métricas não possuem o mesmo ciclo de vida. +Observe que o {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} também expõe métricas nos endpoints `/metrics/cadvisor`, `/metrics/resource` e `/metrics/probes`. Essas métricas não possuem o mesmo ciclo de vida. -Se o seu _cluster_ usa {{< glossary_tooltip term_id="rbac" text="RBAC" >}}, ler as métricas requer autorização por meio de um usuário, grupo ou _ServiceAccount_ com um _ClusterRole_ que conceda o acesso ao `/metrics`. +Se o seu cluster usa {{< glossary_tooltip term_id="rbac" text="RBAC" >}}, ler as métricas requer autorização por meio de um usuário, grupo ou ServiceAccount com um ClusterRole que conceda o acesso ao `/metrics`. Por exemplo: @@ -46,10 +46,12 @@ rules: ## Ciclo de vida da métrica -Métrica alfa → Métrica estável → Métrica ultrapassada → Métrica oculta → Métrica excluída +Métrica alfa → Métrica beta → Métrica estável → Métrica ultrapassada → Métrica oculta → Métrica excluída A métrica alfa não tem garantias de estabilidade. Essas métricas podem ser modificadas ou deletadas a qualquer momento. +Métricas beta seguem um contrato de API menos rígido do que suas contrapartes estáveis. Nenhum rótulo pode ser removido de métricas beta durante sua vida útil, no entanto, rótulos podem ser adicionados enquanto a métrica estiver no estágio beta. + Métricas estáveis possuem a garantia de que não serão alteradas. Isso significa: - Uma métrica estável sem uma assinatura ultrapassada não será deletada ou renomeada @@ -76,7 +78,13 @@ Por exemplo: some_counter 0 ``` -Métricas ocultas não são mais publicadas para extração, mas ainda estão disponíveis para uso. Para usar uma métrica oculta, por favor consulte a seção [mostrar métricas ocultas](#mostrar-métricas-ocultas). +Métricas ocultas não são mais publicadas para extração, mas ainda estão disponíveis para uso. +Uma métrica ultrapassada se torna uma métrica oculta após um período de tempo, com base em seu nível de estabilidade: +* Métricas **ESTÁVEL** se tornam ocultas após um mínimo de 3 versões ou 9 meses, o que for mais longo. +* Métricas **BETA** se tornam ocultas após um mínimo de 1 versão ou 4 meses, o que for mais longo. +* Métricas **ALFA** podem ser ocultadas ou removidas na mesma versão em que são ultrapassadas. + +Para usar uma métrica oculta, por favor consulte a seção [mostrar métricas ocultas](#mostrar-métricas-ocultas). Métricas excluídas não estão mais disponíveis e não podem mais ser usadas. @@ -84,32 +92,21 @@ Métricas excluídas não estão mais disponíveis e não podem mais ser usadas. Como descrito anteriormente, administradores podem habilitar métricas ocultas por meio de uma _flag_ de linha de comando em um binário específico. Isso pode ser usado como uma saída de emergência para os administradores caso percam a migração das métricas ultrapassadas na última versão. -A _flag_ `show-hidden-metrics-for-version` usa uma versão para a qual você deseja mostrar métricas ultrapassadas nessa versão. A versão é expressada como x.y, onde x é a versão principal e y a versão secundária. A versão de _patch_ não é necessária mesmo que uma métrica possa ser descontinuada em uma versão de _patch_, o motivo é que a política de descontinuação de métricas é executada na versão secundária. +A _flag_ `show-hidden-metrics-for-version` usa uma versão para a qual você deseja mostrar métricas ultrapassadas nessa versão. A versão é expressada como x.y, onde x é a versão principal e y a versão secundária. A versão de patch não é necessária mesmo que uma métrica possa ser descontinuada em uma versão de patch, o motivo é que a política de descontinuação de métricas é executada na versão secundária. A _flag_ só pode usar a versão secundária anterior como seu valor. Todas as métricas ocultas no anterior serão emitidas se os administradores definirem a versão anterior como `show-hidden-metrics-for-version`. A versão muito antiga não é permitida porque viola a política de métricas ultrapassadas. -Utilize a métrica `A` como exemplo, assumindo que `A` está obsoleto em 1.n. De acordo com a política de métricas ultrapassadas, podemos chegar à seguinte conclusão: - -- Na versão `1.n`, a métrica está ultrapassada, e pode ser emitida por padrão. -- Na versão `1.n+1`, a métrica está oculta por padrão e pode ser emitida via linha de comando `show-hidden-metrics-for-version=1.n`. -- Na versão `1.n+2`, a métrica deve ser removida do código fonte. Não há mais _escape hatch_. - -Se você está atualizando da versão `1.12` para `1.13`, mas ainda depende da métrica `A` ultrapassada em `1.12`, você deve definir métricas ocultas via linha de comando: `--show-hidden-metrics=1.12` e lembre-se de remover essa dependência de métrica antes de atualizar para `1.14`. - -## Desativar métricas do _accelerator_ - -O kubelet coleta métricas do _accelerator_ por meio do cAdvisor. Para coletar essas métricas, para _accelerator_ como as GPUs NVIDIA, o kubelet mantinha uma alça aberta no driver. Isso significava que, para realizar alterações na infraestrutura (por exemplo, atualizar o _driver_), um administrador do _cluster_ precisa interromper o agente kubelet. - -A responsabilidade de colear métricas do _accelerator_ agora pertence ao fornecedor, e não ao kubelet. Os fornecedores devem providenciar um contêiner que colete métricas e as exponha ao serviço de métricas (por exemplo, Prometheus). - -O [`DisableAcceleratorUsageMetrics` _feature gate_](/docs/reference/command-line-tools-reference/feature-gates/) desabilita as métricas coletadas pelo kubelet, com uma [_timeline_ para habilitar esse recurso por padrão](https://github.com/kubernetes/enhancements/tree/411e51027db842355bd489691af897afc1a41a5e/keps/sig-node/1867-disable-accelerator-usage-metrics#graduation-criteria). +Por exemplo, vamos supor que a métrica `A` seja descontinuada na versão `1.29`. A versão na qual a métrica `A` se torna oculta depende de seu nível de estabilidade: +* Se a métrica `A` for **ALFA**, ela poderá ser ocultada na versão `1.29`. +* Se a métrica `A` for **BETA**, ela será ocultada na versão `1.30` no mínimo. Se você estiver atualizando para a versão `1.30` e ainda precisar de `A`, você deve usar a opção de linha de comando `--show-hidden-metrics-for-version=1.29`. +* Se a métrica `A` for **ESTÁVEL**, ela será ocultada na versão `1.32` no mínimo. Se você estiver atualizando para a versão `1.32` e ainda precisar de `A`, você deve usar a opção de linha de comando `--show-hidden-metrics-for-version=1.31`. ## Métricas de componentes -### Métricas do _kube-controller-manager_ +### Métricas do kube-controller-manager -As métricas do _controller manager_ fornecem informações importantes sobre o desempenho e a integridade do _controller manager_. -Essas métricas incluem métricas comuns do agente de execução da linguagem Go, tais como a quantidade de _go_routine_ e métricas específicas do _controller_, como latência de requisições etcd ou latência da _API_ dos provedores de serviços de nuvem (AWS, GCE, OpenStack), que podem ser usadas para medir a integridade de um _cluster_. +As métricas do controller manager fornecem informações importantes sobre o desempenho e a integridade do controller manager. +Essas métricas incluem métricas comuns do agente de execução da linguagem Go, tais como a quantidade de go_routine e métricas específicas do controller, como latência de requisições etcd ou latência da API dos provedores de serviços de nuvem (AWS, GCE, OpenStack), que podem ser usadas para medir a integridade de um cluster. A partir do Kubernetes 1.7, métricas detalhadas de provedores de serviços de nuvem estão disponíveis para operações de armazenamento para o GCE, AWS, Vsphere e OpenStack. Essas métricas podem ser usadas para monitorar a integridade das operações de volumes persistentes. @@ -125,42 +122,96 @@ cloudprovider_gce_api_request_duration_seconds { request = "detach_disk"} cloudprovider_gce_api_request_duration_seconds { request = "list_disk"} ``` -### Métricas do _kube-scheduler_ +### Métricas do kube-scheduler {{< feature-state for_k8s_version="v1.21" state="beta" >}} -O _scheduler_ expõe métricas opcionais que relatam os recursos solicitados e os limites desejados de todos os _pods_ em execução. Essas métricas podem ser usadas para criar _dashboards_ de planejamento de capacidade, avaliar os limites de agendamentos atuais ou históricos, identificar rapidamente cargas de trabalho que não podem ser agendadas devido à falta de recursos e comparar o uso atual com a solicitação do _pod_. +O scheduler expõe métricas opcionais que reportam os recursos solicitados e os limites desejados de todos os pods em execução. Essas métricas podem ser usadas para criar dashboards de planejamento de capacidade, avaliar os limites de agendamentos atuais ou históricos, identificar rapidamente cargas de trabalho que não podem ser agendadas devido à falta de recursos e comparar o uso atual com a solicitação do pod. -O _kube-scheduler_ identifica as requisições de [recursos e limites](/docs/concepts/configuration/manage-resources-containers/) configurado para cada _Pod_; quando uma requisição ou limite é diferente de zero o _kube-scheduler_ relata uma _timeseries_ de métricas. Essa _timeseries_ é etiquetada por: +O kube-scheduler identifica as requisições de [recursos e limites](/docs/concepts/configuration/manage-resources-containers/) configurado para cada Pod; quando uma requisição ou limite é diferente de zero o kube-scheduler relata uma timeseries de métricas. Essa timeseries é etiquetada por: -- _namespace_ -- nome do _pod_ -- o nó onde o _pod_ está programado ou uma _string_ vazia caso ainda não esteja programado +- namespace +- nome do pod +- o nó onde o pod está agendado ou uma string vazia caso ainda não esteja agendado - prioridade -- o _scheduler_ atribuído para esse _pod_ +- o scheduler atribuído para esse pod - o nome do recurso (por exemplo, `cpu`) - a unidade do recurso, se conhecida (por exemplo, `cores`) -Uma vez que o _pod_ alcança um estado de conclusão (sua `restartPolicy` está como `Never` ou `onFailure` e está na fase de `Succeeded` ou `Failed`, ou foi deletado e todos os contêineres tem um estado de terminado), a série não é mais relatada já que o _scheduler_ agora está livre para agendar a execução de outros _pods_. As duas métricas são chamadas de `kube_pod_resource_request` e `kube_pod_resource_limit`. +Uma vez que o pod alcança um estado de conclusão (sua `restartPolicy` está como `Never` ou `onFailure` e está na fase de `Succeeded` ou `Failed`, ou foi deletado e todos os contêineres tem um estado de terminado), a série não é mais relatada já que o scheduler agora está livre para agendar a execução de outros pods. As duas métricas são chamadas de `kube_pod_resource_request` e `kube_pod_resource_limit`. + +As métricas são expostas no endpoint HTTP `/metrics/resources`. Elas requerem +autorização para o endpoint `/metrics/resources`, geralmente concedida por uma +ClusterRole com o verbo `get` para a URL não-recurso `/metrics/resources`. + +No Kubernetes 1.21 você deve usar a opção +`--show-hidden-metrics-for-version=1.20` para expor essas métricas de estabilidade alfa. + +### Métricas de Pressure Stall Information (PSI) do kubelet + +{{< feature-state for_k8s_version="v1.34" state="beta" >}} + +Como uma funcionalidade beta, o Kubernetes permite que você configure o kubelet para coletar informações de +[Pressure Stall Information](https://docs.kernel.org/accounting/psi.html) +(PSI) do kernel Linux para uso de CPU, memória e I/O. +As informações são coletadas no nível de nó, Pod e contêiner. +As métricas são expostas no endpoint `/metrics/cadvisor` com os seguintes nomes: +``` +container_pressure_cpu_stalled_seconds_total +container_pressure_cpu_waiting_seconds_total +container_pressure_memory_stalled_seconds_total +container_pressure_memory_waiting_seconds_total +container_pressure_io_stalled_seconds_total +container_pressure_io_waiting_seconds_total +``` -As métricas são expostas no _endpoint_ HTTP `/metrics/resources` e requerem a mesma autorização que o _endpoint_ `/metrics` no _scheduler_. Você deve usar a _flag_ `--show-hidden-metrics-for-version=1.20` para expor essas métricas de estabilidade alfa. +Esta funcionalidade está habilitada por padrão, ao definir o [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) `KubeletPSI`. As informações também são expostas na +[API Summary](/docs/reference/instrumentation/node-metrics#psi). + +Você pode aprender como interpretar as métricas PSI em [Entender Métricas PSI](/docs/reference/instrumentation/understand-psi-metrics/). + +#### Requisitos + +Pressure Stall Information requer: + +- [Versões do kernel Linux 4.20 ou posterior](/docs/reference/node/kernel-version-requirements#requirements-psi) +- [cgroup v2](/docs/concepts/architecture/cgroups) ## Desativando métricas -Você pode desativar explicitamente as métricas via linha de comando utilizando a _flag_ `--disabled-metrics`. Isso pode ser desejado se, por exemplo, uma métrica estiver causando um problema de desempenho. A entrada é uma lista de métricas desabilitadas (ou seja, `--disabled-metrics=metric1,metric2`). +Você pode desativar explicitamente as métricas via linha de comando utilizando a flag `--disabled-metrics`. Isso pode ser desejado se, por exemplo, uma métrica estiver causando um problema de desempenho. A entrada é uma lista de métricas desabilitadas (ou seja, `--disabled-metrics=metric1,metric2`). ## Aplicação de cardinalidade de métrica -As métricas com dimensões sem limites podem causar problemas de memória nos componentes que elas instrumentam. Para limitar a utilização de recursos você pode usar a opção de linha de comando `--allow-label-value` para dinamicamente configurar uma lista de permissões de valores de _label_ para uma métrica. +As métricas com dimensões sem limites podem causar problemas de memória nos componentes que elas instrumentam. Para limitar a utilização de recursos você pode usar a opção de linha de comando `--allow-label-value` para dinamicamente configurar uma lista de permissões de valores de label para uma métrica. -No estágio alfa, a _flag_ pode receber apenas uma série de mapeamentos como lista de permissões de _labels_ para uma métrica. -Cada mapeamento tem o formato `,=` onde `` é uma lista separada por vírgulas de nomes aceitáveis para a _label_. +No estágio alfa, a flag pode receber apenas uma série de mapeamentos como lista de permissões de labels para uma métrica. +Cada mapeamento tem o formato `,=` onde `` é uma lista separada por vírgulas de nomes aceitáveis para a label. O formato geral se parece com: -`--allow-label-value ,=', ...', ,=', ...', ...`. + +``` +--allow-metric-labels ,=', ...', ,=', ...', ... +``` Por exemplo: -`--allow-label-value number_count_metric,odd_number='1,3,5', number_count_metric,even_number='2,4,6', date_gauge_metric,weekend='Saturday,Sunday'` + +```none +--allow-metric-labels number_count_metric,odd_number='1,3,5', number_count_metric,even_number='2,4,6', date_gauge_metric,weekend='Saturday,Sunday' +``` + +Além de especificar isso pela CLI, isso também pode ser feito dentro de um arquivo de configuração. Você +pode especificar o caminho para esse arquivo de configuração usando o argumento de linha de comando +`--allow-metric-labels-manifest` para um componente. Aqui está um exemplo do conteúdo desse arquivo de configuração: + +```yaml +"metric1,label2": "v1,v2,v3" +"metric2,label1": "v1,v2,v3" +``` + +Além disso, a meta-métrica `cardinality_enforcement_unexpected_categorizations_total` registra a +contagem de categorizações inesperadas durante a aplicação de cardinalidade, isto é, sempre que um valor de rótulo +é encontrado que não é permitido em relação às restrições da lista de permissões. ## {{% heading "whatsnext" %}}