Guia para usar a API do agente Python

A API do agente Python permite personalizar e ampliar seu monitoramento. Use a API do agente Python para:

Instrumentar manualmente uma framework não suportada ou sistema de terceiros.
Adicione instrumentação para complementar o monitoramento padrão do agente.

Este documento descreve algumas das chamadas de API Python disponíveis. Para obter uma descrição de todas as nossas API disponíveis, consulte Introdução à API.

Instrumentação personalizada ou API

Se o seu objetivo é a instrumentação personalizada, considere usar o método do arquivo de configuração, que permite adicionar funções e métodos de classe ao arquivo de configuração que será auto-instrumentado pelo agente. A vantagem do método config-file é que ele não exige que você altere o código do seu aplicativo.

No entanto, a API do agente Python é muito mais poderosa e é melhor para configurar instrumentação mais complexa e personalizada. Para garantir que você tenha acesso a todas as funcionalidades da API, atualize para o agente Python mais recente.

Monitor transações e segmentos

O agente Python é compatível com a maioria das estruturas da web WSGI comuns. Se o agente suportar sua framework, as solicitações da web serão capturadas automaticamente como transação e exibidas na UI do New Relic. Uma transação também pode ter segmentos em nível de função que são capturados como parte de um rastreamento da transação.

Use estes métodos para monitor transações da web, transações fora da web e segmentos de transação:

Se você quiser...	Fazem isto...
Monitor WSGI transação da web	O agente Python captura automaticamente transações da web para framework suportado. Se você não tiver uma framework compatível, poderá usar a função `wsgi_application` para monitor seu ponto de entrada WSGI.
Monitor ASGI transações da web	O agente Python captura automaticamente transações da web para framework suportado. Se você não tiver uma framework compatível, poderá usar a função `asgi_application` para monitor seu ponto de entrada ASGI.
Monitor transações fora da web	O agente Python classifica a transação fora da web como tarefas em segundo plano. Para capturar transações fora da web, use `background_task`.
Capture mais detalhes sobre uma transação	Se o seu rastreamento da transação não tiver o nível de detalhe que você deseja: Use `function_trace` para capturar mais detalhes em nível de função na transação. Use `datastore_trace` para capturar mais detalhes sobre chamadas de armazenamento de dados.
Ignorar uma transação	Use qualquer uma destas opções: Para ignorar completamente uma transação, use `ignore_transaction`. Para evitar que uma transação produza um rastreamento da transação, use `suppress_transaction_trace`. Para encerrar uma transação antes que o agente a termine automaticamente, use `end_of_transaction`.

Adicionar e editar metadados de transação

Às vezes o código que você deseja fica visível em nossa interface, mas alguns detalhes do método não são úteis. Por exemplo:

O nome padrão não é útil ou está causando um problema de agrupamento métrico.
Você deseja adicionar um atributo personalizado à sua transação para poder filtrá-los na consulta.

Use estas chamadas quando quiser alterar os metadados de uma transação existente:

Se você quiser...	Fazem isto...
Obtenha referência à transação atual	Para retornar um objeto que representa a transação atual, use `current_transaction`. Isso é exigido por algumas outras chamadas de API do agente Python.
Alterar o nome de uma transação	Use `set_transaction_name`.
Adicionar metadados (como o nível de assinatura do cliente) à transação	Adicione um atributo personalizado à sua transação usando `add_custom_attribute` ou use outra chamada de API para relatar dados personalizados.
Marcar uma transação como um trabalho em segundo plano	Para converter uma transação web em uma tarefa em segundo plano para que ela apareça como uma transação fora da web na interface, utilize `set_background_task`.
Evite que uma transação afete sua pontuação Apdex	Usar `suppress_apdex_metric`.

Veja o registro relacionado

Para ver o registro diretamente no contexto dos erros e rastreamentos do seu aplicativo, use a chamada de API get_linking_metadata para anotar seu registro. Para obter mais informações sobre como correlacionar dados log com outros dados de telemetria, consulte nossa documentação de logs contextualizados .

Relatório de evento personalizado e dados métricos personalizados

O agente relata dados em dois formatos principais:

Os dados métricos medem valores numéricos baseados no tempo; por exemplo, conexões por minuto.
Os dados de eventos capturam informações discretas de eventos. ainda tenham valor principal atributo associado a eles. Você pode analisar e consultar dados de eventos.

Use estes métodos para criar novos dados de eventos e novos dados métricos:

