Instrumentação com Bibliotecas OpenTelemetry

O envio de sinais para o Priax pode ser realizado através de instrumentação própria, alterando o código da aplicação a ser observada sem inserir componentes de terceiros à sua infraestrutura. Este processo, no entanto pode ser custoso e levar algum tempo. Para que se possa acelerar esse processo, recomendamos, apesar de não ser a única opção, as bibliotecas e SDKs open-source do OpenTelemetry. Tais bibliotecas seguem os padrões OpenTracing e se tornaram a mais difundida solução de instrumentação para o mercado de Observabilidade.

Como o OpenTelemetry facilita a instrumentação
Para tornar um sistema observável, é necessário instrumentá-lo: ou seja, o código dos componentes do sistema deve emitir traces, métricas e logs.

Com o OpenTelemetry, você pode instrumentar seu código de duas maneiras principais:

Soluções baseadas em código
Utilizando APIs e SDKs oficiais disponíveis para a maioria das linguagens de programação.
Soluções sem código
Ideais para casos em que você não pode ou não deseja modificar o aplicativo que precisa de telemetria.

Soluções baseadas em código

Essas soluções permitem uma telemetria mais profunda e detalhada, gerada diretamente pela sua aplicação. Elas utilizam a API do OpenTelemetry para produzir telemetria personalizada, complementando as informações coletadas por soluções sem código.

Soluções sem código

Perfeitas para começar rapidamente ou quando o aplicativo não pode ser modificado. Essas soluções oferecem uma telemetria rica baseada em bibliotecas utilizadas ou no ambiente em que a aplicação está sendo executada. Elas fornecem dados sobre o que está acontecendo nas "bordas" da aplicação, como interações externas e dependências.

Nota: É possível usar ambas as abordagens ao mesmo tempo para maximizar a observabilidade.

Benefícios adicionais do OpenTelemetry

O OpenTelemetry vai além de oferecer soluções com e sem código. Ele também inclui os seguintes recursos:

Bibliotecas compatíveis: Bibliotecas podem usar a API do OpenTelemetry como dependência, sem impactar aplicações que não importem o SDK.
Sinais flexíveis: Para cada tipo de sinal (traces, métricas, logs), existem várias formas de criá-los, processá-los e exportá-los.
Correlação de sinais: Com a propagação de contexto integrada, é possível correlacionar sinais, independentemente de onde foram gerados.
Recursos e Escopos de Instrumentação: Permitem agrupar sinais por diferentes entidades, como o host, sistema operacional ou cluster Kubernetes.
Padrões e especificações: Cada implementação de linguagem do OpenTelemetry segue os requisitos e expectativas definidos pela especificação oficial.
Convenções semânticas: Fornecem um esquema de nomenclatura comum para padronizar métricas, logs e traces entre diferentes bases de código e plataformas.

Formas de Instrumentação

Instrumentação sem código com OpenTelemetry

A instrumentação sem código adiciona as capacidades da API e SDK do OpenTelemetry à sua aplicação, geralmente por meio de uma instalação de agente ou algo semelhante a um agente. Os mecanismos específicos variam conforme a linguagem, incluindo manipulação de bytecode, monkey patching ou eBPF, para injetar chamadas à API e ao SDK do OpenTelemetry diretamente na aplicação.

Como funciona

Normalmente, a instrumentação sem código adiciona suporte para bibliotecas que sua aplicação utiliza. Isso significa que requisições e respostas, chamadas a bancos de dados, chamadas de filas de mensagens, entre outros, serão instrumentados automaticamente. No entanto, o código da sua aplicação geralmente não é instrumentado. Para isso, é necessário utilizar instrumentação baseada em código.

Além disso, a instrumentação sem código permite configurar as bibliotecas de instrumentação e os exportadores que serão carregados.

Configuração

Você pode configurar a instrumentação sem código 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, é necessário apenas configurar o nome do serviço para identificá-lo no backend de observabilidade escolhido.

Outras opções de configuração incluem:

Configuração específica para fontes de dados.
Configuração de exportadores.
Configuração de propagadores.
Configuração de recursos.

