docs: update content/pt/docs/concepts/instrumentation/libraries.md

Author: vitorvasc

content/pt/docs/concepts/instrumentation/libraries.md

@@ -2,7 +2,7 @@
 title: Bibliotecas
 description: Aprenda como adicionar instrumentação nativa à sua biblioteca.
 weight: 40
-default_lang_commit: a570a00c7a238ffe26528d7bfb20efdbaf939c39 # + link-fix patch
+default_lang_commit: e09adae2c06b71a08cafb2b1c42e3e7b9e48997b
 ---
 
 O OpenTelemetry fornece [bibliotecas de instrumentação][] para várias
@@ -11,7 +11,7 @@ _monkey-patching_ do código da biblioteca.
 
 A instrumentação nativa de bibliotecas com OpenTelemetry oferece melhor
 observabilidade e experiência para desenvolvedores, eliminando a necessidade das
-bibliotecas exporem e documentarem _hooks_:
+bibliotecas exporem e documentarem _hooks_. Outros benefícios fornecidos pela instrumentação nativa incluem:
 
 - _Hooks_ personalizados de logging podem ser substituídos por APIs
   OpenTelemetry comuns e fáceis de usar, os usuários utilizarão somente o
@@ -25,51 +25,40 @@ bibliotecas exporem e documentarem _hooks_:
   para diversos cenários de consumo usando uma grande variedade de pontos de
   extensibilidade bem documentados do OpenTelemetry.
 
-## Convenção semântica
+![ Native Instrumentation vs instrumentation libraries](../native-vs-libraries.svg)
 
-Confira as [convenções semânticas](/docs/specs/semconv/general/trace/)
-disponíveis, que abrangem frameworks web, clientes RPC, bancos de dados,
-clientes de mensagens, componentes de infraestrutura e muito mais!
+## Convenção semântica {#semantic-conventions}
 
-Se a sua biblioteca se enquadra em alguma dessas categorias, siga as convenções.
-Elas são a principal fonte de verdade e indicam quais informações devem ser
-incluídas nos trechos. As convenções tornam a instrumentação consistente:
+[Convenções semânticas](/docs/specs/semconv/general/trace/) são a principal fonte de verdade e indicam quais informações devem ser
+incluídas nos trechos produzidos por _frameworks_ web, clientes RPC, bancos de dados, clientes de mensagens, infraestrutura e mais. As convenções tornam a instrumentação consistente:
 usuários que trabalham com telemetria não precisam aprender as especificidades
 de cada biblioteca, e fornecedores de observabilidade podem criar experiências
-para uma ampla variedade de tecnologias (por exemplo, bancos de dados ou
-sistemas de mensagens). Quando as bibliotecas seguem as convenções, muitos
+para uma ampla variedade de tecnologias, por exemplo, bancos de dados ou
+sistemas de mensagens. Quando as bibliotecas seguem as convenções, muitos
 cenários podem ser habilitados automaticamente, sem necessidade de intervenção
 ou configuração por parte do usuário.
 
 As convenções semânticas estão em constante evolução, e novas são adicionadas
 regularmente. Se ainda não existirem convenções para a sua biblioteca,
 [considere adicioná-las](https://github.com/open-telemetry/semantic-conventions/issues).
-Preste atenção especial aos nomes dos trechos; procure usar nomes significativos
-e considere a cardinalidade ao defini-los.
+Preste atenção especial aos nomes dos trechos: procure usar nomes significativos
+e considere a cardinalidade ao defini-los. Também defina o atributo [`schema_url`](/docs/specs/otel/schemas/#schema-url), que pode ser
+utilizado para registrar a versão das convenções semânticas em uso
 
-Há um atributo [`schema_url`](/docs/specs/otel/schemas/#schema-url) que pode ser
-usado para registrar a versão das convenções semânticas em uso. Sempre que
-possível, configure esse atributo.
+Se tiver algum feedback ou quiser adicionar uma nova convenção, contribua juntando-se ao _[Instrumentation Slack](https://cloud-native.slack.com/archives/C01QZFGMLQ7)_, ou através de uma nova discussão ou _pull request_ no [repositório de Especificações _(Specification)](https://github.com/open-telemetry/opentelemetry-specification) .
 
-Se tiver algum feedback ou quiser adicionar uma nova convenção, participe e
-contribua! O
-[Instrumentation Slack](https://cloud-native.slack.com/archives/C01QZFGMLQ7) ou
-o repositório de
-[Specification](https://github.com/open-telemetry/opentelemetry-specification)
-são ótimos pontos de partida!
-
-### Definindo trechos
+### Definindo trechos {#defining-spans}
 
 Pense na sua biblioteca do ponto de vista de um usuário e no que ele poderia
 querer saber sobre o comportamento e a atividade da biblioteca. Como mantenedor
 da biblioteca, você conhece os detalhes internos, mas o usuário provavelmente
 estará mais interessado na funcionalidade da aplicação do que no funcionamento
 interno da biblioteca. Considere quais informações podem ser úteis para analisar
 o uso da sua biblioteca e pense em uma maneira apropriada de modelar esses
-dados. Algumas considerações incluem:
+dados. Alguns aspectos a serem considerados incluem:
 
 - Trechos e hierarquias de trecho
-- Atributos numéricos em trechos (como alternativa a métricas agregadas)
+- Atributos numéricos em trechos, como uma alternativa a métricas agregadas
 - Eventos em trechos
 - Métricas agregadas
 
@@ -82,28 +71,23 @@ adicionais.
 
 Siga as convenções semânticas ao definir atributos dos trechos.
 
-## Quando **não** instrumentar
+## Quando não instrumentar {#when-not-to-instrument}
 
 Algumas bibliotecas atuam como camadas finas que encapsulam chamadas de rede. Há
 uma grande chance de que o OpenTelemetry já tenha uma biblioteca de
-instrumentação para o cliente RPC subjacente (confira o
-[registry](/ecosystem/registry/)). Nesse caso, pode não ser necessário
-instrumentar a biblioteca que encapsula essas chamadas. Como diretriz geral, só
-instrumente sua biblioteca em seu próprio nível.
+instrumentação para o cliente RPC subjacente. Confira o
+_[registro](/ecosystem/registry/)_ para encontrar as bibliotecas existentes. Caso uma biblioteca já exista, pode não ser necessário instrumentar a biblioteca que encapsula essas chamadas.
 
-Não instrumente se:
+Como regra geral, instrumente sua biblioteca apenas em seu próprio nível. Não a instrumente caso todos os casos a seguir se apliquem:
 
-- Sua biblioteca é um proxy simples em cima de APIs documentadas ou
-  autoexplicativas
-- O OpenTelemetry já tem instrumentação para as chamadas de rede subjacentes
+- Sua biblioteca é um _proxy_ simples em cima de APIs documentadas ou
+  autoexplicativas.
+- O OpenTelemetry já possui instrumentação para as chamadas de rede subjacentes.
 - Não existem convenções que sua biblioteca deva seguir para enriquecer a
-  telemetria
-
-Se estiver em dúvida - não instrumente - você sempre pode fazê-lo mais tarde,
-quando perceber a necessidade.
+  telemetria.
 
-Se optar por não instrumentar, ainda pode ser útil fornecer uma maneira de
-configurar _handlers_ do OpenTelemetry para a instância interna do cliente RPC.
+Em caso de dúvida, não instrumente. Se optar por não instrumentar, ainda pode ser útil fornecer uma maneira de
+configurar manipuladores do OpenTelemetry para a instância interna do cliente RPC.
 Isso é essencial em linguagens que não suportam instrumentação totalmente
 automática e ainda é útil em outras.
 
@@ -114,41 +98,37 @@ caso decida fazê-lo.
 
 O primeiro passo é adicionar a dependência do pacote OpenTelemetry API.
 
-O OpenTelemetry possui [dois módulos principais](/docs/specs/otel/overview/) -
+O OpenTelemetry possui [dois módulos principais](/docs/specs/otel/overview/):
 API e SDK. A API do OpenTelemetry é um conjunto de abstrações e implementações
 não operacionais. A menos que sua aplicação importe o SDK do OpenTelemetry, sua
 instrumentação não faz nada e não impacta o desempenho da aplicação.
 
-**Bibliotecas devem usar apenas a API do OpenTelemetry.**
+### Bibliotecas devem usar apenas a API do OpenTelemetry {#libraries-should-only-use-the-opentelemetry-api}
 
-Você pode estar com receio de adicionar novas dependências, então aqui estão
-algumas considerações para ajudar a minimizar problemas com dependências:
+Caso você esteja com receio de adicionar novas dependências, então aqui estão
+algumas considerações para ajudar a minimizar problemas de conflitos de dependências:
 
-- A API de rastros do OpenTelemetry alcançou estabilidade no início de 2021,
-  seguindo a
-  [Convenção semântica 2.0](/docs/specs/otel/versioning-and-stability/), e
-  levamos a estabilidade da API a sério.
-- Ao adicionar dependências, use a versão estável da API do OpenTelemetry
-  (1.0.\*) e evite atualizá-la, a menos que precise usar novas funcionalidades.
+- A API de rastros do OpenTelemetry alcançou estabilidade no início de 2021. Ela segue o [Versionamento Semântico 2.0](/docs/specs/otel/versioning-and-stability/).
+- Utilize a versão mais antiga estável da API do OpenTelemetry (1.0.\*) e evite atualizá-la, a menos que precise usar novas funcionalidades.
 - Enquanto sua instrumentação se estabiliza, considere lançá-la como um pacote
   separado, para que isso não cause problemas para usuários que não a utilizam.
   Você pode mantê-la em seu repositório ou
   [adicioná-la ao OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/0155-external-modules.md#contrib-components),
   para que seja distribuída junto com outras bibliotecas de instrumentação.
-- As Convenções Semânticas são [estáveis, mas sujeitas à evolução][]: embora
+- As Convenções semânticas são [estáveis, mas sujeitas à evolução][]: embora
   isso não cause problemas funcionais, pode ser necessário atualizar sua
   instrumentação de tempos em tempos. Ter a instrumentação em um pacote
   experimental ou no repositório _contrib_ do OpenTelemetry pode ajudar a manter
   as convenções atualizadas sem causar mudanças disruptivas para seus usuários.
 
-### Obtendo um rastreador
+### Obtendo um rastreador {#getting-a-tracer}
 
 Toda a configuração da aplicação é ocultada da sua biblioteca por meio da API de
 Rastreamento. As bibliotecas podem permitir que as aplicações passem instâncias
 de `TracerProvider` para facilitar testes e injeção de dependências, ou podem
 obtê-las a partir do
-[TracerProvider global](/docs/specs/otel/trace/api/#get-a-tracer). As
-implementações do OpenTelemetry em diferentes linguagens podem ter preferências
+[TracerProvider global](/docs/specs/otel/trace/api/#get-a-tracer).
+As implementações do OpenTelemetry em diferentes linguagens podem ter preferências
 distintas para passar instâncias ou acessar o global, dependendo do que é mais
 comum na linguagem.
 
@@ -157,9 +137,9 @@ de rastreamento) - essas informações aparecerão na telemetria e ajudarão os
 usuários a processar e filtrar a telemetria, além de entender sua origem e
 depurar/relatar quaisquer problemas de instrumentação.
 
-## O que instrumentar
+## O que instrumentar {#what-to-instrument}
 
-### APIs Públicas
+### APIs Públicas {#public-apis}
 
 APIs públicas são bons candidatos para rastreamento: trechos criados para
 chamadas de APIs públicas permitem que os usuários mapeiem a telemetria para o
@@ -170,7 +150,9 @@ biblioteca. Quais chamadas devem ser rastreadas:
   que levam tempo significativo e podem falhar (ex.: operações de Entrada/Saída)
 - _Handlers_ que processam requisições ou mensagens
 
-**Exemplo de instrumentação:**
+#### Exemplo de instrumentação {#instrumentation-example}
+
+O exemplo a seguir mostra como instrumentar uma aplicação Java:
 
 ```java
 private static Tracer tracer =  getTracer(TracerProvider.noop());
@@ -211,18 +193,17 @@ private Response selectWithTracing(Query query) {
 }
 ```
 
-Siga as convenções para preencher atributos! Se nenhuma delas se aplicar,
+Siga as convenções para preencher atributos. Se nenhuma delas se aplicar,
 consulte as [convenções gerais](/docs/specs/semconv/general/attributes/).
 
-### Trechos de rede aninhados e outros trechos
+### Trechos de rede aninhados e outros trechos {#nestex-network-and-other-spans}
 
 Chamadas de rede são geralmente rastreadas com auto-instrumentações do
 OpenTelemetry através da implementação correspondente do cliente.
 
 ![Trecho de banco de dados e HTTP aninhados na interface do Jaeger](../nested-spans.svg)
 
-Se o OpenTelemetry não suportar o rastreamento do seu cliente de rede, use seu
-melhor julgamento. Aqui estão algumas considerações para ajudar:
+Se o OpenTelemetry não suportar o rastreamento do seu cliente de rede, aqui estão algumas considerações para ajudar a decidir o melhor curso de ação:
 
 - Rastrear chamadas de rede melhoraria a observabilidade para os usuários ou sua
   capacidade de apoiá-los?
@@ -242,26 +223,27 @@ melhor julgamento. Aqui estão algumas considerações para ajudar:
 Se o OpenTelemetry já suportar o rastreamento de suas chamadas de rede, você
 provavelmente não quer duplicá-lo. Pode haver algumas exceções:
 
-- Para suportar usuários sem auto-instrumentação (que pode não funcionar em
-  certos ambientes ou os usuários podem ter preocupações com _monkey-patching_)
-- Para habilitar protocolos personalizados (legados) de correlação e propagação
-  de contexto com o serviço subjacente
+- Para suportar usuários sem auto-instrumentação, que pode não funcionar em
+  certos ambientes ou quando os usuários podem ter preocupações com _monkey-patching_.
+- Para habilitar protocolos personalizados ou legados de correlação e propagação
+  de contexto com o serviço subjacente.
 - Enriquecer trechos de RPC com informações absolutamente essenciais específicas
   da biblioteca/serviço não cobertas pela auto-instrumentação
 
-AVISO: Solução genérica para evitar duplicação está em construção 🚧.
+Uma solução genérica para evitar duplicação está em construção.
 
-### Eventos
+### Eventos {#events}
 
 Rastros são um tipo de sinal que seus aplicativos podem emitir. Eventos (ou
-logs) e traces se complementam, não se duplicam. Sempre que você tiver algo que
-deva ter uma verbosidade, logs são uma escolha melhor do que traces.
+logs) e rastros se complementam, não se duplicam. Sempre que você tiver algo que
+deva ter um certo nível de verbosidade, logs são uma escolha melhor do que rastros.
 
-É provável que seu aplicativo já use log ou algum módulo semelhante. Seu módulo
-pode já ter integração com o OpenTelemetry -- para descobrir, veja o
-[registry](/ecosystem/registry/). As integrações geralmente adicionam o contexto
+Caso a sua aplicação já utilize log ou algum módulo semelhante, é possível que o módulo de logs já tenha integração com o OpenTelemetry. Para descobrir, veja o
+[registro](/ecosystem/registry/). As integrações geralmente adicionam o contexto
 de rastros ativo em todos os logs, para que os usuários possam correlacioná-los.
 
+[//]: # (TODO: Draft PR, resume it from here)
+
 Se sua linguagem e ecossistema não tiverem suporte comum para logs, use [span
 events][] para compartilhar detalhes adicionais do aplicativo. Eventos podem ser
 mais convenientes se você quiser adicionar atributos também.