Usando bibliotecas de instrumentação

Ao desenvolver uma aplicação, é possível utilizar bibliotecas e frameworks de terceiros para acelerar seu trabalho. Caso você instrumente sua aplicação utilizando OpenTelemetry, talvez queira evitar gastar tempo adicional para adicionar manualmente rastros, logs e métricas às bibliotecas e frameworks de terceiros que utiliza.

Muitas bibliotecas e frameworks já oferecem suporte ao OpenTelemetry ou são compatíveis por meio da instrumentação, permitindo gerar dados de telemetria que podem ser exportados para um backend de observabilidade.

Caso você esteja instrumentando uma aplicação ou serviço que utilize bibliotecas ou frameworks de terceiros, siga estas instruções para aprender como usar bibliotecas instrumentadas nativamente e bibliotecas de instrumentação para as dependências do seu projeto.

Usar bibliotecas com instrumentação nativa

Se uma biblioteca oferece suporte ao OpenTelemetry por padrão, é possível obter rastros, métricas e logs emitidos por essa biblioteca ao adicionar e configurar o SDK do OpenTelemetry na sua aplicação.

A biblioteca pode exigir alguma configuração adicional para sua instrumentação. Consulte a documentação dessa biblioteca para saber mais.

• Elasticsearch Python Client

Use bibliotecas de instrumentação

Se uma biblioteca não oferece suporte nativo ao OpenTelemetry, você pode usar bibliotecas de instrumentação para gerar dados de telemetria para uma biblioteca ou framework.

Por exemplo, a biblioteca de instrumentação para HTTPX cria automaticamente trechos com base em solicitações HTTP.

Configuração

Você pode instalar cada biblioteca de instrumentação separadamente usando pip. Por exemplo:

pip install opentelemetry-instrumentation-{instrumented-library}

No exemplo anterior, {instrumented-library} é o nome da instrumentação.

Para instalar uma versão de desenvolvimento, clone ou faça um fork do repositório opentelemetry-python-contrib e execute o seguinte comando para fazer uma instalação editável:

pip install -e ./instrumentation/opentelemetry-instrumentation-{integration}

Após a instalação, você precisará inicializar a biblioteca de instrumentação. Cada biblioteca geralmente tem sua própria maneira de inicializar.

Exemplo com instrumentação HTTPX

Veja como você pode instrumentar solicitações HTTP feitas usando a biblioteca httpx.

Primeiro, instale a biblioteca de instrumentação usando pip:

pip install opentelemetry-instrumentation-httpx

Em seguida, use o instrumentador para rastrear automaticamente as solicitações de todos os clientes:

import httpx
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

url = "https://some.url/get"
HTTPXClientInstrumentor().instrument()

with httpx.Client() as client:
     response = client.get(url)

async with httpx.AsyncClient() as client:
     response = await client.get(url)

Desativar instrumentações

Se necessário, você pode desinstrumentar clientes específicos ou todos os clientes usando o método uninstrument_client. Por exemplo:

import httpx
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

HTTPXClientInstrumentor().instrument()
client = httpx.Client()

# Desinstrumentar um cliente específico
HTTPXClientInstrumentor.uninstrument_client(client)

# Desinstrumentar todos os clientes
HTTPXClientInstrumentor().uninstrument()

Bibliotecas de instrumentação disponíveis

Uma lista completa de bibliotecas de instrumentação produzidas pelo OpenTelemetry está disponível no repositório opentelemetry-python-contrib.

Você também pode encontrar mais instrumentações disponíveis em registro.

Próximos passos

Depois de configurar as bibliotecas de instrumentação, você pode querer adicionar sua própria instrumentação no seu código, para coletar dados de telemetria personalizados.

Você também pode querer configurar um exporter apropriado para exportar seus dados de telemetria para um ou mais backends de telemetria.

Você também pode verificar a Instrumentação sem código para Python.