Suporte de linguagens para instrumentação automática

A instrumentação automática está disponível para as seguintes linguagens:

.NET
Go
Java
JavaScript
PHP
Python

Para realizar a instrumentação de sua aplicação, utilizando o método Zero Code, siga as instruções da página do OpenTelemetry.

Instrumentação Baseada em Código com OpenTelemetry

A instrumentação baseada em código permite criar telemetria personalizada diretamente no código da sua aplicação. Abaixo estão os passos essenciais para configurar essa abordagem:

1. Importar a API e o SDK do OpenTelemetry

Serviços: Dependem da API e do SDK do OpenTelemetry.
Bibliotecas: Apenas dependem da API.

Para mais detalhes sobre a API e o SDK, consulte a especificação do OpenTelemetry.

2. Configurar a API do OpenTelemetry

Fornecedores de Tracer e Meter:
- Crie um TracerProvider para gerar traços.
- Crie um MeterProvider para gerar métricas.
Nomeação:
- Use um nome que identifique o componente sendo instrumentado.
- Exemplo: para uma biblioteca, use algo como com.example.myLibrary.
- Inclua uma versão no formato semver (ex.: semver:1.0.0).

3. Configurar o SDK do OpenTelemetry

Exportação de dados: Configure o SDK para exportar telemetria a um backend de análise.
Opções específicas da linguagem: Verifique as opções de ajuste disponíveis para a sua linguagem.

A configuração pode ser feita programaticamente, por meio de arquivos de configuração ou outros mecanismos.

4. Criar Dados de Telemetria

Traços e Métricas:
- Gere traços e eventos de métricas com os objetos Tracer e Meter.
Bibliotecas de Instrumentação:
- Use bibliotecas de instrumentação disponíveis para suas dependências.
- Consulte o repositório ou registro da sua linguagem para obter mais informações.

5. Exportar Dados de Telemetria

Métodos de Exportação:
- Exportação no processo:
  - Importe e use exportadores para traduzir os objetos de telemetria do OpenTelemetry em formatos apropriados para ferramentas de análise (ex.: Jaeger ou Prometheus).
- Exportação via OTLP e Collector:
  - Use o protocolo OTLP para enviar dados ao OpenTelemetry Collector, que pode atuar como um proxy, sidecar ou processo separado.
  - O Collector encaminha os dados para ferramentas de análise.

Para realizar a instrumentação de sua aplicação, utilizando o método baseado em código siga as instruções da página do OpenTelemetry.

Instrumentação de Bibliotecas com OpenTelemetry

A instrumentação nativa de bibliotecas com OpenTelemetry oferece uma experiência aprimorada tanto para desenvolvedores quanto para usuários finais, eliminando a necessidade de expor e documentar hooks personalizados. Aqui está como funciona e os benefícios associados:

Como Adicionar Instrumentação Nativa

Instrumentação via Hooks ou dynamic runtime patching:
OpenTelemetry fornece bibliotecas de instrumentação para várias linguagens, que tipicamente utilizam hooks de bibliotecas ou dynamic runtime patching do código.

Vantagens da Instrumentação Nativa

Melhoria na Observabilidade e Experiência do Usuário:
- Remove a necessidade de hooks personalizados, facilitando a integração.
- APIs do OpenTelemetry são fáceis de usar e consistentes para os usuários finais.
Telemetria Consistente e Correlação Aprimorada:
- Traços, logs e métricas provenientes do código da biblioteca e da aplicação são correlacionados, criando uma visão coesa dos eventos.
- Convenções comuns garantem uniformidade entre tecnologias, bibliotecas e linguagens.
Extensibilidade e Ajustes Fáceis:
- Sinais de telemetria podem ser ajustados (filtrados, processados, agregados) para atender a diferentes cenários de consumo.
- OpenTelemetry oferece extensibilidade bem documentada para personalização.

Para realizar a instrumentação de sua aplicação, utilizando as bibliotecas nativas OpenTelemetry, siga as instruções da página do OpenTelemetry.