Se você quiser...	Fazem isto...
Envie dados sobre um evento para uso ao consultar seus dados.	Usar `record_custom_event`.
Relate métricas baseadas em tempo sobre o desempenho do aplicativo	Para relatar uma única métrica, use `record_custom_metric`. Para reportar um conjunto de métricas, use `record_custom_metrics`.
Relatar uma exceção como um erro	Por padrão, o agente Python relata apenas exceções não tratadas. Para relatar uma exceção do Python como um erro, use `notice_error`.
Parâmetro da string de consulta do relatório	Por motivos de segurança, os parâmetros de query string associados à transação da web estão desabilitados por padrão. Use `capture_request_params` para ativá-los.
Tag evento com metadados	Para adicionar um atributo ao evento para consultas mais detalhadas ou análises de erros, use `add_custom_attribute`.
Gere métricas a partir de fontes de dados e fábricas de dados	Para gerar métricas com uma API estilo pull em vez da API estilo push implementada por `record_custom_metric()`, use esta chamada de API: `register_data_source` `data_source_generator` `data_source_factory`

Chamadas relacionadas a mensagens

Essas chamadas de API permitem coletar dados de desempenho em sua arquitetura ou serviço de passagem de mensagens; por exemplo, RabbitMQ. Para usar essas chamadas, certifique-se de ter o agente Python versão 2.88.0.72 ou superior.

Se você quiser...	Fazem isto...
Relatar mensagens como uma transação	Usar `message_transaction`.
Relatar detalhes da mensagem como segmentos de rastreamento da transação	Usar `message_trace`.

Implementar distributed tracing

Essas API exigem que distributed tracing esteja ativado.

Os serviços e aplicativos monitorados por nosso agente passarão automaticamente o contexto distributed tracing entre si ao usar uma frameworksuportada. Quando não estiver usando uma framework compatível, você precisará usar a distributed tracing API para aceitar manualmente esse contexto.

A estrutura da web compatível (por exemplo, Flask, Django, Tornado) chamará automaticamente accept_distributed_trace_payload ao criar uma transação. A biblioteca de serviços da web externos suportados chamará automaticamente create_distributed_trace_payload antes de fazer uma chamada HTTP externa.

Para obter instruções gerais sobre como usar as chamadas abaixo para implementar distributed tracing, consulte Usar distributed tracing API.

Se você quiser...	Fazem isto...
Crie uma carga a ser enviada para um serviço chamado.	Usar `create_distributed_trace_payload`.
Aceite uma carga enviada do primeiro serviço; isso vinculará esses serviços em um trace	Usar `accept_distributed_trace_payload`.

Configuração do agente, inicialização, desligamento

Essas chamadas ajudam você a gerenciar o comportamento do agente Python, como inicializar e integrar o agente e fazer referência ou alterar definições de configuração :

Se você quiser...	Fazem isto...
Inicialize o agente	Para inicializar o agente Python com um arquivo de configuração específico como parte do processo de integração avançado, use `initialize`.
Obtenha uma referência ao objeto `application`	O objeto `application` representa um aplicativo agente-monitor e é usado por algumas chamadas de API de agente Python.
Obtenha uma referência às definições de configuração	Para controlar o comportamento do agente Python, você pode usar definições de configuração. Para obter uma referência ao arquivo de configuração e às configurações de variáveis de ambiente e fazer alterações neles, use `global_settings`. Para obter uma referência às configurações de all , incluindo configuração no lado do servidor de nossa interface, use `application_settings`.
Desligue o agente	Para forçar o encerramento do agente em vez de permitir que ele faça a tentativa final padrão de upload de dados, use `shutdown_agent`.

Controle o agente de monitoramento do Browser

Você pode instalar o agente de monitoramento de Browser adicionando-o automaticamente às suas páginas ou implantando-o em páginas específicas copiando e colando o trecho JavaScript do agente . Você também pode controlar o agente browser usando a chamada de API do agente APM. Para obter mais informações, consulte agente browser e agente Python.

Se você quiser...	Fazem isto...
Monitor visualizações de páginas específicas	Para injetar o trecho JavaScript de cabeçalho e rodapé do agente browser nas visualizações que você deseja monitor, use `get_browser_timing_header` e `get_browser_timing_footer`.
Desative o monitoramento de visualizações de páginas específicas	Para desativar o monitoramento do browser para visualizações de páginas específicas, use `disable_browser_autorum`.

Esta tradução de máquina é fornecida para sua comodidade.

Instrumentação personalizada ou API .css-21sua1{background:none;border:none;width:0;padding:0;}