From 1b87a28caf6bd12d97ff5ebb80f63741e125d1ec Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Wed, 7 Aug 2024 07:11:27 -0300 Subject: [PATCH 1/9] feat: add localization trace --- content/pt/docs/concepts/signals/traces.md | 47 ++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 content/pt/docs/concepts/signals/traces.md diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md new file mode 100644 index 000000000000..94576965296e --- /dev/null +++ b/content/pt/docs/concepts/signals/traces.md @@ -0,0 +1,47 @@ +--- +title: Rastros +weight: 1 +cSpell:ignore: Guten +description: O caminho de uma solicitação através do seu aplicativo. +--- + +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. + +`olá` trecho: + +```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 + } + } + ] +} +``` From 4fdb4c9886d0f23f37ceef46de729ffee6766333 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Sun, 11 Aug 2024 16:07:52 -0300 Subject: [PATCH 2/9] feat: add localization trecer --- content/pt/docs/concepts/signals/traces.md | 254 ++++++++++++++++++++- 1 file changed, 253 insertions(+), 1 deletion(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 94576965296e..02da161125d6 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -19,7 +19,7 @@ Vamos explorar isso com três unidades de trabalho, representadas como 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. -`olá` trecho: +trecho `olá`: ```json { @@ -45,3 +45,255 @@ Os exemplos JSON a seguir não apresentam um formato específico, especialmente ] } ``` + +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 + +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, OpenTelemetry Collector ou qualquer backend de código aberto ou fornecedor de sua escolha. + +## Propagação de Contexto + +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 + +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) +- Carimbo 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 span: + +```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 + +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 + +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 + +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 + +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 + +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 + +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 + +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. + +## Specification + +Para mais informações, consulte [especificação de rastros](/docs/specs/otel/overview/#tracing-signal). From cced49ada32fb5b9909613dd4620638120099db7 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Sun, 11 Aug 2024 16:12:02 -0300 Subject: [PATCH 3/9] fix: run fmt --- content/pt/docs/concepts/signals/traces.md | 188 ++++++++++++++++----- 1 file changed, 143 insertions(+), 45 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 02da161125d6..5e9ea8459d0f 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -3,6 +3,7 @@ title: Rastros weight: 1 cSpell:ignore: Guten 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 @@ -46,7 +47,9 @@ trecho `olá`: } ``` -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. +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`: @@ -82,7 +85,10 @@ O trecho `olá-cumprimentos`: } ``` -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á`. +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`: @@ -111,33 +117,58 @@ O trecho `olá-saudações`: } ``` -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`. +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! +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. +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. +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ê. +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 -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. +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, OpenTelemetry Collector ou qualquer backend de código aberto ou fornecedor de sua escolha. +Trace Exporters enviam rastros para um consumidor. Esse consumidor pode ser a +saída padrão para depuração em tempo de desenvolvimento, OpenTelemetry Collector +ou qualquer backend de código aberto ou fornecedor de sua escolha. ## Propagação de Contexto -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). +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 -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: +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) @@ -187,7 +218,9 @@ Exemplo de span: } ``` -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. +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 @@ -196,61 +229,93 @@ O contexto do trecho é um objeto imutável em cada trecho que contém o seguint - 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 +- 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). +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). +Como o contexto do trecho contém o trace ID, o trace ID é usado ao criar +[links de trechos](#span-links). ### Atributos -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. +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. +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. +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 +- 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. +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 -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. +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 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. +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 -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ê. +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. +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. +- 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 -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. +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. +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. +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. +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. +Os links são opcionais, mas servem como uma boa maneira de associar trechos de +rastro uns aos outros. ### O estado do Trecho @@ -260,40 +325,73 @@ Cada trecho tem um estado. Os três valores possíveis são: - `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. +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 é `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". +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. +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 -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. +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). +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. +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. +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. +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. +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. +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. ## Specification -Para mais informações, consulte [especificação de rastros](/docs/specs/otel/overview/#tracing-signal). +Para mais informações, consulte +[especificação de rastros](/docs/specs/otel/overview/#tracing-signal). From 7419f5dd7bf4b4746c077ec9a0bdddf0d86e2678 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Sun, 11 Aug 2024 16:18:01 -0300 Subject: [PATCH 4/9] fix: change Ok to OK --- content/pt/docs/concepts/signals/traces.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 5e9ea8459d0f..972a2c5cc556 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -323,7 +323,7 @@ Cada trecho tem um estado. Os três valores possíveis são: - `Unset` - `Error` -- `Ok` +- `OK` O valor padrão é `Unset`. Um estado de trecho `Unset` significa que a operação rastreada foi concluída com sucesso, sem erro. @@ -332,19 +332,19 @@ Quando o estado de um trecho é `Error`, isso significa que algum erro ocorreu n 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 +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 +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` +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. +trecho como OK. ### Tipo de Trecho From c9847258d9f6ea80cb075f4ffe4acdc7b69f5186 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Tue, 13 Aug 2024 18:59:21 -0300 Subject: [PATCH 5/9] fix: ajuste doc --- content/pt/docs/concepts/signals/traces.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 972a2c5cc556..05cc4239acce 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -1,7 +1,6 @@ --- title: Rastros weight: 1 -cSpell:ignore: Guten description: O caminho de uma solicitação através do seu aplicativo. default_lang_commit: 57cd4f78d61cc1642ce56089aeec7ae278544194 --- @@ -20,6 +19,8 @@ Vamos explorar isso com três unidades de trabalho, representadas como 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 @@ -172,14 +173,14 @@ informações: - Nome - ID do trecho pai (vazio para trecho raiz) -- Carimbo de tempo do início e fim +- 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 span: +Exemplo de trecho: ```json { @@ -391,7 +392,7 @@ 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. -## Specification +## Especificação Para mais informações, consulte [especificação de rastros](/docs/specs/otel/overview/#tracing-signal). From d9e9ac396e3fbbc7ce6e84b7bb0434f91d8b748d Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Tue, 13 Aug 2024 19:03:36 -0300 Subject: [PATCH 6/9] fix: update doc Co-authored-by: Edson C. --- content/pt/docs/concepts/signals/traces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 05cc4239acce..138aee940add 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -154,7 +154,7 @@ 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, OpenTelemetry Collector +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 From 8df563bda7ca2e6aef50a9673552bdc79718c828 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Tue, 13 Aug 2024 19:05:45 -0300 Subject: [PATCH 7/9] fix: run lint local --- content/pt/docs/concepts/signals/traces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 138aee940add..fc8363d6d4c9 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -154,8 +154,8 @@ 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. +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 From 73eab9edf0f7c3ea3621b33b979362ab6a831ce8 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Fri, 16 Aug 2024 20:22:01 -0300 Subject: [PATCH 8/9] fix: ajuste das ancoras da doc --- content/pt/docs/concepts/signals/traces.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index fc8363d6d4c9..710baee9cc41 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -157,7 +157,7 @@ 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 +## 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 @@ -165,7 +165,7 @@ 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 +## 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 @@ -223,7 +223,7 @@ 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 +### Contexto do Trecho {#span-context} O contexto do trecho é um objeto imutável em cada trecho que contém o seguinte: @@ -240,7 +240,7 @@ com a [propagação de contexto](#context-propagation) e Como o contexto do trecho contém o trace ID, o trace ID é usado ao criar [links de trechos](#span-links). -### Atributos +### 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á @@ -267,7 +267,7 @@ 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 +### 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 @@ -298,7 +298,7 @@ finalizada, você pode querer adicionar dados da operação à sua telemetria. - Se a data e hora não forem relevantes, anexe os dados como atributos de trecho. -### Links de Trechos +### 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 @@ -318,7 +318,7 @@ 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 +### O estado do Trecho {#span-status} Cada trecho tem um estado. Os três valores possíveis são: From c6b59fcd35e9c98f03f2e1d455306d4c3c660110 Mon Sep 17 00:00:00 2001 From: Ezzio Moreira Date: Fri, 16 Aug 2024 20:40:30 -0300 Subject: [PATCH 9/9] fix: ajuste das ancoras da doc --- content/pt/docs/concepts/signals/traces.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md index 710baee9cc41..d8d3271b6b44 100644 --- a/content/pt/docs/concepts/signals/traces.md +++ b/content/pt/docs/concepts/signals/traces.md @@ -145,7 +145,7 @@ Trace Provider também inclui a inicialização de Resource e Exporter. Geralmen é a primeira etapa do rastreamento com OpenTelemetry. Em alguns SDKs, um Trace Provider global já é inicializado para você. -## Rastro +## 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 @@ -267,7 +267,7 @@ 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 +### 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 @@ -284,7 +284,7 @@ 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 +#### 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 @@ -347,7 +347,7 @@ 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 +### 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 @@ -392,7 +392,7 @@ 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 +## Especificação {#specification} Para mais informações, consulte [especificação de rastros](/docs/specs/otel/overview/#tracing-signal).