Skip to main content

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:

  1. Soluções baseadas em código
    Utilizando APIs e SDKs oficiais disponíveis para a maioria das linguagens de programação.

  2. 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

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.

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.