[pt] Add /pt/docs/concepts/signals/trace.md (#5019)

Co-authored-by: Edson C. <[email protected]>
Co-authored-by: Emídio Neto <[email protected]>

Author: 3 people

content/pt/docs/concepts/signals/traces.md

@@ -0,0 +1,398 @@
+---
+title: Rastros
+weight: 1
+description: O caminho de uma solicitação através do seu aplicativo.
+default_lang_commit: 57cd4f78d61cc1642ce56089aeec7ae278544194
+---
+
+Os **rastros** nos fornecem uma visão geral do que acontece quando uma
+solicitação é feita para uma aplicação. Seja sua aplicação um monólito com um
+único banco de dados ou uma grande variedade de serviços, os rastros são
+essenciais para compreender o "caminho" completo que uma solicitação percorreu
+na sua aplicação.
+
+Vamos explorar isso com três unidades de trabalho, representadas como
+[Trechos](#spans):
+
+{{% alert title="Note" %}}
+
+Os exemplos JSON a seguir não apresentam um formato específico, especialmente o
+[OTLP/JSON](/docs/specs/otlp/#json-protobuf-encoding), que é mais verboso.
+
+{{% /alert %}}
+
+trecho `olá`:
+
+```json
+{
+  "name": "olá",
+  "context": {
+    "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
+    "span_id": "0x051581bf3cb55c13"
+  },
+  "parent_id": null,
+  "start_time": "2022-04-29T18:52:58.114201Z",
+  "end_time": "2022-04-29T18:52:58.114687Z",
+  "attributes": {
+    "http.route": "alguma_rota1"
+  },
+  "events": [
+    {
+      "name": "Guten Tag!",
+      "timestamp": "2022-04-29T18:52:58.114561Z",
+      "attributes": {
+        "event_attributes": 1
+      }
+    }
+  ]
+}
+```
+
+Este é o trecho raiz, sinalizando o início e o fim de toda a operação. Note que
+ele possui um campo `trace_id` indicando o rastro, mas não possui `parent_id`. É
+assim que você sabe que é o trecho raiz.
+
+O trecho `olá-cumprimentos`:
+
+```json
+{
+  "name": "olá-cumprimentos",
+  "context": {
+    "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
+    "span_id": "0x5fb397be34d26b51"
+  },
+  "parent_id": "0x051581bf3cb55c13",
+  "start_time": "2022-04-29T18:52:58.114304Z",
+  "end_time": "2022-04-29T22:52:58.114561Z",
+  "attributes": {
+    "http.route": "alguma_rota2"
+  },
+  "events": [
+    {
+      "name": "e aí!",
+      "timestamp": "2022-04-29T18:52:58.114561Z",
+      "attributes": {
+        "event_attributes": 1
+      }
+    },
+    {
+      "name": "até logo!",
+      "timestamp": "2022-04-29T18:52:58.114585Z",
+      "attributes": {
+        "event_attributes": 1
+      }
+    }
+  ]
+}
+```
+
+Este trecho encapsula tarefas específicas, como dizer saudações, e seu pai é o
+trecho `olá`. Note que ele compartilha o mesmo `trace_id` que o trecho raiz,
+indicando que faz parte do mesmo rastro. Além disso, ele possui um `parent_id`
+que corresponde ao `span_id` do trecho `olá`.
+
+O trecho `olá-saudações`:
+
+```json
+{
+  "name": "olá-saudações",
+  "context": {
+    "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2",
+    "span_id": "0x93564f51e1abe1c2"
+  },
+  "parent_id": "0x051581bf3cb55c13",
+  "start_time": "2022-04-29T18:52:58.114492Z",
+  "end_time": "2022-04-29T18:52:58.114631Z",
+  "attributes": {
+    "http.route": "alguma_rota3"
+  },
+  "events": [
+    {
+      "name": "olá!",
+      "timestamp": "2022-04-29T18:52:58.114561Z",
+      "attributes": {
+        "event_attributes": 1
+      }
+    }
+  ]
+}
+```
+
+Este trecho representa a terceira operação neste rastro e assim como o anterior,
+é um filho do trecho `olá`. Isso também o torna um irmão do trecho
+`olá-cumprimentos`.
+
+Esses três blocos de JSON compartilham o mesmo `trace_id`, e o campo `parent_id`
+que representa uma hierarquia. Isso o torna um rastro!
+
+Outra coisa que você notará é que cada trecho se parece com um log estruturado.
+Isso porque, de certa forma, é mesmo! Uma maneira de pensar em rastros é como
+uma coleção de logs estruturados com contexto, correlação, hierarquia e outros
+recursos. No entanto, esses "logs estruturados" podem vir de diferentes
+processos, serviços, VMs, data centers, e assim por diante. Isso torna possível
+que o rastreamento represente uma visão de ponta a ponta de qualquer sistema.
+
+Para compreender como o rastreamento no OpenTelemetry funciona, vamos analisar
+uma lista de componentes que terão um papel fundamental na instrumentação do
+nosso código.
+
+## Trace Provider
+
+Um Trace Provider (às vezes chamado de `TracerProvider`) é uma fábrica de
+`rastros`. Na maioria das aplicações, um Trace Provider é inicializado uma vez e
+seu ciclo de vida corresponde ao ciclo de vida da aplicação. A inicialização do
+Trace Provider também inclui a inicialização de Resource e Exporter. Geralmente
+é a primeira etapa do rastreamento com OpenTelemetry. Em alguns SDKs, um Trace
+Provider global já é inicializado para você.
+
+## Rastro {#tracer}
+
+Um rastro cria trechos contendo mais informações sobre o que está acontecendo em
+uma determinada operação, como uma solicitação em um serviço. Rastros são
+criados a partir de Trace Providers.
+
+## Trace Exporters
+
+Trace Exporters enviam rastros para um consumidor. Esse consumidor pode ser a
+saída padrão para depuração em tempo de desenvolvimento, o OpenTelemetry
+Collector ou qualquer backend de código aberto ou fornecedor de sua escolha.
+
+## Propagação de Contexto {#context-propagation}
+
+A propagação de contexto é o conceito central que possibilita o rastreamento
+distribuído. Com a propagação de contexto, trechos podem ser correlacionados
+entre si e montados em um rastro, independentemente de onde os trechos são
+gerados. Para saber mais sobre este tópico, consulte a página de conceitos sobre
+[Propagação de Contexto](/docs/concepts/context-propagation).
+
+## Trechos {#spans}
+
+Um **trecho** representa uma unidade de trabalho ou operação. Trechos são os
+blocos que compõem os rastros. No OpenTelemetry, eles incluem as seguintes
+informações:
+
+- Nome
+- ID do trecho pai (vazio para trecho raiz)
+- Marcação de tempo do início e fim
+- [Contexto do Trecho](#span-context)
+- [Atributos](#attributes)
+- [Eventos do Trecho](#span-events)
+- [Links do Trecho](#span-links)
+- [Estado do Trecho](#span-status)
+
+Exemplo de trecho:
+
+```json
+{
+  "name": "/v1/sys/health",
+  "context": {
+    "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
+    "span_id": "086e83747d0e381e"
+  },
+  "parent_id": "",
+  "start_time": "2021-10-22 16:04:01.209458162 +0000 UTC",
+  "end_time": "2021-10-22 16:04:01.209514132 +0000 UTC",
+  "status_code": "STATUS_CODE_OK",
+  "status_message": "",
+  "attributes": {
+    "net.transport": "IP.TCP",
+    "net.peer.ip": "172.17.0.1",
+    "net.peer.port": "51820",
+    "net.host.ip": "10.177.2.152",
+    "net.host.port": "26040",
+    "http.method": "GET",
+    "http.target": "/v1/sys/health",
+    "http.server_name": "mortar-gateway",
+    "http.route": "/v1/sys/health",
+    "http.user_agent": "Consul Health Check",
+    "http.scheme": "http",
+    "http.host": "10.177.2.152:26040",
+    "http.flavor": "1.1"
+  },
+  "events": [
+    {
+      "name": "",
+      "message": "OK",
+      "timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC"
+    }
+  ]
+}
+```
+
+Trechos podem ser aninhados, como é indicado pela presença de um ID de trecho
+pai: trechos filhos representam sub-operações. Isso permite que os trechos
+capturem de forma mais precisa o trabalho realizado em uma aplicação.
+
+### Contexto do Trecho {#span-context}
+
+O contexto do trecho é um objeto imutável em cada trecho que contém o seguinte:
+
+- O Trace ID que representando o rastro do qual o trecho faz parte
+- O Span ID do trecho
+- Trace Flags, uma codificação binária contendo informações sobre o rastro
+- Trace State, uma lista de pares chave-valor que podem carregar informações de
+  rastro específicos do fornecedor
+
+O contexto do trecho é a parte de um trecho que é serializada e propagada junto
+com a [propagação de contexto](#context-propagation) e
+[baggage](/docs/concepts/signals/baggage).
+
+Como o contexto do trecho contém o trace ID, o trace ID é usado ao criar
+[links de trechos](#span-links).
+
+### Atributos {#attributes}
+
+Atributos são pares chave-valor que contêm metadados que você pode usar para
+anotar um trecho e carregar informações sobre a operação que ele está
+acompanhando.
+
+Por exemplo, se um trecho rastreia uma operação que adiciona um item ao carrinho
+de compras de um usuário em um sistema de eCommerce, é possível obter o ID do
+usuário o ID do item a ser adicionado ao carrinho e o ID do carrinho.
+
+Você pode adicionar atributos aos trecho durante ou após a criação do trecho.
+Prefira adicionar atributos na criação do trecho para disponibilizar os
+atributos para a amostragem do SDK. Se precisar adicionar um valor após a
+criação do trecho, atualize o trecho com o valor.
+
+Os atributos têm as seguintes regras que é implementada por cada SDK:
+
+- Chaves devem ser valores de string não nulos
+- Valores devem ser uma string não nula, boolean, valor de ponto flutuante,
+  inteiro ou um array desses valores
+
+Além disso, existem [atributos semânticos](/docs/specs/semconv/general/trace/),
+que são convenções de nomenclatura conhecidas para metadados que estão
+tipicamente presentes em operações comuns. É útil usar a nomenclatura de
+atributos semânticos sempre que possível para que tipos comuns de metadados
+sejam padronizados entre sistemas.
+
+### Eventos de Trechos {#span-events}
+
+Um evento de trecho pode ser considerado como uma mensagem de log estruturada
+(ou anotação) em um trecho, tipicamente usada para apresentar um ponto
+significativo e único no tempo durante a duração do trecho.
+
+Por exemplo, considere dois cenários em um navegador web:
+
+1. Rastrear o carregamento de uma página
+2. Apontar quando uma página se torna interativa
+
+Um trecho é mais adequado para o primeiro cenário, pois é uma operação que tem
+início e fim.
+
+Um evento de trecho é mais adequado para rastrear o segundo cenário porque
+representa um ponto relevante e único na solicitação.
+
+#### Quando usar eventos de trecho versus atributos de trecho {#when-to-use-span-events-versus-span-attributes}
+
+Como eventos de trecho também contêm atributos, a questão de quando usar eventos
+em vez de atributos nem sempre tem uma resposta óbvia. Para confirmar sua
+decisão, verifique se uma data e hora específicas são relevantes para você.
+
+Por exemplo, quando você está rastreando uma operação com um trecho e a mesma é
+finalizada, você pode querer adicionar dados da operação à sua telemetria.
+
+- Se a data e hora em que a operação é finalizada for significativo ou
+  relevante, anexe os dados a um evento de trecho.
+- Se a data e hora não forem relevantes, anexe os dados como atributos de
+  trecho.
+
+### Links de Trechos {#span-links}
+
+Os links existem para que você possa associar um trecho a um ou mais trechos,
+resultando em uma relação causal. Por exemplo, imagine que temos um sistema
+distribuído onde algumas operações são rastreadas por um rastro.
+
+Em resposta a algumas dessas ações, uma operação adicional é enfileirada para
+ser executada, mas sua execução é assíncrona. Podemos rastrear essa operação
+seguinte através de um rastro.
+
+Gostaríamos de associar o rastro das operações subsequentes ao primeiro rastro,
+mas não podemos prever quando as operações subsequentes começarão. Precisamos
+associar os dois rastros, então utilizaremos um link de trecho.
+
+Você pode vincular o último trecho do primeiro rastro ao primeiro trecho do
+segundo rastro. Agora, eles estão causalmente associados entre si.
+
+Os links são opcionais, mas servem como uma boa maneira de associar trechos de
+rastro uns aos outros.
+
+### O estado do Trecho {#span-status}
+
+Cada trecho tem um estado. Os três valores possíveis são:
+
+- `Unset`
+- `Error`
+- `OK`
+
+O valor padrão é `Unset`. Um estado de trecho `Unset` significa que a operação
+rastreada foi concluída com sucesso, sem erro.
+
+Quando o estado de um trecho é `Error`, isso significa que algum erro ocorreu na
+operação rastreada. Por exemplo, isso pode ser devido a um erro de HTTP 500 em
+um servidor que está lidando com uma solicitação.
+
+Quando o estado de um trecho é `OK`, isso significa que o trecho foi
+expressamente marcado como livre de erros pelo desenvolvedor. Apesar de parecer
+contraditório, não é necessário definir o estado de um trecho como `OK` quando
+se sabe que foi concluído sem erros, pois já está implícito em `Unset`. O estado
+de `OK` representa uma "decisão final" clara sobre o estado de um trecho que foi
+explicitamente definido por um usuário. Isso é útil em qualquer situação em que
+um desenvolvedor deseje que não haja outra interpretação de um trecho além de
+"bem-sucedido".
+
+Para reiterar: `Unset` representa um trecho que foi concluído sem erro. `OK`
+representa quando um desenvolvedor marca explicitamente um trecho como
+bem-sucedido. Na maioria dos casos, não é necessário marcar explicitamente um
+trecho como OK.
+
+### Tipo de Trecho {#span-kind}
+
+Quando um trecho é criado, ele pode ser do tipo: `Client`, `Server`, `Internal`,
+`Producer` ou `Consumer`. Esse tipo de trecho indica ao backend de rastreamento
+como o rastro deve ser montado. De acordo com a especificação do OpenTelemetry,
+o trecho pai de um servidor geralmente é um trecho de cliente remoto, e o trecho
+filho de um cliente geralmente é um trecho de servidor. Da mesma forma, o trecho
+pai de um consumidor é sempre um fornecedor, e o trecho filho de um fornecedor é
+sempre um consumidor. Se o tipo de trecho não for especificado, ele será
+assumido como interno.
+
+Para mais informações sobre o tipo de Trecho, consulte
+[SpanKind](/docs/specs/otel/trace/api/#spankind).
+
+#### Client
+
+Um trecho de client representa uma chamada remota síncrona de saída, como uma
+solicitação HTTP ou uma chamada de banco de dados. Observe que, neste contexto,
+"síncrono" não se refere a operações `async/await`, mas sim ao fato de que a
+chamada não é enfileirada para processamento posterior.
+
+#### Server
+
+Um trecho de servidor representa uma chamada remota síncrona de entrada, como
+uma solicitação HTTP de entrada ou uma chamada de procedimento remoto.
+
+#### Internal
+
+Trechos internos representam operações que não atravessam uma fronteira de
+processo. Coisas como instrumentar uma chamada de função ou um Express
+middleware podem usar trechos internos.
+
+#### Producer
+
+Trechos de fornecedor representam a criação de um trabalho que pode ser
+processado de forma assíncrona mais tarde. Pode ser uma tarefa remota, como uma
+adição em uma fila de tarefas, ou uma tarefa local processada por um ouvinte de
+eventos.
+
+### Consumer
+
+Trechos de consumidor representam o processamento de um trabalho criado por um
+produtor e podem começar muito tempo depois que o trecho de produtor já
+terminou.
+
+## Especificação {#specification}
+
+Para mais informações, consulte
+[especificação de rastros](/docs/specs/otel/overview/#tracing-signal).