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.