From b9615b085049edd380a4e7823ac76e83e248cfe5 Mon Sep 17 00:00:00 2001 From: Marcelo Baptista Date: Sat, 24 Aug 2024 16:07:42 -0300 Subject: [PATCH 1/4] [pt] Add pt/content/docs/concepts/instrumentation --- .../docs/concepts/instrumentation/_index.md | 35 ++ .../concepts/instrumentation/code-based.md | 32 ++ .../concepts/instrumentation/libraries.md | 327 ++++++++++++++++++ .../concepts/instrumentation/nested-spans.svg | 1 + .../concepts/instrumentation/zero-code.md | 35 ++ 5 files changed, 430 insertions(+) create mode 100644 content/pt/docs/concepts/instrumentation/_index.md create mode 100644 content/pt/docs/concepts/instrumentation/code-based.md create mode 100644 content/pt/docs/concepts/instrumentation/libraries.md create mode 100644 content/pt/docs/concepts/instrumentation/nested-spans.svg create mode 100644 content/pt/docs/concepts/instrumentation/zero-code.md diff --git a/content/pt/docs/concepts/instrumentation/_index.md b/content/pt/docs/concepts/instrumentation/_index.md new file mode 100644 index 000000000000..77b5a2fe9439 --- /dev/null +++ b/content/pt/docs/concepts/instrumentation/_index.md @@ -0,0 +1,35 @@ +--- +title: Instrumentação +description: Como o OpenTelemetry facilita a instrumentação +aliases: [instrumentation] +weight: 15 +default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f +--- + +Para tornar um sistema observável, ele deve ser **instrumentado**: Ou seja, o código dos componentes do sistema devem emitir [rastros](/docs/concepts/signals/traces/), +[métricas](/docs/concepts/signals/metrics/), e +[logs](/docs/concepts/signals/logs/). + +Usando o OpenTelemetry, você pode instrumentar seu código de duas maneiras principais: + +1. [Soluções baseadas em código](/docs/concepts/instrumentation/code-based) através das + [APIs e SDKs oficiais para a maioria das linguagens](/docs/languages/) +2. [Soluções autoinstrumentadas](/docs/concepts/instrumentation/zero-code/) + +Soluções **baseadas em código** permitem obter uma visão mais profunda e rica da telemetria da própria aplicação. Elas permitem que você use a API do OpenTelemetry para gerar telemetria a partir da sua aplicação, o que atua como um complemento essencial para a telemetria gerada por soluções autoinstrumentadas. + +Soluções **autoinstrumentadas** são ótimas para começar ou quando você não pode modificar a aplicação da qual você precisa obter telemetria. Elas fornecem uma rica telemetria a partir das bibliotecas que você usa e/ou do ambiente no qual sua aplicação é executada. Outra +forma de pensar é que elas fornecem informações sobre o que está acontecendo _nas bordas_ da sua aplicação. + +Você pode usar ambas as soluções simultaneamente. + +## Benefícios adicionais do OpenTelemetry + +O OpenTelemetry oferece mais do que apenas soluções de telemetria autoinstrumentadas e baseadas em código. Também fazem parte do OpenTelemetry: + +- As bibliotecas podem aproveitar a API do OpenTelemetry como uma dependência, o que não terá impacto nas aplicações que usam essa biblioteca, a menos que o SDK do OpenTelemetry seja importado. +- Para cada [sinal](/docs/concepts/signals) (rastros, métricas, logs), você tem vários métodos à sua disposição para criar, processar e exportá-los. +- Com a [propagação de contexto](/docs/concepts/context-propagation) incorporada nas implementações, você pode correlacionar sinais independentemente de onde eles são gerados. +- [Recursos](/docs/concepts/resources) e [Escopos de Instrumentação](/docs/concepts/instrumentation-scope) permitem agrupar sinais por diferentes entidades, como o [host](/docs/specs/semconv/resource/host/), [sistema operacional](/docs/specs/semconv/resource/os/) ou [cluster K8s](/docs/specs/semconv/resource/k8s/#cluster). +- Cada implementação específica de linguagem da API e SDK seguem os requisitos e expectativas da [especificação do OpenTelemetry](/docs/specs/otel/). +- As [Convenções Semânticas](/docs/concepts/semantic-conventions) fornecem um esquema de nomenclatura comum que pode ser usado para padronização em bases de código e plataformas. diff --git a/content/pt/docs/concepts/instrumentation/code-based.md b/content/pt/docs/concepts/instrumentation/code-based.md new file mode 100644 index 000000000000..d8b7d8ec7b31 --- /dev/null +++ b/content/pt/docs/concepts/instrumentation/code-based.md @@ -0,0 +1,32 @@ +--- +title: Instrumentação baseada em Código +description: Aprenda o essencial para configurar a instrumentação baseada em código +weight: 20 +aliases: [manual] +cSpell:ignore: proxying +default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f +--- + +## Importe a API e SDK do OpenTelemetry + +Primeiro, você precisará importar o OpenTelemetry para o código do seu serviço. Se você estiver desenvolvendo uma biblioteca ou algum outro componente que será consumido por um binário executável, então você só precisará depender da API. Se o seu artefato for um processo ou serviço independente, então você precisará depender tanto da API quanto do SDK. Para saber mais informações sobre a API e SDK do OpenTelemetry, consulte a [especificação](/docs/specs/otel/). + +## Configure a API do OpenTelemetry + +Para criar rastros ou métricas, você precisará primeiro criar um rastreador e/ou um provedor de métricas. Em geral, recomendamos que o SDK forneça um provedor padrão único para esses objetos. Em seguida, você obterá uma instância de rastreador ou medidor desse provedor e dará a ele um nome e uma versão. O nome que você escolher aqui deve identificar exatamente o que está sendo instrumentado - se você estiver escrevendo uma biblioteca, por exemplo, então você deve nomeá-la com o nome da sua biblioteca (por exemplo, `com.example.myLibrary`), pois esse nome irá agrupar todos os spans ou eventos de métricas produzidos. Também é recomendado que você forneça uma string de versão (por exemplo, `semver:1.0.0`) que corresponda à versão atual da sua biblioteca ou serviço. + +## Configure o SDK do OpenTelemetry + +Se você estiver desenvolvendo um processo de serviço, também precisará configurar o SDK com as opções apropriadas para exportar seus dados de telemetria para algum backend de análise. Recomendamos que essa configuração seja feita programaticamente por meio de um arquivo de configuração ou algum outro mecanismo. Também existem opções de ajuste específicas de cada linguagem das quais você pode se beneficiar. + +## Crie Dados de Telemetria + +Depois de configurar a API e o SDK, você poderá criar rastros e eventos de métricas por meio dos objetos rastreador e medidor que você obteve do provedor. Utilize Bibliotecas de Instrumentação para suas dependências - confira o [registro](/ecosystem/registry/) ou o repositório da linguagem escolhida para ter mais informações sobre elas. + +## Exporte os Dados + +Depois de criar os dados de telemetria, você vai querer enviá-los para algum lugar. O OpenTelemetry suporta dois métodos principais de exportação de dados do seu processo para um backend de análise, seja diretamente de um processo ou por meio do [OpenTelemetry Collector](/docs/collector). + +A exportação in-process requer que você importe e dependa de um ou mais _exporters_, bibliotecas que traduzem os objetos de trecho e métrica em memória do OpenTelemetry para o formato apropriado para ferramentas de análise de telemetria como Jaeger ou Prometheus. Além disso, o OpenTelemetry suporta um protocolo de comunicação conhecido como `OTLP`, que é suportado por todos os SDKs do OpenTelemetry. Esse protocolo pode ser usado para enviar dados para o OpenTelemetry Collector, um processo binário independente que pode ser executado como um proxy ou sidecar para suas instâncias de serviço ou em um host separado. O Collector pode então ser configurado para encaminhar e exportar esses dados para as suas ferramentas de análise preferidas. + +Além de ferramentas de código aberto como Jaeger ou Prometheus, uma lista crescente de empresas suporta a ingestão de dados de telemetria do OpenTelemetry. Para mais detalhes, consulte [Fornecedores](/ecosystem/vendors/). diff --git a/content/pt/docs/concepts/instrumentation/libraries.md b/content/pt/docs/concepts/instrumentation/libraries.md new file mode 100644 index 000000000000..2e215d3e47d2 --- /dev/null +++ b/content/pt/docs/concepts/instrumentation/libraries.md @@ -0,0 +1,327 @@ +--- +title: Bibliotecas +description: Aprenda como adicionar instrumentação nativa à sua biblioteca. +aliases: [../instrumenting-library] +weight: 40 +default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f +--- + +O OpenTelemetry fornece [bibliotecas de instrumentação][] para muitas bibliotecas, o que geralmente é feito por meio de hooks de biblioteca ou modificando o código da biblioteca (monkey-patching). + +A instrumentação nativa de bibliotecas com o OpenTelemetry oferece melhor observabilidade e experiência para os desenvolvedores, eliminando a necessidade de as bibliotecas exporem e documentarem hooks: + +- hooks personalizados de logs podem ser substituídos por APIs comuns e fáceis de usar do OpenTelemetry, os usuários interagem apenas com o OpenTelemetry +- Rastros, logs e métricas do código da biblioteca e da aplicação são correlacionados e coerentes +- Convenções comuns permitem que os usuários obtenham telemetria semelhante e consistente dentro da mesma tecnologia e entre bibliotecas e linguagens +- Os sinais de telemetria podem ser ajustados (filtrados, processados, agregados) para diversos cenários de consumo usando uma ampla variedade de pontos de extensão do OpenTelemetry bem documentados. + +## Convenções Semânticas + +Confira as [convenções semânticas](/docs/specs/semconv/general/trace/) +disponíveis, que abrangem frameworks web, clientes RPC, bancos de dados, clientes de mensageria, componentes de infraestrutura e muito mais! + +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 garantem consistência na instrumentação: os usuários que trabalham com telemetria não precisam aprender os detalhes específicos de cada biblioteca, e os fornecedores de observabilidade podem construir experiências para uma ampla variedade de tecnologias (por exemplo, bancos de dados ou sistemas de mensageria). Quando as bibliotecas seguem as convenções, muitos cenários podem ser habilitados automaticamente, sem a necessidade de intervenção ou configuração por parte do usuário. + +As convenções semânticas estão sempre evoluindo e novas estão constantemente sendo adicionadas. Se não houver convenções para sua biblioteca, considere +[adicionar novas.](https://github.com/open-telemetry/semantic-conventions/issues). +Tenha atenção especial aos nomes dos trechos; procure usar nomes significativos e considere a cardinalidade ao defini-los. + +Há um atributo [`schema_url`](/docs/specs/otel/schemas/#schema-url) que pode ser usado para registrar qual versão das convenções semânticas está sendo utilizada. Defina este atributo, sempre que possível. + +Se você tiver algum feedback ou quiser adicionar uma nova convenção, contribua! +[Slack sobre Instrumentação](https://cloud-native.slack.com/archives/C01QZFGMLQ7) ou o +[repositório da Especificação](https://github.com/open-telemetry/opentelemetry-specification) +são ótimos pontos de partida! + +### Definindo trechos + +Considere sua biblioteca sob a perspectiva de um usuário e o que ele gostaria de 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 de sua aplicação do que nos aspectos internos da biblioteca. Pense sobre que informações podem ser úteis para analisar o uso da sua biblioteca e sobre a melhor forma de modelar esses dados. Alguns pontos a considerar são: + +- trechos e hierarquias de trechos +- Atributos numéricos em trechos (como alternativa a métricas agregadas) +- Eventos de trechos +- Métricas agregadas + +Por exemplo, se sua biblioteca faz requisições a um banco de dados, crie trechos apenas para a requisição lógica ao banco de dados. As requisições físicas pela rede devem ser instrumentadas nas bibliotecas que implementam essa funcionalidade. Além disso, prefira capturar atividades adicionais, como a serialização de objetos/dados, como eventos de trechos, em vez de criar trechos separados para essas atividades. + +Siga as convenções semânticas ao definir os atributos dos trechos. + +## Quando **não** instrumentar + +Algumas bibliotecas são clientes simples que envolvem chamadas de rede. É provável que o OpenTelemetry já tenha uma biblioteca de instrumentação para o cliente RPC subjacente (confira o [registro](/ecosystem/registry/)). Nesse caso, pode não ser necessário instrumentar a biblioteca que serve como camada adicional. Como regra geral, instrumente sua biblioteca apenas no seu próprio nível. + +Não instrumente se: + +- sua biblioteca for um proxy simples sobre APIs documentadas ou autoexplicativas +- _e_ o OpenTelemetry já tiver instrumentação para as chamadas de rede subjacentes +- _e_ e não houver convenções que sua biblioteca deva seguir para enriquecer a telemetria + +Se estiver em dúvida, não instrumente – é possível realizar a instrumentação mais tarde, caso necessário. + +Se optar por não instrumentar, pode ser útil fornecer uma forma de configurar os manipuladores do OpenTelemetry para a instância interna do seu cliente RPC. Isso é essencial em linguagens que não suportam instrumentação totalmente automática e ainda útil em outras. + +O restante deste documento oferece orientações sobre o que e como instrumentar, se optar por fazer. + +## API do OpenTelemetry + +O primeiro passo é adicionar a dependência do pacote da API do OpenTelemetry. + +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 a aplicação importe o SDK do OpenTelemetry, a instrumentação não terá efeito e não impactará o desempenho da aplicação. + +**As bibliotecas devem usar apenas a API do OpenTelemetry.** + +É compreensível estar preocupado com a adição de novas dependências, aqui estão algumas considerações para ajudar a minimizar problemas relacionados a dependências: + +- A API de Rastros do OpenTelemetry atingiu estabilidade no início de 2021, segue o + [Versionamento Semântico 2.0](/docs/specs/otel/versioning-and-stability/) e levamos a estabilidade da API a sério. +- Ao adicionar a dependência, use a versão estável mais antiga da API do OpenTelemetry (1.0.\*) e evite atualizá-la a menos que precise de novos recursos. +- Enquanto sua instrumentação se estabiliza, considere disponibilizá-la como um pacote separado, para que 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/oteps/blob/main/text/0155-external-modules.md#contrib-components), + para que seja incluída com outras bibliotecas de instrumentação. +- As Convenções Semânticas são [estáveis, mas sujeitas a evolução][]: embora isso + não cause problemas funcionais, pode ser necessário atualizar sua instrumentação + de vez em quando. Mantê-la em um plugin de pré-visualização ou no repositório contrib + do OpenTelemetry pode ajudar a manter as convenções atualizadas sem causar mudanças + que possam impactar seus usuários. + + [estáveis, mas sujeitas a evolução]: /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability + +## O que instrumentar + +### APIs públicas + +As APIs públicas são boas candidatas para rastreamento: os intervalos criados para chamadas de APIs públicas permitem aos utilizadores mapear a telemetria para o código da aplicação, compreender a duração e o resultado das chamadas de biblioteca. Quais chamadas rastrear: + +- métodos públicos que fazem chamadas de rede internamente ou operações locais que demoram muito tempo e podem falhar (por exemplo, IO) +- manipuladores que processam requisições ou mensagens + +**Exemplo de instrumentação:** + +```java +private static Tracer tracer = getTracer(TracerProvider.noop()); + +public static void setTracerProvider(TracerProvider tracerProvider) { + tracer = getTracer(tracerProvider); +} + +private static Tracer getTracer(TracerProvider tracerProvider) { + return tracerProvider.getTracer("demo-db-client", "0.1.0-beta1"); +} + +private Response selectWithTracing(Query query) { + // check out conventions for guidance on trecho names and attributes + trecho trecho = tracer.spanBuilder(String.format("SELECT %s.%s", dbName, collectionName)) + .setSpanKind(SpanKind.CLIENT) + .setAttribute("db.name", dbName) + ... + .startSpan(); + + // makes trecho active and allows correlating logs and nest trechos + try (Scope unused = trecho.makeCurrent()) { + Response response = query.runWithRetries(); + if (response.isSuccessful()) { + trecho.setStatus(StatusCode.OK); + } + + if (trecho.isRecording()) { + // populate response attributes for response codes and other information + } + } catch (Exception e) { + trecho.recordException(e); + trecho.setStatus(StatusCode.ERROR, e.getClass().getSimpleName()); + throw e; + } finally { + trecho.end(); + } +} +``` + +Siga as convenções para popular os atributos! Se não houver nenhuma aplicável, verifique +as [convenções gerais](/docs/specs/semconv/general/attributes/). + +### Rede aninhada e outros trechos + +Chamadas de rede são normalmente rastreadas com autoinstrumentações OpenTelemetry +através da implementação do cliente correspondente. + +![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-trechos.svg) + +Se o OpenTelemetry não suportar o rastreio do seu cliente de rede, use seu próprio critério. +Aqui estão algumas considerações para ajudar: + +- O rastreamento de chamadas de rede melhoraria a observabilidade para os usuários ou sua capacidade de apoiá-los? +- Sua biblioteca é um módulo sobre uma API RPC pública e documentada? Os usuários precisariam obter suporte do serviço subjacente em caso de problemas? + - instrumente a biblioteca e certifique-se de rastrear tentativas de rede individuais +- Rastrear essas chamadas com trechos seria muito verboso? Ou teria um impacto perceptível no desempenho? + - use logs com níveis de verbosidade ou eventos de trecho: os logs podem ser correlacionados ao pai (chamadas da API pública), enquanto os eventos de trecho devem ser configurados no trecho da API pública. + - se forem necessários trechos (para carregar e propagar o contexto de rastreamento único), coloque-os atrás de uma opção de configuração e desative-os por padrão. + +Se o OpenTelemetry já suporta o rastreamento das suas chamadas de rede, provavelmente você não vai querer duplicar isso. Pode haver algumas exceções: + +- para dar suporte aos usuários sem autoinstrumentação (que pode não funcionar em certos ambientes ou os usuários podem ter preocupações com monkey-patching) +- para permitir protocolos personalizados (legados) de correlação e propagação de contexto com o serviço subjacente +- enriquecer os trechos RPC com informações essenciais específicas da biblioteca/serviço que não são cobertas pela autoinstrumentação + +AVISO: A solução genérica para evitar duplicação está em desenvolvimento 🚧. + +### Eventos + +Rastros são um tipo de sinal que suas aplicações podem emitir. Eventos (ou logs) e rastros se complementam, não se duplicam. Sempre que você tiver algo que deve ter um nível de verbosidade, logs são uma escolha melhor do que rastros. + +É provável que sua aplicação já use logging ou algum módulo similar. Seu módulo pode já ter integração com OpenTelemetry — para descobrir, consulte o [registro](/ecosystem/registry/). As integrações geralmente adicionam o contexto de rastreamento ativo em todos os logs, permitindo que os usuários os correlacionem. + +Se sua linguagem e ecossistema não têm suporte comum para logging, use [eventos de trecho][] para compartilhar detalhes adicionais da aplicação. Eventos podem ser mais convenientes se você quiser adicionar atributos também. + +Como regra geral, use eventos ou logs para dados detalhados em vez de trechos. Sempre anexe eventos à instância de trecho criada pela sua instrumentação. Evite usar o trecho ativo, se possível, pois você não controla a que ele se refere. + +## Propagação de contexto + +### Extraindo contexto + +Se você trabalha em uma biblioteca ou serviço que recebe chamadas de upstream, como um framework web ou um consumidor de mensagens, você deve extrair o contexto da solicitação/mensagem recebida. O OpenTelemetry fornece a API `Propagator`, que oculta padrões específicos de propagação e lê o contexto de rastreamento a partir da comunicação. Em um caso de uma única resposta, há apenas um contexto na comunicação, que se torna o pai do novo trecho criado pela biblioteca. + +Depois de criar um trecho, você deve passar o novo contexto de rastreamento para o código da aplicação (função de retorno ou manipulador), tornando o trecho ativo; se possível, você deve fazer isso de forma explícita. + +```java +// extract the context +Context extractedContext = propagator.extract(Context.current(), httpExchange, getter); +trecho trecho = tracer.spanBuilder("receive") + .setSpanKind(SpanKind.SERVER) + .setParent(extractedContext) + .startSpan(); + +// make trecho active so any nested telemetry is correlated +try (Scope unused = trecho.makeCurrent()) { + userCode(); +} catch (Exception e) { + trecho.recordException(e); + trecho.setStatus(StatusCode.ERROR); + throw e; +} finally { + trecho.end(); +} +``` + +Aqui estão os +[exemplos completos de extração de contexto em Java](/docs/languages/java/instrumentation/#context-propagation), +confira a documentação do OpenTelemetry da sua linguagem. + +No caso de um sistema de mensageria, você pode receber mais de uma mensagem de uma só vez. As mensagens recebidas se tornam +[_links_](/docs/languages/java/instrumentation/#create-trechos-with-links) no trecho que você cria. Consulte as +[convenções de mensageria](/docs/specs/semconv/messaging/messaging-trechos/) para mais detalhes (AVISO: as convenções de mensageria estão +[em construção](https://github.com/open-telemetry/oteps/pull/173) 🚧). + +### Injetando contexto + +Quando você faz uma chamada de saída, geralmente você vai querer propagar o contexto para o serviço subsequente. 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. Pode haver outros casos em que você queira injetar contexto, por exemplo, ao criar mensagens para processamento assíncrono. + +```java +trecho trecho = tracer.spanBuilder("send") + .setSpanKind(SpanKind.CLIENT) + .startSpan(); + +// make trecho active so any nested telemetry is correlated +// even network calls might have nested layers of trechos, logs or events +try (Scope unused = trecho.makeCurrent()) { + // inject the context + propagator.inject(Context.current(), transportLayer, setter); + send(); +} catch (Exception e) { + trecho.recordException(e); + trecho.setStatus(StatusCode.ERROR); + throw e; +} finally { + trecho.end(); +} +``` + +Aqui está o +[exemplo completo de injeção de contexto em Java](/docs/languages/java/instrumentation/#context-propagation). + +Pode haver algumas exceções: + +- o serviço subsequente não suporta metadados ou proíbe campos desconhecidos +- o serviço subsequente não define protocolos de correlação. É possível que alguma versão futura do serviço suporte a propagação de contexto compatível? Neste caso, injete o contexto! +- o serviço subsequente suporta um protocolo de correlação personalizado. + - faça o melhor possível com um propagador personalizado: use o contexto de rastreamento do OpenTelemetry se for compatível. + - ou gere e adicione IDs de correlação personalizados no trecho. + +### In-process + +- **Torne seus trechos ativos** (também conhecidos como atuais): isso permite correlacionar trechos com logs e quaisquer autoinstrumentações aninhadas. +- Se a biblioteca tiver uma noção de contexto, suporte a propagação opcional de contexto de rastreamento explícito _além_ dos trechos ativos. + - coloque os trechos (contexto de rastreamento) criados pela biblioteca explicitamente no contexto e documente como acessá-los. + - permita que os usuários passem o contexto de rastreamento no seu contexto. +- Dentro da biblioteca, propague o contexto de rastreamento explicitamente - os trechos ativos podem mudar durante as chamadas de retorno! + - capture o contexto ativo dos usuários na superfície da API pública assim que possível e use-o como contexto pai para seus trechos. + - passe o contexto ao redor e adicione atributos, exceções e eventos nas instâncias explicitamente propagadas. + - isso é essencial se você iniciar threads explicitamente, realizar processamento em segundo plano ou outras atividades que possam ser afetadas pelas limitações de fluxo de contexto assíncrono na sua linguagem. + +## Misc + +### Registro de instrumentação + +Por favor, adicione sua biblioteca de instrumentação ao +[registro do OpenTelemetry](/ecosystem/registry/), para que os usuários possam encontrá-la. + +### Desempenho + +A API do OpenTelemetry é autônma e muito eficiente quando não há SDK na +aplicação. Quando o SDK do OpenTelemetry é configurado, ele +[consome recursos vinculados](/docs/specs/otel/performance/). + +Aplicações do mundo real, especialmente em grande escala, frequentemente têm a amostragem baseada em cabeçalho configurada. Trechos descartados são baratos e você pode verificar se o trecho está gravando, para evitar alocações extras e cálculos potencialmente caros ao popular atributos. + +```java +// some attributes are important for sampling, they should be provided at creation time +trecho trecho = tracer.spanBuilder(String.format("SELECT %s.%s", dbName, collectionName)) + .setSpanKind(SpanKind.CLIENT) + .setAttribute("db.name", dbName) + ... + .startSpan(); + +// other attributes, especially those that are expensive to calculate +// should be added if trecho is recording +if (trecho.isRecording()) { + trecho.setAttribute("db.statement", sanitize(query.statement())) +} +``` + +### Tratamento de erros + +A API do OpenTelemetry é tolerante em tempo de execução - não falha em argumentos inválidos, nunca lança exceções e engole as exceções. Dessa forma, os 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 + +Como o OpenTelemetry possui uma variedade de autoinstrumentações, é útil testar como sua instrumentação interage com outras telemetrias: solicitações recebidas, solicitações enviadas, 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 exibidas. + +Para testes unitários, você geralmente pode usar mocks ou fakes `SpanProcessor` e `SpanExporter`. + +```java +@Test +public void checkInstrumentation() { + SpanExporter exporter = new TestExporter(); + + Tracer tracer = OpenTelemetrySdk.builder() + .setTracerProvider(SdkTracerProvider.builder() + .addSpanProcessor(SimpleSpanProcessor.create(exporter)).build()).build() + .getTracer("test"); + // run test ... + + validateSpans(exporter.exportedSpans); +} + +class TestExporter implements SpanExporter { + public final List exportedSpans = Collections.synchronizedList(new ArrayList<>()); + + @Override + public CompletableResultCode export(Collection trechos) { + exportedSpans.addAll(trechos); + return CompletableResultCode.ofSuccess(); + } + ... +} +``` + +[bibliotecas de instrumentação]: /docs/specs/otel/overview/#instrumentation-libraries +[eventos de trecho]: /docs/specs/otel/trace/api/#add-events diff --git a/content/pt/docs/concepts/instrumentation/nested-spans.svg b/content/pt/docs/concepts/instrumentation/nested-spans.svg new file mode 100644 index 000000000000..8178ad001e9c --- /dev/null +++ b/content/pt/docs/concepts/instrumentation/nested-spans.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/pt/docs/concepts/instrumentation/zero-code.md b/content/pt/docs/concepts/instrumentation/zero-code.md new file mode 100644 index 000000000000..b4ba315a83b4 --- /dev/null +++ b/content/pt/docs/concepts/instrumentation/zero-code.md @@ -0,0 +1,35 @@ +--- +title: Autoinstrumentação +description: >- + Aprenda a adicionar observabilidade a uma aplicação sem a necessidade de escrever + código +weight: 10 +aliases: [automatic] +default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f +--- + +Em um time de [operaçõe](/docs/getting-started/ops/), você pode querer adicionar observabilidade a uma ou mais aplicações sem precisar editar o código-fonte. O OpenTelemetry permite que você tenha rapidamente observabilidade para um serviço sem precisar usar a API e SDK do OpenTelemetry para instrumentação baseada em código. + +A autoinstrumentação adiciona as capacidades da API e SDK do OpenTelemetry à sua aplicação, geralmente como uma instalação de agente ou semelhante a um agente. Os mecanismos específicos envolvidos podem variar de acordo com a linguagem, desde manipulação de bytecode, monkey patching ou eBPF para injetar chamadas à API e SDK do OpenTelemetry em sua aplicação. + +Normalmente, a autoinstrumentação adiciona instrumentação para as bibliotecas que você está usando. Isso significa que as chamadas de requisições e respostas, chamadas de banco de dados, chamadas de fila de mensagens e assim por diante são instrumentadas. No entanto, o código da sua aplicação geralmente não é instrumentado. Para instrumentar seu código, você precisará usar a instrumentação baseada em código. + +Além disso, a autoinstrumentação permite que você configure as Bibliotecas de Instrumentação e os Exporters carregados. + +Você pode configurar a autoinstrumentação por meio de variáveis de ambiente e outros mecanismos específicos da linguagem, como propriedades do sistema ou argumentos passados para métodos de inicialização. Para começar, você só precisa configurar um nome de serviço para que você possa identificar o serviço no backend de observabilidade de sua escolha. + +Outras opções de configuração estão disponíveis, incluindo: + +- Configuração específica da fonte de dados +- Configuração do exportador +- Configuração do propagador +- Configuração de recursos + +A instrumentação automática está disponível para as seguintes linguagens: + +- [.NET](/docs/zero-code/net/) +- [Go](/docs/zero-code/go) +- [Java](/docs/zero-code/java/) +- [JavaScript](/docs/zero-code/js/) +- [PHP](/docs/zero-code/php/) +- [Python](/docs/zero-code/python/) From 9c28b85200873ddef591ec34236af2b7dbae4d4b Mon Sep 17 00:00:00 2001 From: Marcelo Baptista Date: Sat, 24 Aug 2024 16:19:26 -0300 Subject: [PATCH 2/4] fix: broken links --- content/pt/docs/concepts/instrumentation/libraries.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/pt/docs/concepts/instrumentation/libraries.md b/content/pt/docs/concepts/instrumentation/libraries.md index 2e215d3e47d2..b777ec4de505 100644 --- a/content/pt/docs/concepts/instrumentation/libraries.md +++ b/content/pt/docs/concepts/instrumentation/libraries.md @@ -144,7 +144,7 @@ as [convenções gerais](/docs/specs/semconv/general/attributes/). Chamadas de rede são normalmente rastreadas com autoinstrumentações OpenTelemetry através da implementação do cliente correspondente. -![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-trechos.svg) +![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-span.svg) Se o OpenTelemetry não suportar o rastreio do seu cliente de rede, use seu próprio critério. Aqui estão algumas considerações para ajudar: @@ -207,8 +207,8 @@ Aqui estão os confira a documentação do OpenTelemetry da sua linguagem. No caso de um sistema de mensageria, você pode receber mais de uma mensagem de uma só vez. As mensagens recebidas se tornam -[_links_](/docs/languages/java/instrumentation/#create-trechos-with-links) no trecho que você cria. Consulte as -[convenções de mensageria](/docs/specs/semconv/messaging/messaging-trechos/) para mais detalhes (AVISO: as convenções de mensageria estão +[_links_](/docs/languages/java/instrumentation/#create-spans-with-links) no trecho que você cria. Consulte as +[convenções de mensageria](/docs/specs/semconv/messaging/messaging-spans/) para mais detalhes (AVISO: as convenções de mensageria estão [em construção](https://github.com/open-telemetry/oteps/pull/173) 🚧). ### Injetando contexto @@ -266,7 +266,7 @@ Por favor, adicione sua biblioteca de instrumentação ao ### Desempenho -A API do OpenTelemetry é autônma e muito eficiente quando não há SDK na +A API do OpenTelemetry é autônoma e muito eficiente quando não há SDK na aplicação. Quando o SDK do OpenTelemetry é configurado, ele [consome recursos vinculados](/docs/specs/otel/performance/). From 05fb8cb1c641c5a0e7d81ce95056c38b51ec8a38 Mon Sep 17 00:00:00 2001 From: Marcelo Baptista Date: Sat, 24 Aug 2024 16:25:14 -0300 Subject: [PATCH 3/4] fix: nested-spans.svg --- content/pt/docs/concepts/instrumentation/libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/pt/docs/concepts/instrumentation/libraries.md b/content/pt/docs/concepts/instrumentation/libraries.md index b777ec4de505..eb132e8b949e 100644 --- a/content/pt/docs/concepts/instrumentation/libraries.md +++ b/content/pt/docs/concepts/instrumentation/libraries.md @@ -144,7 +144,7 @@ as [convenções gerais](/docs/specs/semconv/general/attributes/). Chamadas de rede são normalmente rastreadas com autoinstrumentações OpenTelemetry através da implementação do cliente correspondente. -![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-span.svg) +![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-spans.svg) Se o OpenTelemetry não suportar o rastreio do seu cliente de rede, use seu próprio critério. Aqui estão algumas considerações para ajudar: From c576ebb70e2964564d3402423f8068d4201c7686 Mon Sep 17 00:00:00 2001 From: Marcelo Baptista Date: Sat, 24 Aug 2024 16:30:18 -0300 Subject: [PATCH 4/4] fix: prettify --- .../docs/concepts/instrumentation/_index.md | 53 +++- .../concepts/instrumentation/code-based.md | 55 +++- .../concepts/instrumentation/libraries.md | 295 +++++++++++++----- .../concepts/instrumentation/zero-code.md | 40 ++- 4 files changed, 325 insertions(+), 118 deletions(-) diff --git a/content/pt/docs/concepts/instrumentation/_index.md b/content/pt/docs/concepts/instrumentation/_index.md index 77b5a2fe9439..110c07805ca4 100644 --- a/content/pt/docs/concepts/instrumentation/_index.md +++ b/content/pt/docs/concepts/instrumentation/_index.md @@ -6,30 +6,55 @@ weight: 15 default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f --- -Para tornar um sistema observável, ele deve ser **instrumentado**: Ou seja, o código dos componentes do sistema devem emitir [rastros](/docs/concepts/signals/traces/), +Para tornar um sistema observável, ele deve ser **instrumentado**: Ou seja, o +código dos componentes do sistema devem emitir +[rastros](/docs/concepts/signals/traces/), [métricas](/docs/concepts/signals/metrics/), e [logs](/docs/concepts/signals/logs/). -Usando o OpenTelemetry, você pode instrumentar seu código de duas maneiras principais: +Usando o OpenTelemetry, você pode instrumentar seu código de duas maneiras +principais: -1. [Soluções baseadas em código](/docs/concepts/instrumentation/code-based) através das +1. [Soluções baseadas em código](/docs/concepts/instrumentation/code-based) + através das [APIs e SDKs oficiais para a maioria das linguagens](/docs/languages/) 2. [Soluções autoinstrumentadas](/docs/concepts/instrumentation/zero-code/) -Soluções **baseadas em código** permitem obter uma visão mais profunda e rica da telemetria da própria aplicação. Elas permitem que você use a API do OpenTelemetry para gerar telemetria a partir da sua aplicação, o que atua como um complemento essencial para a telemetria gerada por soluções autoinstrumentadas. +Soluções **baseadas em código** permitem obter uma visão mais profunda e rica da +telemetria da própria aplicação. Elas permitem que você use a API do +OpenTelemetry para gerar telemetria a partir da sua aplicação, o que atua como +um complemento essencial para a telemetria gerada por soluções +autoinstrumentadas. -Soluções **autoinstrumentadas** são ótimas para começar ou quando você não pode modificar a aplicação da qual você precisa obter telemetria. Elas fornecem uma rica telemetria a partir das bibliotecas que você usa e/ou do ambiente no qual sua aplicação é executada. Outra -forma de pensar é que elas fornecem informações sobre o que está acontecendo _nas bordas_ da sua aplicação. +Soluções **autoinstrumentadas** são ótimas para começar ou quando você não pode +modificar a aplicação da qual você precisa obter telemetria. Elas fornecem uma +rica telemetria a partir das bibliotecas que você usa e/ou do ambiente no qual +sua aplicação é executada. Outra forma de pensar é que elas fornecem informações +sobre o que está acontecendo _nas bordas_ da sua aplicação. Você pode usar ambas as soluções simultaneamente. ## Benefícios adicionais do OpenTelemetry -O OpenTelemetry oferece mais do que apenas soluções de telemetria autoinstrumentadas e baseadas em código. Também fazem parte do OpenTelemetry: - -- As bibliotecas podem aproveitar a API do OpenTelemetry como uma dependência, o que não terá impacto nas aplicações que usam essa biblioteca, a menos que o SDK do OpenTelemetry seja importado. -- Para cada [sinal](/docs/concepts/signals) (rastros, métricas, logs), você tem vários métodos à sua disposição para criar, processar e exportá-los. -- Com a [propagação de contexto](/docs/concepts/context-propagation) incorporada nas implementações, você pode correlacionar sinais independentemente de onde eles são gerados. -- [Recursos](/docs/concepts/resources) e [Escopos de Instrumentação](/docs/concepts/instrumentation-scope) permitem agrupar sinais por diferentes entidades, como o [host](/docs/specs/semconv/resource/host/), [sistema operacional](/docs/specs/semconv/resource/os/) ou [cluster K8s](/docs/specs/semconv/resource/k8s/#cluster). -- Cada implementação específica de linguagem da API e SDK seguem os requisitos e expectativas da [especificação do OpenTelemetry](/docs/specs/otel/). -- As [Convenções Semânticas](/docs/concepts/semantic-conventions) fornecem um esquema de nomenclatura comum que pode ser usado para padronização em bases de código e plataformas. +O OpenTelemetry oferece mais do que apenas soluções de telemetria +autoinstrumentadas e baseadas em código. Também fazem parte do OpenTelemetry: + +- As bibliotecas podem aproveitar a API do OpenTelemetry como uma dependência, o + que não terá impacto nas aplicações que usam essa biblioteca, a menos que o + SDK do OpenTelemetry seja importado. +- Para cada [sinal](/docs/concepts/signals) (rastros, métricas, logs), você tem + vários métodos à sua disposição para criar, processar e exportá-los. +- Com a [propagação de contexto](/docs/concepts/context-propagation) incorporada + nas implementações, você pode correlacionar sinais independentemente de onde + eles são gerados. +- [Recursos](/docs/concepts/resources) e + [Escopos de Instrumentação](/docs/concepts/instrumentation-scope) permitem + agrupar sinais por diferentes entidades, como o + [host](/docs/specs/semconv/resource/host/), + [sistema operacional](/docs/specs/semconv/resource/os/) ou + [cluster K8s](/docs/specs/semconv/resource/k8s/#cluster). +- Cada implementação específica de linguagem da API e SDK seguem os requisitos e + expectativas da [especificação do OpenTelemetry](/docs/specs/otel/). +- As [Convenções Semânticas](/docs/concepts/semantic-conventions) fornecem um + esquema de nomenclatura comum que pode ser usado para padronização em bases de + código e plataformas. diff --git a/content/pt/docs/concepts/instrumentation/code-based.md b/content/pt/docs/concepts/instrumentation/code-based.md index d8b7d8ec7b31..c7e67860698f 100644 --- a/content/pt/docs/concepts/instrumentation/code-based.md +++ b/content/pt/docs/concepts/instrumentation/code-based.md @@ -1,6 +1,7 @@ --- title: Instrumentação baseada em Código -description: Aprenda o essencial para configurar a instrumentação baseada em código +description: + Aprenda o essencial para configurar a instrumentação baseada em código weight: 20 aliases: [manual] cSpell:ignore: proxying @@ -9,24 +10,62 @@ default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f ## Importe a API e SDK do OpenTelemetry -Primeiro, você precisará importar o OpenTelemetry para o código do seu serviço. Se você estiver desenvolvendo uma biblioteca ou algum outro componente que será consumido por um binário executável, então você só precisará depender da API. Se o seu artefato for um processo ou serviço independente, então você precisará depender tanto da API quanto do SDK. Para saber mais informações sobre a API e SDK do OpenTelemetry, consulte a [especificação](/docs/specs/otel/). +Primeiro, você precisará importar o OpenTelemetry para o código do seu serviço. +Se você estiver desenvolvendo uma biblioteca ou algum outro componente que será +consumido por um binário executável, então você só precisará depender da API. Se +o seu artefato for um processo ou serviço independente, então você precisará +depender tanto da API quanto do SDK. Para saber mais informações sobre a API e +SDK do OpenTelemetry, consulte a [especificação](/docs/specs/otel/). ## Configure a API do OpenTelemetry -Para criar rastros ou métricas, você precisará primeiro criar um rastreador e/ou um provedor de métricas. Em geral, recomendamos que o SDK forneça um provedor padrão único para esses objetos. Em seguida, você obterá uma instância de rastreador ou medidor desse provedor e dará a ele um nome e uma versão. O nome que você escolher aqui deve identificar exatamente o que está sendo instrumentado - se você estiver escrevendo uma biblioteca, por exemplo, então você deve nomeá-la com o nome da sua biblioteca (por exemplo, `com.example.myLibrary`), pois esse nome irá agrupar todos os spans ou eventos de métricas produzidos. Também é recomendado que você forneça uma string de versão (por exemplo, `semver:1.0.0`) que corresponda à versão atual da sua biblioteca ou serviço. +Para criar rastros ou métricas, você precisará primeiro criar um rastreador e/ou +um provedor de métricas. Em geral, recomendamos que o SDK forneça um provedor +padrão único para esses objetos. Em seguida, você obterá uma instância de +rastreador ou medidor desse provedor e dará a ele um nome e uma versão. O nome +que você escolher aqui deve identificar exatamente o que está sendo +instrumentado - se você estiver escrevendo uma biblioteca, por exemplo, então +você deve nomeá-la com o nome da sua biblioteca (por exemplo, +`com.example.myLibrary`), pois esse nome irá agrupar todos os spans ou eventos +de métricas produzidos. Também é recomendado que você forneça uma string de +versão (por exemplo, `semver:1.0.0`) que corresponda à versão atual da sua +biblioteca ou serviço. ## Configure o SDK do OpenTelemetry -Se você estiver desenvolvendo um processo de serviço, também precisará configurar o SDK com as opções apropriadas para exportar seus dados de telemetria para algum backend de análise. Recomendamos que essa configuração seja feita programaticamente por meio de um arquivo de configuração ou algum outro mecanismo. Também existem opções de ajuste específicas de cada linguagem das quais você pode se beneficiar. +Se você estiver desenvolvendo um processo de serviço, também precisará +configurar o SDK com as opções apropriadas para exportar seus dados de +telemetria para algum backend de análise. Recomendamos que essa configuração +seja feita programaticamente por meio de um arquivo de configuração ou algum +outro mecanismo. Também existem opções de ajuste específicas de cada linguagem +das quais você pode se beneficiar. ## Crie Dados de Telemetria -Depois de configurar a API e o SDK, você poderá criar rastros e eventos de métricas por meio dos objetos rastreador e medidor que você obteve do provedor. Utilize Bibliotecas de Instrumentação para suas dependências - confira o [registro](/ecosystem/registry/) ou o repositório da linguagem escolhida para ter mais informações sobre elas. +Depois de configurar a API e o SDK, você poderá criar rastros e eventos de +métricas por meio dos objetos rastreador e medidor que você obteve do provedor. +Utilize Bibliotecas de Instrumentação para suas dependências - confira o +[registro](/ecosystem/registry/) ou o repositório da linguagem escolhida para +ter mais informações sobre elas. ## Exporte os Dados -Depois de criar os dados de telemetria, você vai querer enviá-los para algum lugar. O OpenTelemetry suporta dois métodos principais de exportação de dados do seu processo para um backend de análise, seja diretamente de um processo ou por meio do [OpenTelemetry Collector](/docs/collector). +Depois de criar os dados de telemetria, você vai querer enviá-los para algum +lugar. O OpenTelemetry suporta dois métodos principais de exportação de dados do +seu processo para um backend de análise, seja diretamente de um processo ou por +meio do [OpenTelemetry Collector](/docs/collector). -A exportação in-process requer que você importe e dependa de um ou mais _exporters_, bibliotecas que traduzem os objetos de trecho e métrica em memória do OpenTelemetry para o formato apropriado para ferramentas de análise de telemetria como Jaeger ou Prometheus. Além disso, o OpenTelemetry suporta um protocolo de comunicação conhecido como `OTLP`, que é suportado por todos os SDKs do OpenTelemetry. Esse protocolo pode ser usado para enviar dados para o OpenTelemetry Collector, um processo binário independente que pode ser executado como um proxy ou sidecar para suas instâncias de serviço ou em um host separado. O Collector pode então ser configurado para encaminhar e exportar esses dados para as suas ferramentas de análise preferidas. +A exportação in-process requer que você importe e dependa de um ou mais +_exporters_, bibliotecas que traduzem os objetos de trecho e métrica em memória +do OpenTelemetry para o formato apropriado para ferramentas de análise de +telemetria como Jaeger ou Prometheus. Além disso, o OpenTelemetry suporta um +protocolo de comunicação conhecido como `OTLP`, que é suportado por todos os +SDKs do OpenTelemetry. Esse protocolo pode ser usado para enviar dados para o +OpenTelemetry Collector, um processo binário independente que pode ser executado +como um proxy ou sidecar para suas instâncias de serviço ou em um host separado. +O Collector pode então ser configurado para encaminhar e exportar esses dados +para as suas ferramentas de análise preferidas. -Além de ferramentas de código aberto como Jaeger ou Prometheus, uma lista crescente de empresas suporta a ingestão de dados de telemetria do OpenTelemetry. Para mais detalhes, consulte [Fornecedores](/ecosystem/vendors/). +Além de ferramentas de código aberto como Jaeger ou Prometheus, uma lista +crescente de empresas suporta a ingestão de dados de telemetria do +OpenTelemetry. Para mais detalhes, consulte [Fornecedores](/ecosystem/vendors/). diff --git a/content/pt/docs/concepts/instrumentation/libraries.md b/content/pt/docs/concepts/instrumentation/libraries.md index eb132e8b949e..117fa5c42393 100644 --- a/content/pt/docs/concepts/instrumentation/libraries.md +++ b/content/pt/docs/concepts/instrumentation/libraries.md @@ -6,93 +6,156 @@ weight: 40 default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f --- -O OpenTelemetry fornece [bibliotecas de instrumentação][] para muitas bibliotecas, o que geralmente é feito por meio de hooks de biblioteca ou modificando o código da biblioteca (monkey-patching). - -A instrumentação nativa de bibliotecas com o OpenTelemetry oferece melhor observabilidade e experiência para os desenvolvedores, eliminando a necessidade de as bibliotecas exporem e documentarem hooks: - -- hooks personalizados de logs podem ser substituídos por APIs comuns e fáceis de usar do OpenTelemetry, os usuários interagem apenas com o OpenTelemetry -- Rastros, logs e métricas do código da biblioteca e da aplicação são correlacionados e coerentes -- Convenções comuns permitem que os usuários obtenham telemetria semelhante e consistente dentro da mesma tecnologia e entre bibliotecas e linguagens -- Os sinais de telemetria podem ser ajustados (filtrados, processados, agregados) para diversos cenários de consumo usando uma ampla variedade de pontos de extensão do OpenTelemetry bem documentados. +O OpenTelemetry fornece [bibliotecas de instrumentação][] para muitas +bibliotecas, o que geralmente é feito por meio de hooks de biblioteca ou +modificando o código da biblioteca (monkey-patching). + +A instrumentação nativa de bibliotecas com o OpenTelemetry oferece melhor +observabilidade e experiência para os desenvolvedores, eliminando a necessidade +de as bibliotecas exporem e documentarem hooks: + +- hooks personalizados de logs podem ser substituídos por APIs comuns e fáceis + de usar do OpenTelemetry, os usuários interagem apenas com o OpenTelemetry +- Rastros, logs e métricas do código da biblioteca e da aplicação são + correlacionados e coerentes +- Convenções comuns permitem que os usuários obtenham telemetria semelhante e + consistente dentro da mesma tecnologia e entre bibliotecas e linguagens +- Os sinais de telemetria podem ser ajustados (filtrados, processados, + agregados) para diversos cenários de consumo usando uma ampla variedade de + pontos de extensão do OpenTelemetry bem documentados. ## Convenções Semânticas Confira as [convenções semânticas](/docs/specs/semconv/general/trace/) -disponíveis, que abrangem frameworks web, clientes RPC, bancos de dados, clientes de mensageria, componentes de infraestrutura e muito mais! - -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 garantem consistência na instrumentação: os usuários que trabalham com telemetria não precisam aprender os detalhes específicos de cada biblioteca, e os fornecedores de observabilidade podem construir experiências para uma ampla variedade de tecnologias (por exemplo, bancos de dados ou sistemas de mensageria). Quando as bibliotecas seguem as convenções, muitos cenários podem ser habilitados automaticamente, sem a necessidade de intervenção ou configuração por parte do usuário. - -As convenções semânticas estão sempre evoluindo e novas estão constantemente sendo adicionadas. Se não houver convenções para sua biblioteca, considere +disponíveis, que abrangem frameworks web, clientes RPC, bancos de dados, +clientes de mensageria, componentes de infraestrutura e muito mais! + +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 garantem consistência na instrumentação: os +usuários que trabalham com telemetria não precisam aprender os detalhes +específicos de cada biblioteca, e os fornecedores de observabilidade podem +construir experiências para uma ampla variedade de tecnologias (por exemplo, +bancos de dados ou sistemas de mensageria). Quando as bibliotecas seguem as +convenções, muitos cenários podem ser habilitados automaticamente, sem a +necessidade de intervenção ou configuração por parte do usuário. + +As convenções semânticas estão sempre evoluindo e novas estão constantemente +sendo adicionadas. Se não houver convenções para sua biblioteca, considere [adicionar novas.](https://github.com/open-telemetry/semantic-conventions/issues). -Tenha atenção especial aos nomes dos trechos; procure usar nomes significativos e considere a cardinalidade ao defini-los. +Tenha atenção especial aos nomes dos trechos; procure usar nomes significativos +e considere a cardinalidade ao defini-los. -Há um atributo [`schema_url`](/docs/specs/otel/schemas/#schema-url) que pode ser usado para registrar qual versão das convenções semânticas está sendo utilizada. Defina este atributo, sempre que possível. +Há um atributo [`schema_url`](/docs/specs/otel/schemas/#schema-url) que pode ser +usado para registrar qual versão das convenções semânticas está sendo utilizada. +Defina este atributo, sempre que possível. Se você tiver algum feedback ou quiser adicionar uma nova convenção, contribua! -[Slack sobre Instrumentação](https://cloud-native.slack.com/archives/C01QZFGMLQ7) ou o +[Slack sobre Instrumentação](https://cloud-native.slack.com/archives/C01QZFGMLQ7) +ou o [repositório da Especificação](https://github.com/open-telemetry/opentelemetry-specification) são ótimos pontos de partida! ### Definindo trechos -Considere sua biblioteca sob a perspectiva de um usuário e o que ele gostaria de 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 de sua aplicação do que nos aspectos internos da biblioteca. Pense sobre que informações podem ser úteis para analisar o uso da sua biblioteca e sobre a melhor forma de modelar esses dados. Alguns pontos a considerar são: +Considere sua biblioteca sob a perspectiva de um usuário e o que ele gostaria de +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 de sua aplicação do que nos aspectos +internos da biblioteca. Pense sobre que informações podem ser úteis para +analisar o uso da sua biblioteca e sobre a melhor forma de modelar esses dados. +Alguns pontos a considerar são: - trechos e hierarquias de trechos - Atributos numéricos em trechos (como alternativa a métricas agregadas) - Eventos de trechos - Métricas agregadas -Por exemplo, se sua biblioteca faz requisições a um banco de dados, crie trechos apenas para a requisição lógica ao banco de dados. As requisições físicas pela rede devem ser instrumentadas nas bibliotecas que implementam essa funcionalidade. Além disso, prefira capturar atividades adicionais, como a serialização de objetos/dados, como eventos de trechos, em vez de criar trechos separados para essas atividades. +Por exemplo, se sua biblioteca faz requisições a um banco de dados, crie trechos +apenas para a requisição lógica ao banco de dados. As requisições físicas pela +rede devem ser instrumentadas nas bibliotecas que implementam essa +funcionalidade. Além disso, prefira capturar atividades adicionais, como a +serialização de objetos/dados, como eventos de trechos, em vez de criar trechos +separados para essas atividades. Siga as convenções semânticas ao definir os atributos dos trechos. ## Quando **não** instrumentar -Algumas bibliotecas são clientes simples que envolvem chamadas de rede. É provável que o OpenTelemetry já tenha uma biblioteca de instrumentação para o cliente RPC subjacente (confira o [registro](/ecosystem/registry/)). Nesse caso, pode não ser necessário instrumentar a biblioteca que serve como camada adicional. Como regra geral, instrumente sua biblioteca apenas no seu próprio nível. +Algumas bibliotecas são clientes simples que envolvem chamadas de rede. É +provável que o OpenTelemetry já tenha uma biblioteca de instrumentação para o +cliente RPC subjacente (confira o [registro](/ecosystem/registry/)). Nesse caso, +pode não ser necessário instrumentar a biblioteca que serve como camada +adicional. Como regra geral, instrumente sua biblioteca apenas no seu próprio +nível. Não instrumente se: -- sua biblioteca for um proxy simples sobre APIs documentadas ou autoexplicativas -- _e_ o OpenTelemetry já tiver instrumentação para as chamadas de rede subjacentes -- _e_ e não houver convenções que sua biblioteca deva seguir para enriquecer a telemetria +- sua biblioteca for um proxy simples sobre APIs documentadas ou + autoexplicativas +- _e_ o OpenTelemetry já tiver instrumentação para as chamadas de rede + subjacentes +- _e_ e não houver convenções que sua biblioteca deva seguir para enriquecer a + telemetria -Se estiver em dúvida, não instrumente – é possível realizar a instrumentação mais tarde, caso necessário. +Se estiver em dúvida, não instrumente – é possível realizar a instrumentação +mais tarde, caso necessário. -Se optar por não instrumentar, pode ser útil fornecer uma forma de configurar os manipuladores do OpenTelemetry para a instância interna do seu cliente RPC. Isso é essencial em linguagens que não suportam instrumentação totalmente automática e ainda útil em outras. +Se optar por não instrumentar, pode ser útil fornecer uma forma de configurar os +manipuladores do OpenTelemetry para a instância interna do seu cliente RPC. Isso +é essencial em linguagens que não suportam instrumentação totalmente automática +e ainda útil em outras. -O restante deste documento oferece orientações sobre o que e como instrumentar, se optar por fazer. +O restante deste documento oferece orientações sobre o que e como instrumentar, +se optar por fazer. ## API do OpenTelemetry O primeiro passo é adicionar a dependência do pacote da API do OpenTelemetry. -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 a aplicação importe o SDK do OpenTelemetry, a instrumentação não terá efeito e não impactará o desempenho da aplicação. +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 a aplicação importe o SDK do OpenTelemetry, a +instrumentação não terá efeito e não impactará o desempenho da aplicação. **As bibliotecas devem usar apenas a API do OpenTelemetry.** -É compreensível estar preocupado com a adição de novas dependências, aqui estão algumas considerações para ajudar a minimizar problemas relacionados a dependências: - -- A API de Rastros do OpenTelemetry atingiu estabilidade no início de 2021, segue o - [Versionamento Semântico 2.0](/docs/specs/otel/versioning-and-stability/) e levamos a estabilidade da API a sério. -- Ao adicionar a dependência, use a versão estável mais antiga da API do OpenTelemetry (1.0.\*) e evite atualizá-la a menos que precise de novos recursos. -- Enquanto sua instrumentação se estabiliza, considere disponibilizá-la como um pacote separado, para que 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/oteps/blob/main/text/0155-external-modules.md#contrib-components), +É compreensível estar preocupado com a adição de novas dependências, aqui estão +algumas considerações para ajudar a minimizar problemas relacionados a +dependências: + +- A API de Rastros do OpenTelemetry atingiu estabilidade no início de 2021, + segue o + [Versionamento Semântico 2.0](/docs/specs/otel/versioning-and-stability/) e + levamos a estabilidade da API a sério. +- Ao adicionar a dependência, use a versão estável mais antiga da API do + OpenTelemetry (1.0.\*) e evite atualizá-la a menos que precise de novos + recursos. +- Enquanto sua instrumentação se estabiliza, considere disponibilizá-la como um + pacote separado, para que 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/oteps/blob/main/text/0155-external-modules.md#contrib-components), para que seja incluída com outras bibliotecas de instrumentação. -- As Convenções Semânticas são [estáveis, mas sujeitas a evolução][]: embora isso - não cause problemas funcionais, pode ser necessário atualizar sua instrumentação - de vez em quando. Mantê-la em um plugin de pré-visualização ou no repositório contrib - do OpenTelemetry pode ajudar a manter as convenções atualizadas sem causar mudanças - que possam impactar seus usuários. +- As Convenções Semânticas são [estáveis, mas sujeitas a evolução][]: embora + isso não cause problemas funcionais, pode ser necessário atualizar sua + instrumentação de vez em quando. Mantê-la em um plugin de pré-visualização ou + no repositório contrib do OpenTelemetry pode ajudar a manter as convenções + atualizadas sem causar mudanças que possam impactar seus usuários. - [estáveis, mas sujeitas a evolução]: /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability + [estáveis, mas sujeitas a evolução]: + /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability ## O que instrumentar ### APIs públicas -As APIs públicas são boas candidatas para rastreamento: os intervalos criados para chamadas de APIs públicas permitem aos utilizadores mapear a telemetria para o código da aplicação, compreender a duração e o resultado das chamadas de biblioteca. Quais chamadas rastrear: +As APIs públicas são boas candidatas para rastreamento: os intervalos criados +para chamadas de APIs públicas permitem aos utilizadores mapear a telemetria +para o código da aplicação, compreender a duração e o resultado das chamadas de +biblioteca. Quais chamadas rastrear: -- métodos públicos que fazem chamadas de rede internamente ou operações locais que demoram muito tempo e podem falhar (por exemplo, IO) +- métodos públicos que fazem chamadas de rede internamente ou operações locais + que demoram muito tempo e podem falhar (por exemplo, IO) - manipuladores que processam requisições ou mensagens **Exemplo de instrumentação:** @@ -136,51 +199,81 @@ private Response selectWithTracing(Query query) { } ``` -Siga as convenções para popular os atributos! Se não houver nenhuma aplicável, verifique -as [convenções gerais](/docs/specs/semconv/general/attributes/). +Siga as convenções para popular os atributos! Se não houver nenhuma aplicável, +verifique as [convenções gerais](/docs/specs/semconv/general/attributes/). ### Rede aninhada e outros trechos -Chamadas de rede são normalmente rastreadas com autoinstrumentações OpenTelemetry -através da implementação do cliente correspondente. +Chamadas de rede são normalmente rastreadas com autoinstrumentações +OpenTelemetry através da implementação do cliente correspondente. ![Base de dados aninhada e trechos HTTP na Jaeger UI](../nested-spans.svg) -Se o OpenTelemetry não suportar o rastreio do seu cliente de rede, use seu próprio critério. -Aqui estão algumas considerações para ajudar: - -- O rastreamento de chamadas de rede melhoraria a observabilidade para os usuários ou sua capacidade de apoiá-los? -- Sua biblioteca é um módulo sobre uma API RPC pública e documentada? Os usuários precisariam obter suporte do serviço subjacente em caso de problemas? - - instrumente a biblioteca e certifique-se de rastrear tentativas de rede individuais -- Rastrear essas chamadas com trechos seria muito verboso? Ou teria um impacto perceptível no desempenho? - - use logs com níveis de verbosidade ou eventos de trecho: os logs podem ser correlacionados ao pai (chamadas da API pública), enquanto os eventos de trecho devem ser configurados no trecho da API pública. - - se forem necessários trechos (para carregar e propagar o contexto de rastreamento único), coloque-os atrás de uma opção de configuração e desative-os por padrão. - -Se o OpenTelemetry já suporta o rastreamento das suas chamadas de rede, provavelmente você não vai querer duplicar isso. Pode haver algumas exceções: - -- para dar suporte aos usuários sem autoinstrumentação (que pode não funcionar em certos ambientes ou os usuários podem ter preocupações com monkey-patching) -- para permitir protocolos personalizados (legados) de correlação e propagação de contexto com o serviço subjacente -- enriquecer os trechos RPC com informações essenciais específicas da biblioteca/serviço que não são cobertas pela autoinstrumentação +Se o OpenTelemetry não suportar o rastreio do seu cliente de rede, use seu +próprio critério. Aqui estão algumas considerações para ajudar: + +- O rastreamento de chamadas de rede melhoraria a observabilidade para os + usuários ou sua capacidade de apoiá-los? +- Sua biblioteca é um módulo sobre uma API RPC pública e documentada? Os + usuários precisariam obter suporte do serviço subjacente em caso de problemas? + - instrumente a biblioteca e certifique-se de rastrear tentativas de rede + individuais +- Rastrear essas chamadas com trechos seria muito verboso? Ou teria um impacto + perceptível no desempenho? + - use logs com níveis de verbosidade ou eventos de trecho: os logs podem ser + correlacionados ao pai (chamadas da API pública), enquanto os eventos de + trecho devem ser configurados no trecho da API pública. + - se forem necessários trechos (para carregar e propagar o contexto de + rastreamento único), coloque-os atrás de uma opção de configuração e + desative-os por padrão. + +Se o OpenTelemetry já suporta o rastreamento das suas chamadas de rede, +provavelmente você não vai querer duplicar isso. Pode haver algumas exceções: + +- para dar suporte aos usuários sem autoinstrumentação (que pode não funcionar + em certos ambientes ou os usuários podem ter preocupações com monkey-patching) +- para permitir protocolos personalizados (legados) de correlação e propagação + de contexto com o serviço subjacente +- enriquecer os trechos RPC com informações essenciais específicas da + biblioteca/serviço que não são cobertas pela autoinstrumentação AVISO: A solução genérica para evitar duplicação está em desenvolvimento 🚧. ### Eventos -Rastros são um tipo de sinal que suas aplicações podem emitir. Eventos (ou logs) e rastros se complementam, não se duplicam. Sempre que você tiver algo que deve ter um nível de verbosidade, logs são uma escolha melhor do que rastros. +Rastros são um tipo de sinal que suas aplicações podem emitir. Eventos (ou logs) +e rastros se complementam, não se duplicam. Sempre que você tiver algo que deve +ter um nível de verbosidade, logs são uma escolha melhor do que rastros. -É provável que sua aplicação já use logging ou algum módulo similar. Seu módulo pode já ter integração com OpenTelemetry — para descobrir, consulte o [registro](/ecosystem/registry/). As integrações geralmente adicionam o contexto de rastreamento ativo em todos os logs, permitindo que os usuários os correlacionem. +É provável que sua aplicação já use logging ou algum módulo similar. Seu módulo +pode já ter integração com OpenTelemetry — para descobrir, consulte o +[registro](/ecosystem/registry/). As integrações geralmente adicionam o contexto +de rastreamento ativo em todos os logs, permitindo que os usuários os +correlacionem. -Se sua linguagem e ecossistema não têm suporte comum para logging, use [eventos de trecho][] para compartilhar detalhes adicionais da aplicação. Eventos podem ser mais convenientes se você quiser adicionar atributos também. +Se sua linguagem e ecossistema não têm suporte comum para logging, use [eventos +de trecho][] para compartilhar detalhes adicionais da aplicação. Eventos podem +ser mais convenientes se você quiser adicionar atributos também. -Como regra geral, use eventos ou logs para dados detalhados em vez de trechos. Sempre anexe eventos à instância de trecho criada pela sua instrumentação. Evite usar o trecho ativo, se possível, pois você não controla a que ele se refere. +Como regra geral, use eventos ou logs para dados detalhados em vez de trechos. +Sempre anexe eventos à instância de trecho criada pela sua instrumentação. Evite +usar o trecho ativo, se possível, pois você não controla a que ele se refere. ## Propagação de contexto ### Extraindo contexto -Se você trabalha em uma biblioteca ou serviço que recebe chamadas de upstream, como um framework web ou um consumidor de mensagens, você deve extrair o contexto da solicitação/mensagem recebida. O OpenTelemetry fornece a API `Propagator`, que oculta padrões específicos de propagação e lê o contexto de rastreamento a partir da comunicação. Em um caso de uma única resposta, há apenas um contexto na comunicação, que se torna o pai do novo trecho criado pela biblioteca. +Se você trabalha em uma biblioteca ou serviço que recebe chamadas de upstream, +como um framework web ou um consumidor de mensagens, você deve extrair o +contexto da solicitação/mensagem recebida. O OpenTelemetry fornece a API +`Propagator`, que oculta padrões específicos de propagação e lê o contexto de +rastreamento a partir da comunicação. Em um caso de uma única resposta, há +apenas um contexto na comunicação, que se torna o pai do novo trecho criado pela +biblioteca. -Depois de criar um trecho, você deve passar o novo contexto de rastreamento para o código da aplicação (função de retorno ou manipulador), tornando o trecho ativo; se possível, você deve fazer isso de forma explícita. +Depois de criar um trecho, você deve passar o novo contexto de rastreamento para +o código da aplicação (função de retorno ou manipulador), tornando o trecho +ativo; se possível, você deve fazer isso de forma explícita. ```java // extract the context @@ -206,14 +299,21 @@ Aqui estão os [exemplos completos de extração de contexto em Java](/docs/languages/java/instrumentation/#context-propagation), confira a documentação do OpenTelemetry da sua linguagem. -No caso de um sistema de mensageria, você pode receber mais de uma mensagem de uma só vez. As mensagens recebidas se tornam -[_links_](/docs/languages/java/instrumentation/#create-spans-with-links) no trecho que você cria. Consulte as -[convenções de mensageria](/docs/specs/semconv/messaging/messaging-spans/) para mais detalhes (AVISO: as convenções de mensageria estão +No caso de um sistema de mensageria, você pode receber mais de uma mensagem de +uma só vez. As mensagens recebidas se tornam +[_links_](/docs/languages/java/instrumentation/#create-spans-with-links) no +trecho que você cria. Consulte as +[convenções de mensageria](/docs/specs/semconv/messaging/messaging-spans/) para +mais detalhes (AVISO: as convenções de mensageria estão [em construção](https://github.com/open-telemetry/oteps/pull/173) 🚧). ### Injetando contexto -Quando você faz uma chamada de saída, geralmente você vai querer propagar o contexto para o serviço subsequente. 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. Pode haver outros casos em que você queira injetar contexto, por exemplo, ao criar mensagens para processamento assíncrono. +Quando você faz uma chamada de saída, geralmente você vai querer propagar o +contexto para o serviço subsequente. 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. Pode haver outros casos em que você queira injetar +contexto, por exemplo, ao criar mensagens para processamento assíncrono. ```java trecho trecho = tracer.spanBuilder("send") @@ -241,28 +341,40 @@ Aqui está o Pode haver algumas exceções: - o serviço subsequente não suporta metadados ou proíbe campos desconhecidos -- o serviço subsequente não define protocolos de correlação. É possível que alguma versão futura do serviço suporte a propagação de contexto compatível? Neste caso, injete o contexto! +- o serviço subsequente não define protocolos de correlação. É possível que + alguma versão futura do serviço suporte a propagação de contexto compatível? + Neste caso, injete o contexto! - o serviço subsequente suporta um protocolo de correlação personalizado. - - faça o melhor possível com um propagador personalizado: use o contexto de rastreamento do OpenTelemetry se for compatível. + - faça o melhor possível com um propagador personalizado: use o contexto de + rastreamento do OpenTelemetry se for compatível. - ou gere e adicione IDs de correlação personalizados no trecho. ### In-process -- **Torne seus trechos ativos** (também conhecidos como atuais): isso permite correlacionar trechos com logs e quaisquer autoinstrumentações aninhadas. -- Se a biblioteca tiver uma noção de contexto, suporte a propagação opcional de contexto de rastreamento explícito _além_ dos trechos ativos. - - coloque os trechos (contexto de rastreamento) criados pela biblioteca explicitamente no contexto e documente como acessá-los. +- **Torne seus trechos ativos** (também conhecidos como atuais): isso permite + correlacionar trechos com logs e quaisquer autoinstrumentações aninhadas. +- Se a biblioteca tiver uma noção de contexto, suporte a propagação opcional de + contexto de rastreamento explícito _além_ dos trechos ativos. + - coloque os trechos (contexto de rastreamento) criados pela biblioteca + explicitamente no contexto e documente como acessá-los. - permita que os usuários passem o contexto de rastreamento no seu contexto. -- Dentro da biblioteca, propague o contexto de rastreamento explicitamente - os trechos ativos podem mudar durante as chamadas de retorno! - - capture o contexto ativo dos usuários na superfície da API pública assim que possível e use-o como contexto pai para seus trechos. - - passe o contexto ao redor e adicione atributos, exceções e eventos nas instâncias explicitamente propagadas. - - isso é essencial se você iniciar threads explicitamente, realizar processamento em segundo plano ou outras atividades que possam ser afetadas pelas limitações de fluxo de contexto assíncrono na sua linguagem. +- Dentro da biblioteca, propague o contexto de rastreamento explicitamente - os + trechos ativos podem mudar durante as chamadas de retorno! + - capture o contexto ativo dos usuários na superfície da API pública assim que + possível e use-o como contexto pai para seus trechos. + - passe o contexto ao redor e adicione atributos, exceções e eventos nas + instâncias explicitamente propagadas. + - isso é essencial se você iniciar threads explicitamente, realizar + processamento em segundo plano ou outras atividades que possam ser afetadas + pelas limitações de fluxo de contexto assíncrono na sua linguagem. ## Misc ### Registro de instrumentação Por favor, adicione sua biblioteca de instrumentação ao -[registro do OpenTelemetry](/ecosystem/registry/), para que os usuários possam encontrá-la. +[registro do OpenTelemetry](/ecosystem/registry/), para que os usuários possam +encontrá-la. ### Desempenho @@ -270,7 +382,10 @@ A API do OpenTelemetry é autônoma e muito eficiente quando não há SDK na aplicação. Quando o SDK do OpenTelemetry é configurado, ele [consome recursos vinculados](/docs/specs/otel/performance/). -Aplicações do mundo real, especialmente em grande escala, frequentemente têm a amostragem baseada em cabeçalho configurada. Trechos descartados são baratos e você pode verificar se o trecho está gravando, para evitar alocações extras e cálculos potencialmente caros ao popular atributos. +Aplicações do mundo real, especialmente em grande escala, frequentemente têm a +amostragem baseada em cabeçalho configurada. Trechos descartados são baratos e +você pode verificar se o trecho está gravando, para evitar alocações extras e +cálculos potencialmente caros ao popular atributos. ```java // some attributes are important for sampling, they should be provided at creation time @@ -289,13 +404,22 @@ if (trecho.isRecording()) { ### Tratamento de erros -A API do OpenTelemetry é tolerante em tempo de execução - não falha em argumentos inválidos, nunca lança exceções e engole as exceções. Dessa forma, os 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. +A API do OpenTelemetry é tolerante em tempo de execução - não falha em +argumentos inválidos, nunca lança exceções e engole as exceções. Dessa forma, os +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 -Como o OpenTelemetry possui uma variedade de autoinstrumentações, é útil testar como sua instrumentação interage com outras telemetrias: solicitações recebidas, solicitações enviadas, 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 exibidas. +Como o OpenTelemetry possui uma variedade de autoinstrumentações, é útil testar +como sua instrumentação interage com outras telemetrias: solicitações recebidas, +solicitações enviadas, 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 exibidas. -Para testes unitários, você geralmente pode usar mocks ou fakes `SpanProcessor` e `SpanExporter`. +Para testes unitários, você geralmente pode usar mocks ou fakes `SpanProcessor` +e `SpanExporter`. ```java @Test @@ -323,5 +447,6 @@ class TestExporter implements SpanExporter { } ``` -[bibliotecas de instrumentação]: /docs/specs/otel/overview/#instrumentation-libraries +[bibliotecas de instrumentação]: + /docs/specs/otel/overview/#instrumentation-libraries [eventos de trecho]: /docs/specs/otel/trace/api/#add-events diff --git a/content/pt/docs/concepts/instrumentation/zero-code.md b/content/pt/docs/concepts/instrumentation/zero-code.md index b4ba315a83b4..10bd80803cbc 100644 --- a/content/pt/docs/concepts/instrumentation/zero-code.md +++ b/content/pt/docs/concepts/instrumentation/zero-code.md @@ -1,22 +1,40 @@ --- title: Autoinstrumentação description: >- - Aprenda a adicionar observabilidade a uma aplicação sem a necessidade de escrever - código + Aprenda a adicionar observabilidade a uma aplicação sem a necessidade de + escrever código weight: 10 aliases: [automatic] default_lang_commit: 13c2d415e935fac3014344e67c6c61556779fd6f --- -Em um time de [operaçõe](/docs/getting-started/ops/), você pode querer adicionar observabilidade a uma ou mais aplicações sem precisar editar o código-fonte. O OpenTelemetry permite que você tenha rapidamente observabilidade para um serviço sem precisar usar a API e SDK do OpenTelemetry para instrumentação baseada em código. - -A autoinstrumentação adiciona as capacidades da API e SDK do OpenTelemetry à sua aplicação, geralmente como uma instalação de agente ou semelhante a um agente. Os mecanismos específicos envolvidos podem variar de acordo com a linguagem, desde manipulação de bytecode, monkey patching ou eBPF para injetar chamadas à API e SDK do OpenTelemetry em sua aplicação. - -Normalmente, a autoinstrumentação adiciona instrumentação para as bibliotecas que você está usando. Isso significa que as chamadas de requisições e respostas, chamadas de banco de dados, chamadas de fila de mensagens e assim por diante são instrumentadas. No entanto, o código da sua aplicação geralmente não é instrumentado. Para instrumentar seu código, você precisará usar a instrumentação baseada em código. - -Além disso, a autoinstrumentação permite que você configure as Bibliotecas de Instrumentação e os Exporters carregados. - -Você pode configurar a autoinstrumentação por meio de variáveis de ambiente e outros mecanismos específicos da linguagem, como propriedades do sistema ou argumentos passados para métodos de inicialização. Para começar, você só precisa configurar um nome de serviço para que você possa identificar o serviço no backend de observabilidade de sua escolha. +Em um time de [operações](/docs/getting-started/ops/), você pode querer +adicionar observabilidade a uma ou mais aplicações sem precisar editar o +código-fonte. O OpenTelemetry permite que você tenha rapidamente observabilidade +para um serviço sem precisar usar a API e SDK do OpenTelemetry para +instrumentação baseada em código. + +A autoinstrumentação adiciona as capacidades da API e SDK do OpenTelemetry à sua +aplicação, geralmente como uma instalação de agente ou semelhante a um agente. +Os mecanismos específicos envolvidos podem variar de acordo com a linguagem, +desde manipulação de bytecode, monkey patching ou eBPF para injetar chamadas à +API e SDK do OpenTelemetry em sua aplicação. + +Normalmente, a autoinstrumentação adiciona instrumentação para as bibliotecas +que você está usando. Isso significa que as chamadas de requisições e respostas, +chamadas de banco de dados, chamadas de fila de mensagens e assim por diante são +instrumentadas. No entanto, o código da sua aplicação geralmente não é +instrumentado. Para instrumentar seu código, você precisará usar a +instrumentação baseada em código. + +Além disso, a autoinstrumentação permite que você configure as Bibliotecas de +Instrumentação e os Exporters carregados. + +Você pode configurar a autoinstrumentação por meio de variáveis de ambiente e +outros mecanismos específicos da linguagem, como propriedades do sistema ou +argumentos passados para métodos de inicialização. Para começar, você só precisa +configurar um nome de serviço para que você possa identificar o serviço no +backend de observabilidade de sua escolha. Outras opções de configuração estão disponíveis, incluindo: