diff --git a/content/pt/docs/concepts/instrumentation/libraries.md b/content/pt/docs/concepts/instrumentation/libraries.md index e226d6c0bebe..bc0501bbd004 100644 --- a/content/pt/docs/concepts/instrumentation/libraries.md +++ b/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,8 @@ _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,40 +26,37 @@ 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: -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 -cenários podem ser habilitados automaticamente, sem necessidade de intervenção -ou configuração por parte do usuário. +[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 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 @@ -66,10 +64,10 @@ 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,30 +80,28 @@ 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. -Isso é essencial em linguagens que não suportam instrumentação totalmente -automática e ainda é útil em outras. +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. O restante deste documento fornece orientações sobre o que e como instrumentar, caso decida fazê-lo. @@ -114,34 +110,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 +[estáveis, mas sujeitas à evolução]: + /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability + +### 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 @@ -157,9 +156,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 +169,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 +212,18 @@ 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 {#nested-network-and-other-spans} -Chamadas de rede são geralmente rastreadas com auto-instrumentações do +Chamadas de rede são geralmente rastreadas com autoinstrumentaçõ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,24 +243,26 @@ 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. Se sua linguagem e ecossistema não tiverem suporte comum para logs, use [span @@ -270,13 +273,13 @@ Como regra geral, use eventos ou logs para dados verbosos em vez de rastros. Sempre anexe eventos à instância do trecho que sua instrumentação criou. Evite usar o trecho ativo se puder, pois você não controla a que ele se refere. -## Propagação de contexto +## Propagação de contexto {#context-propagation} -### Extraindo contexto +### Extraindo contexto {#extracting-context} Se você trabalha em uma biblioteca ou serviço que recebe chamadas _upstream_, -como um framework web ou um consumidor de mensagens, você deve extrair o -contexto da requisição/mensagem recebida. O OpenTelemetry fornece a API +como um _framework_ web ou um consumidor de mensagens, você deve extrair o +contexto da requisição ou mensagem recebida. O OpenTelemetry fornece a API `Propagator`, que oculta padrões específicos de propagação e lê o `Context` de rastreamento do cabeçalho. No caso de uma única resposta, há apenas um contexto no cabeçalho, que se torna o pai dos novos trechos criado pela biblioteca. @@ -305,24 +308,22 @@ try (Scope unused = span.makeCurrent()) { } ``` -Aqui estão os -[exemplos completos de extração de contexto em Java](/docs/languages/java/instrumentation/#context-propagation), -consulte a documentação do OpenTelemetry no seu idioma. - No caso de um sistema de mensagens, você pode receber mais de uma mensagem de uma vez. As mensagens recebidas se tornam _links_ no trecho que você cria. Consulte as [convenções de mensagens](/docs/specs/semconv/messaging/messaging-spans/) para -mais detalhes (AVISO: as convenções de mensagens estão -[em construção](https://github.com/open-telemetry/oteps/pull/173) 🚧). +mais detalhes. -### Injetando contexto +### Injetando contexto {#injecting-context} Quando você faz uma chamada de saída, geralmente vai querer propagar o contexto para o serviço _downstream_. Nesse caso, você deve criar um novo trecho para rastrear a chamada de saída e usar a API `Propagator` para injetar o contexto na mensagem. Podem haver outros casos em que você queira injetar o contexto, por -exemplo, ao criar mensagens para processamento assíncrono. +exemplo, ao criar mensagens para processamento assíncrono. O exemplo a seguir em +Java mostra como propagar o contexto. Consulte +[Injeção de contexto em Java](/docs/languages/java/instrumentation/#context-propagation) +para mais exemplos. ```java Span span = tracer.spanBuilder("send") @@ -344,44 +345,40 @@ try (Scope unused = span.makeCurrent()) { } ``` -Aqui está o -[exemplo completo de injeção de contexto em Java](/docs/languages/java/instrumentation/#context-propagation). - -Podem haver algumas exceções: +Podem haver algumas exceções onde não é necessário propagar o contexto: -- O serviço _downstream_ não suporta metadados ou proíbe campos desconhecidos -- O serviço _downstream_ não define protocolos de correlação. Existe a - possibilidade de que uma versão futura do serviço suporte a propagação de - contexto compatível? Injete-o! +- O serviço _downstream_ não suporta metadados ou proíbe campos desconhecidos. +- O serviço _downstream_ não define protocolos de correlação. Considere + adicionar suporte para a propagação de contexto em uma versão futura. - O serviço _downstream_ suporta um protocolo de correlação personalizado. - Melhor esforço com propagador personalizado: use o contexto de rastreamento - do OpenTelemetry, se for compatível. - - Ou gere e aplique IDs de correlação personalizados no trecho. + do OpenTelemetry, se for compatível, ou gere e insira IDs de correlação + personalizados no trecho. -### Em processo +### Em processo {#in-process} -- **Torne seus trechos ativos** (também conhecidos como atuais): isso permite - correlacionar trechos com logs e qualquer auto-instrumentação aninhada. -- Se a biblioteca tiver uma noção de contexto, suporte a **propagação explícita - de contexto de rastreamento opcional** _além_ de trechos ativos +- Torne seus trechos ativos ou atuais, pois isso permite correlacionar trechos + com logs e qualquer autoinstrumentação aninhada. +- Se a biblioteca tiver uma noção de contexto, ofereça suporte opcional para a + propagação explícita de contexto de rastreamento, além dos trechos ativos. - Coloque rastros (contexto de rastreamento) criados pela biblioteca no - contexto explicitamente, documente como acessá-los - - Permita que os usuários passem o contexto de rastreamento em seu contexto -- Dentro da biblioteca, propague o contexto de rastreamento explicitamente - - trechos ativos podem mudar durante _callbacks_! + contexto explicitamente, documente como acessá-los. + - Permita que os usuários passem o contexto de rastreamento em seu contexto. +- Dentro da biblioteca, propague o contexto de rastreamento explicitamente. + Trechos ativos podem mudar durante _callbacks_! - Capture o contexto ativo dos usuários na superfície da API pública assim que - puder, use-o como contexto pai para seus trechos - - Passe o contexto e aplique atributos, exceções, eventos nas instâncias - propagadas explicitamente - - Isso é essencial se você iniciar threads explicitamente, fizer processamento - em segundo plano ou outras coisas que podem falhar devido a limitações de - fluxo de contexto assíncrono em sua linguagem + possível e use-o como contexto pai para seus trechos. + - Passe o contexto adiante e aplique atributos, exceções, eventos nas + instâncias propagadas explicitamente. + - Isso é essencial caso você inicie processos explicitamente, realize + processamento em segundo plano ou outras operações que podem falhar devido a + limitações no fluxo de contexto assíncrono de sua linguagem. -## Miscelânea +## Considerações adicionais {#additional-considerations} -### Registro de Instrumentação +### Registro de Instrumentação {#instrumentation-registry} -Por favor, adicione sua biblioteca de instrumentação ao +Adicione sua biblioteca de instrumentação ao [registro do OpenTelemetry](/ecosystem/registry/), para que os usuários possam encontrá-la. @@ -391,10 +388,11 @@ A API do OpenTelemetry não executa operações quando não há SDK configurado aplicação. Quando o SDK do OpenTelemetry é configurado, ele [consome recursos limitados](/docs/specs/otel/performance/). -Aplicações da vida real, especialmente em grande escala, frequentemente têm -amostragem baseada em cabeçalho configurada. Techos não amostrados são baratos e -você pode verificar se o trecho está gravando, para evitar alocações extras e -cálculos potencialmente caros, enquanto preenche atributos. +Aplicações reais, especialmente em grande escala, frequentemente têm amostragem +baseada em cabeçalho configurada. Techos não amostrados são baratos e você pode +verificar se o trecho está gravando, para evitar alocações extras e cálculos +potencialmente caros, enquanto preenche atributos. O exemplo a seguir em Java +mostra como fornecer atributos para amostragem e verificar a gravação do trecho. ```java // alguns atributos são importantes para a amostragem e devem ser fornecidos no momento da criação @@ -411,26 +409,26 @@ if (span.isRecording()) { } ``` -### Tratamento de Erros +### Tratamento de Erros {#error-handling} -A API do OpenTelemetry é -[tolerante em tempo de execução](/docs/specs/otel/error-handling/#basic-error-handling-principles) -– não falha em argumentos inválidos, nunca lança exceções, e as elimina. Dessa -forma, problemas de instrumentação não afetam a lógica da aplicação. Teste a -instrumentação para identificar problemas que o OpenTelemetry pode esconder em -tempo de execução. +A API do OpenTelemetry não falha em argumentos inválidos, nunca lança exceções e +suprime erros, o que significa que é +[tolerante em tempo de execução](/docs/specs/otel/error-handling/#basic-error-handling-principles). +Dessa forma, problemas de instrumentação não afetam a lógica da aplicação. Teste +a instrumentação para identificar problemas que o OpenTelemetry oculta em tempo +de execução. -### Testes +### Testes {#testing} -Como o OpenTelemetry oferece uma variedade de auto-instrumentações, é útil -verificar como a sua instrumentação interage com outras telemetrias: -solicitações de entrada, solicitações de saída, logs, etc. Use uma aplicação -típica, com frameworks e bibliotecas populares e com todo o rastreamento ativado -ao testar sua instrumentação. Verifique como bibliotecas semelhantes à sua são +Como o OpenTelemetry oferece uma variedade de autoinstrumentações, experimente +como a sua instrumentação interage com outras telemetrias: requisições de +entrada, requisições de saída, logs, entre outros. Utilize uma aplicação típica, +com _frameworks_ e bibliotecas populares e com todo o rastreamento habilitado ao +testar sua instrumentação. Verifique como bibliotecas semelhantes à sua são exibidas. Para testes unitários, você geralmente pode simular ou criar versões fictícias -de `SpanProcessor` e `SpanExporter`. +de `SpanProcessor` e `SpanExporter`, como mostra o exemplo Java a seguir: ```java @Test @@ -461,5 +459,3 @@ class TestExporter implements SpanExporter { [bibliotecas de instrumentação]: /docs/specs/otel/overview/#instrumentation-libraries [span events]: /docs/specs/otel/trace/api/#add-events -[estáveis, mas sujeitas à evolução]: - /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability