From d50a1cd8907571b61ac45aead91e3fe4f27aed02 Mon Sep 17 00:00:00 2001 From: MarcosN Date: Thu, 26 Aug 2021 16:02:02 -0300 Subject: [PATCH 1/4] adding pt-br translation for System Logs page --- .../cluster-administration/system-logs.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 content/pt-br/docs/concepts/cluster-administration/system-logs.md diff --git a/content/pt-br/docs/concepts/cluster-administration/system-logs.md b/content/pt-br/docs/concepts/cluster-administration/system-logs.md new file mode 100644 index 0000000000..d1edb9769d --- /dev/null +++ b/content/pt-br/docs/concepts/cluster-administration/system-logs.md @@ -0,0 +1,136 @@ +--- +reviewers: +- dims +- 44past4 +title: Logs de Sistema +content_type: concept +weight: 60 +--- + + + +Logs de componentes do sistema armazenam eventos que acontecem no cluster, tornando-os muito úteis para depuração. Seu nível de detalhe pode ser ajustado para mais ou para menos. Podendo se ater por exemplo a mostrar apenas os erros que ocorrem no componente, ou chegar a mostrar cada passo de um evento. (Como acessos HTTP, mudanças no estado dos pods, ações dos controllers, ou decisões do scheduler) + + + +## Klog + +[Klog](https://github.com/kubernetes/klog) é a biblioteca de logs do Kubernetes. Responsável por gerar as mensagens de log para os componentes do sistema. +generates log messages for the Kubernetes system components. + +Para mais informações acerca da sua configruação, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/) + +Um exemplo do formato padrão dos logs da biblioteca: +``` +I1025 00:15:15.525108 1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756] +``` + +### Logs Estruturados + +{{< feature-state for_k8s_version="v1.19" state="alpha" >}} + +{{< warning >}} +A migração pro formato de logs estruturados é um processo em andamento. Nem todos os logs estão dessa forma na versão atual. Dessa forma, para realizar o parsing de arquivos de log, você também precisa lidar com logs não estruturados. + +A formatação e serialização dos logs ainda estão sujeitas a alterações. +{{< /warning>}} + +A estruturação dos logs trás uma estrutura uniforme para as mensagens de log, facilitando a extração programacional de informações. Logs estruturados podem ser armazenados e processados com menos esforço e custo. Esse formato é totalmente retrocompatível e é habilitado por padrão + +Formato dos logs estruturados:: + +```ini + "" ="" ="" ... +``` + +Exemplo: + +```ini +I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready" +``` + + +### Logs em formato JSON + +{{< feature-state for_k8s_version="v1.19" state="alpha" >}} + +{{}} +Algumas opções da biblioteca klog ainda não funcionam com o os logs em formato JSON. Para ver uma lista completa de quais são, veja a documentação da [ferramenta de linha de comando](/docs/reference/command-line-tools-reference/). + +Nem todos os logs estarão garantidamente em formato JSON (como por exemplo durante o início de processos). Se você pretender realizar um parsing dos logs, seu código deverá saber tratar também linhas que não são JSON + +O nome dos campos e a serialização JSON ainda está sujeita a mudanças. +{{< /warning >}} + +A opção `--logging-format=json` muda o formato dos logs do formato padrão da klog para JSON. Abaixo segue um exemplo de um log em formato JSON (identado): +```json +{ + "ts": 1580306777.04728, + "v": 4, + "msg": "Pod status updated", + "pod":{ + "name": "nginx-1", + "namespace": "default" + }, + "status": "ready" +} +``` + +Chaves com significados especiais: +* `ts` - Data e hora no formato Unix (obrigatório, float) +* `v` - Nível de detalhe (obrigatório, int, padrão 0) +* `err` - Mensagem de erro (opcional, string) +* `msg` - Mensagem (obrigatório, string) + +Lista dos componentes que suportam o formato JSON atualmente: +* {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} +* {{< glossary_tooltip term_id="kube-apiserver" text="kube-apiserver" >}} +* {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}} +* {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} + +### Limpeza dos Logs + +{{< feature-state for_k8s_version="v1.20" state="alpha" >}} + +{{}} +A limpeza dos logs pode causar impactos significativos na performance, sendo portanto contraindicado em produção. +{{< /warning >}} + +A opção `--experimental-logging-sanitization` habilita o filtro de limpeza dos logs. +Quando habilitado, esse filtro inspeciona todos os argumentos dos logs procurando por campos contendo dados sensíveis (como senhas, chaves e tokens). Tais campos não serão expostos nas mensagens de log. + +Lista dos componentes que suportam a limpeza de logs atualmente: +* {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} +* {{< glossary_tooltip term_id="kube-apiserver" text="kube-apiserver" >}} +* {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}} +* {{< glossary_tooltip term_id="kubelet" text="kubelet" >}} + +{{< note >}} +O filtro de limpeza dos logs não impede a exposição de dados sensíveis nos logs das aplicações em execução. +{{< /note >}} + +### Nível de detalhe dos logs + +A opção `-v` controla o nível de detalhe dos logs. Um valor maior aumenta o número de eventos registrados, começando a registrar também os eventos menos importantes. Um valor menor restringe os logs apenas aos eventos mais importantes. O valor padrão 0 registra apenas eventos críticos. + +### Localização dos Logs + +Existem dois tipos de componentes do sistema: aqueles que são executados em um container e aqueles que não são. Por exemplo: + +* O [Kubernetes scheduler](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-scheduler) e o [kube-proxy](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-proxy) são executados em um container. +* O [kubelet](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kubelet) e o [container runtime](https://kubernetes.io/pt-br/docs/concepts/overview/components/#container-runtime), como o Docker por exemplo, não são executados em containers. + +Em máquinas com systemd, o kubelet e o container runtime gravam os logs no journald. +Em outros casos, eles escrevem os logs em arquivos `.log` no diretório `/var/log`. +Já os componentes executados dentro de containers, sempre irão escrever os logs em arquivos `.log` +no diretório `/var/log`, ignorando o mecanismo padrão de log. + +De forma similar aos logs de container, os logs de componentes do sistema no diretório `/var/log` devem ser rotacionados. +Nos clusters Kubernetes criados com o script `kube-up.sh`, a rotação dos logs é configurada pela ferramenta `logrotate`. Essa ferramenta rotaciona os logs diariamente, +ou quando o tamanho do arquivo excede 100MB. + +## {{% heading "Próximos passos" %}} + +* Leia sobre [Arquitetura de Logs do Kubernetes](/pt-br/docs/concepts/cluster-administration/logging/) +* Leia sobre [Logs Estruturados](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) +* Leia sobre [Convenções sobre os níveis de logs](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md) From 9b8e046000e0d46da60592ac67ec2d6fc1b4ad28 Mon Sep 17 00:00:00 2001 From: MarcosN Date: Thu, 26 Aug 2021 16:42:44 -0300 Subject: [PATCH 2/4] improving text readability --- .../cluster-administration/system-logs.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/content/pt-br/docs/concepts/cluster-administration/system-logs.md b/content/pt-br/docs/concepts/cluster-administration/system-logs.md index d1edb9769d..ff5c0f88c7 100644 --- a/content/pt-br/docs/concepts/cluster-administration/system-logs.md +++ b/content/pt-br/docs/concepts/cluster-administration/system-logs.md @@ -9,14 +9,13 @@ weight: 60 -Logs de componentes do sistema armazenam eventos que acontecem no cluster, tornando-os muito úteis para depuração. Seu nível de detalhe pode ser ajustado para mais ou para menos. Podendo se ater por exemplo a mostrar apenas os erros que ocorrem no componente, ou chegar a mostrar cada passo de um evento. (Como acessos HTTP, mudanças no estado dos pods, ações dos controllers, ou decisões do scheduler) +Logs de componentes do sistema armazenam eventos que acontecem no cluster, sendo muito úteis para depuração. Seus níveis de detalhe podem ser ajustados para mais ou para menos. Podendo se ater, por exemplo, a mostrar apenas os erros que ocorrem no componente, ou chegando a mostrar cada passo de um evento. (Como acessos HTTP, mudanças no estado dos pods, ações dos controllers, ou decisões do scheduler) ## Klog [Klog](https://github.com/kubernetes/klog) é a biblioteca de logs do Kubernetes. Responsável por gerar as mensagens de log para os componentes do sistema. -generates log messages for the Kubernetes system components. Para mais informações acerca da sua configruação, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/) @@ -30,12 +29,12 @@ I1025 00:15:15.525108 1 httplog.go:79] GET /api/v1/namespaces/kube-system/ {{< feature-state for_k8s_version="v1.19" state="alpha" >}} {{< warning >}} -A migração pro formato de logs estruturados é um processo em andamento. Nem todos os logs estão dessa forma na versão atual. Dessa forma, para realizar o parsing de arquivos de log, você também precisa lidar com logs não estruturados. +A migração pro formato de logs estruturados é um processo em andamento. Nem todos os logs estão dessa forma na versão atual. Sendo assim, para realizar o parsing de arquivos de log, você também precisa lidar com logs não estruturados. A formatação e serialização dos logs ainda estão sujeitas a alterações. {{< /warning>}} -A estruturação dos logs trás uma estrutura uniforme para as mensagens de log, facilitando a extração programacional de informações. Logs estruturados podem ser armazenados e processados com menos esforço e custo. Esse formato é totalmente retrocompatível e é habilitado por padrão +A estruturação dos logs trás uma estrutura uniforme para as mensagens de log, facilitando a extração programacional de informações. Logs estruturados podem ser armazenados e processados com menos esforço e custo. Esse formato é totalmente retrocompatível e é habilitado por padrão. Formato dos logs estruturados:: @@ -55,14 +54,14 @@ I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod= {{< feature-state for_k8s_version="v1.19" state="alpha" >}} {{}} -Algumas opções da biblioteca klog ainda não funcionam com o os logs em formato JSON. Para ver uma lista completa de quais são, veja a documentação da [ferramenta de linha de comando](/docs/reference/command-line-tools-reference/). +Algumas opções da biblioteca klog ainda não funcionam com o os logs em formato JSON. Para ver uma lista completa de quais são estas, veja a documentação da [ferramenta de linha de comando](/docs/reference/command-line-tools-reference/). Nem todos os logs estarão garantidamente em formato JSON (como por exemplo durante o início de processos). Se você pretender realizar um parsing dos logs, seu código deverá saber tratar também linhas que não são JSON -O nome dos campos e a serialização JSON ainda está sujeita a mudanças. +O nome dos campos e a serialização JSON ainda estão sujeitos a mudanças. {{< /warning >}} -A opção `--logging-format=json` muda o formato dos logs do formato padrão da klog para JSON. Abaixo segue um exemplo de um log em formato JSON (identado): +A opção `--logging-format=json` muda o formato dos logs, do formato padrão da klog para JSON. Abaixo segue um exemplo de um log em formato JSON (identado): ```json { "ts": 1580306777.04728, @@ -93,11 +92,11 @@ Lista dos componentes que suportam o formato JSON atualmente: {{< feature-state for_k8s_version="v1.20" state="alpha" >}} {{}} -A limpeza dos logs pode causar impactos significativos na performance, sendo portanto contraindicado em produção. +A funcionalidade de limpeza dos logs pode causar impactos significativos na performance, sendo portanto contraindicada em produção. {{< /warning >}} A opção `--experimental-logging-sanitization` habilita o filtro de limpeza dos logs. -Quando habilitado, esse filtro inspeciona todos os argumentos dos logs procurando por campos contendo dados sensíveis (como senhas, chaves e tokens). Tais campos não serão expostos nas mensagens de log. +Quando habilitado, esse filtro inspeciona todos os argumentos dos logs, procurando por campos contendo dados sensíveis (como senhas, chaves e tokens). Tais campos não serão expostos nas mensagens de log. Lista dos componentes que suportam a limpeza de logs atualmente: * {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} @@ -111,7 +110,7 @@ O filtro de limpeza dos logs não impede a exposição de dados sensíveis nos l ### Nível de detalhe dos logs -A opção `-v` controla o nível de detalhe dos logs. Um valor maior aumenta o número de eventos registrados, começando a registrar também os eventos menos importantes. Um valor menor restringe os logs apenas aos eventos mais importantes. O valor padrão 0 registra apenas eventos críticos. +A opção `-v` controla o nível de detalhe dos logs. Um valor maior aumenta o número de eventos registrados, começando a registrar também os eventos menos importantes. Similarmente, um valor menor restringe os logs apenas aos eventos mais importantes. O valor padrão 0 registra apenas eventos críticos. ### Localização dos Logs @@ -126,7 +125,7 @@ Já os componentes executados dentro de containers, sempre irão escrever os log no diretório `/var/log`, ignorando o mecanismo padrão de log. De forma similar aos logs de container, os logs de componentes do sistema no diretório `/var/log` devem ser rotacionados. -Nos clusters Kubernetes criados com o script `kube-up.sh`, a rotação dos logs é configurada pela ferramenta `logrotate`. Essa ferramenta rotaciona os logs diariamente, +Nos clusters Kubernetes criados com o script `kube-up.sh`, a rotação dos logs é configurada pela ferramenta `logrotate`. Essa ferramenta rotaciona os logs diariamente ou quando o tamanho do arquivo excede 100MB. ## {{% heading "Próximos passos" %}} From aa8fb8f87143001939206f72fccaa499ec0512d2 Mon Sep 17 00:00:00 2001 From: Marcos Nery Date: Fri, 27 Aug 2021 15:48:36 -0300 Subject: [PATCH 3/4] refact: improving text readability --- .../docs/concepts/cluster-administration/system-logs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/pt-br/docs/concepts/cluster-administration/system-logs.md b/content/pt-br/docs/concepts/cluster-administration/system-logs.md index ff5c0f88c7..ceeabcbc31 100644 --- a/content/pt-br/docs/concepts/cluster-administration/system-logs.md +++ b/content/pt-br/docs/concepts/cluster-administration/system-logs.md @@ -17,7 +17,7 @@ Logs de componentes do sistema armazenam eventos que acontecem no cluster, sendo [Klog](https://github.com/kubernetes/klog) é a biblioteca de logs do Kubernetes. Responsável por gerar as mensagens de log para os componentes do sistema. -Para mais informações acerca da sua configruação, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/) +Para mais informações acerca da sua configuração, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/) Um exemplo do formato padrão dos logs da biblioteca: ``` @@ -34,9 +34,9 @@ A migração pro formato de logs estruturados é um processo em andamento. Nem t A formatação e serialização dos logs ainda estão sujeitas a alterações. {{< /warning>}} -A estruturação dos logs trás uma estrutura uniforme para as mensagens de log, facilitando a extração programacional de informações. Logs estruturados podem ser armazenados e processados com menos esforço e custo. Esse formato é totalmente retrocompatível e é habilitado por padrão. +A estruturação dos logs trás uma estrutura uniforme para as mensagens de log, permitindo a extração programática de informações. Logs estruturados podem ser armazenados e processados com menos esforço e custo. Esse formato é totalmente retrocompatível e é habilitado por padrão. -Formato dos logs estruturados:: +Formato dos logs estruturados: ```ini "" ="" ="" ... From 1b6c76745cb5dfe5bd663fc8e7b0cfae859eaeb9 Mon Sep 17 00:00:00 2001 From: Marcos Nery Date: Mon, 30 Aug 2021 03:19:28 -0300 Subject: [PATCH 4/4] refact: improving readability --- .../cluster-administration/system-logs.md | 27 +++++++++---------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/content/pt-br/docs/concepts/cluster-administration/system-logs.md b/content/pt-br/docs/concepts/cluster-administration/system-logs.md index ceeabcbc31..fb79360821 100644 --- a/content/pt-br/docs/concepts/cluster-administration/system-logs.md +++ b/content/pt-br/docs/concepts/cluster-administration/system-logs.md @@ -1,7 +1,4 @@ --- -reviewers: -- dims -- 44past4 title: Logs de Sistema content_type: concept weight: 60 @@ -9,7 +6,7 @@ weight: 60 -Logs de componentes do sistema armazenam eventos que acontecem no cluster, sendo muito úteis para depuração. Seus níveis de detalhe podem ser ajustados para mais ou para menos. Podendo se ater, por exemplo, a mostrar apenas os erros que ocorrem no componente, ou chegando a mostrar cada passo de um evento. (Como acessos HTTP, mudanças no estado dos pods, ações dos controllers, ou decisões do scheduler) +Logs de componentes do sistema armazenam eventos que acontecem no cluster, sendo muito úteis para depuração. Seus níveis de detalhe podem ser ajustados para mais ou para menos. Podendo se ater, por exemplo, a mostrar apenas os erros que ocorrem no componente, ou chegando a mostrar cada passo de um evento. (Como acessos HTTP, mudanças no estado dos pods, ações dos controllers, ou decisões do scheduler). @@ -17,7 +14,7 @@ Logs de componentes do sistema armazenam eventos que acontecem no cluster, sendo [Klog](https://github.com/kubernetes/klog) é a biblioteca de logs do Kubernetes. Responsável por gerar as mensagens de log para os componentes do sistema. -Para mais informações acerca da sua configuração, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/) +Para mais informações acerca da sua configuração, veja a documentação da [ferramenta de linha de comando](https://kubernetes.io/docs/reference/command-line-tools-reference/). Um exemplo do formato padrão dos logs da biblioteca: ``` @@ -29,7 +26,7 @@ I1025 00:15:15.525108 1 httplog.go:79] GET /api/v1/namespaces/kube-system/ {{< feature-state for_k8s_version="v1.19" state="alpha" >}} {{< warning >}} -A migração pro formato de logs estruturados é um processo em andamento. Nem todos os logs estão dessa forma na versão atual. Sendo assim, para realizar o parsing de arquivos de log, você também precisa lidar com logs não estruturados. +A migração pro formato de logs estruturados é um processo em andamento. Nem todos os logs estão dessa forma na versão atual. Sendo assim, para realizar o processamento de arquivos de log, você também precisa lidar com logs não estruturados. A formatação e serialização dos logs ainda estão sujeitas a alterações. {{< /warning>}} @@ -54,9 +51,9 @@ I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod= {{< feature-state for_k8s_version="v1.19" state="alpha" >}} {{}} -Algumas opções da biblioteca klog ainda não funcionam com o os logs em formato JSON. Para ver uma lista completa de quais são estas, veja a documentação da [ferramenta de linha de comando](/docs/reference/command-line-tools-reference/). +Algumas opções da biblioteca klog ainda não funcionam com os logs em formato JSON. Para ver uma lista completa de quais são estas, veja a documentação da [ferramenta de linha de comando](/docs/reference/command-line-tools-reference/). -Nem todos os logs estarão garantidamente em formato JSON (como por exemplo durante o início de processos). Se você pretender realizar um parsing dos logs, seu código deverá saber tratar também linhas que não são JSON +Nem todos os logs estarão garantidamente em formato JSON (como por exemplo durante o início de processos). Sendo assim, se você pretende realizar o processamento dos logs, seu código deverá saber tratar também linhas que não são JSON. O nome dos campos e a serialização JSON ainda estão sujeitos a mudanças. {{< /warning >}} @@ -114,21 +111,21 @@ A opção `-v` controla o nível de detalhe dos logs. Um valor maior aumenta o n ### Localização dos Logs -Existem dois tipos de componentes do sistema: aqueles que são executados em um container e aqueles que não são. Por exemplo: +Existem dois tipos de componentes do sistema: aqueles que são executados em um contêiner e aqueles que não são. Por exemplo: -* O [Kubernetes scheduler](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-scheduler) e o [kube-proxy](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-proxy) são executados em um container. -* O [kubelet](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kubelet) e o [container runtime](https://kubernetes.io/pt-br/docs/concepts/overview/components/#container-runtime), como o Docker por exemplo, não são executados em containers. +* O [Kubernetes scheduler](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-scheduler) e o [kube-proxy](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kube-proxy) são executados em um contêiner. +* O [kubelet](https://kubernetes.io/pt-br/docs/concepts/overview/components/#kubelet) e os [agentes de execução](https://kubernetes.io/pt-br/docs/concepts/overview/components/#container-runtime), como o Docker por exemplo, não são executados em contêineres. -Em máquinas com systemd, o kubelet e o container runtime gravam os logs no journald. +Em máquinas com systemd, o kubelet e os agentes de execução gravam os logs no journald. Em outros casos, eles escrevem os logs em arquivos `.log` no diretório `/var/log`. -Já os componentes executados dentro de containers, sempre irão escrever os logs em arquivos `.log` +Já os componentes executados dentro de contêineres, sempre irão escrever os logs em arquivos `.log` no diretório `/var/log`, ignorando o mecanismo padrão de log. -De forma similar aos logs de container, os logs de componentes do sistema no diretório `/var/log` devem ser rotacionados. +De forma similar aos logs de contêiner, os logs de componentes do sistema no diretório `/var/log` devem ser rotacionados. Nos clusters Kubernetes criados com o script `kube-up.sh`, a rotação dos logs é configurada pela ferramenta `logrotate`. Essa ferramenta rotaciona os logs diariamente ou quando o tamanho do arquivo excede 100MB. -## {{% heading "Próximos passos" %}} +## {{% heading "whatsnext" %}} * Leia sobre [Arquitetura de Logs do Kubernetes](/pt-br/docs/concepts/cluster-administration/logging/) * Leia sobre [Logs Estruturados](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging)