Distributed tracing para seus serviços PHP

Distributed tracing permite que você veja toda a jornada de suas solicitações em sistemas distribuídos. O agente PHP é automaticamente instrumento com distributed tracing de uma série de funções nativas do PHP, bem como alguns clientes HTTP de terceiros:

• Função PHP file_get_contents
• Funções PHP curl_exec e curl_multi_exec
• Beba 4, Beba 5, Beba 6
• Drupal drupal_http_request function
• Trabalhos de fila do Laravel

Para o agente PHP, oferecemos dois tipos de distributed tracing (para obter mais detalhes, consulte Como funciona a amostragem de span):

• Padrão (Amostragem head-based): Antes de qualquer rastreamento chegar, determinamos uma porcentagem definida de rastreamento para aceitar e analisar. Isso fornece um ponto de partida sólido para ver como o rastreamento pode ajudá-lo. Ele está ativado por padrão no agente PHP 9.21.0 e superior.
• Rastreamento Infinito (amostragem tail-based): Nosso serviço baseado em nuvem aceita todos os seus rastreamentos e depois os classifica para encontrar o mais importante. Depois de configurar o rastreamento padrão, recomendamos adicionar essa opção porque ela analisa todo o seu rastreamento e oferece opções de configuração para obter uma amostra do rastreamento mais importante para você.

Todas as etapas necessárias para começar a usar o distributed tracing estão aqui:

• Novo agente PHP: Passos para head- e amostragem tail-based para instalação de novo agente
• Agente PHP mais antigo: opções de rastreamento se você tiver um agente PHP mais antigo
• Definir nível de detalhe trace
• Manualmente instrumento aplicativo e serviços com API do agente PHP

Novo agente PHP

Se você deseja apenas experimentar distributed tracing padrão (Amostragem head-based) ou também configurar o Infinite Tracing (Amostragem tail-based), você precisa começar configurando o rastreamento padrão. Orientaremos você na instalação do agente APM para iniciar a Amostragem head-based. Depois disso, você pode configurar o Rastreamento Infinito, que é opcional, mas recomendado.

Instale um agente para obter distributed tracingpadrão

Esta é a melhor abordagem para configurar distributed tracingpadrão se você ainda não instalou nenhum agente APM para seus serviços ou se deseja instrumentar serviços adicionais.

Se você já possui alguns serviços instrumentados com este agente APM e deseja incluí-los no distributed tracing, será necessário habilitar manualmente distributed tracing para cada serviço. Consulte Opções para agentes PHP mais antigos.

Passo 1. Identificar serviços

Descubra quais serviços atendem à sua solicitação para que você possa instrumentar cada um deles para enviar dados trace para o New Relic.

Passo 2. Instrumentar cada serviço com um agente APM

Você repetirá a rotina de instalação do agente para cada serviço envolvido na sua transação. Se alguns dos seus serviços utilizarem outros idiomas, basta repetir as etapas de instalação para esses idiomas.

Para iniciar a rotina de instalação, clique no bloco abaixo. Quando terminar de instalar cada agente, volte aqui para ver dicas para visualizar seu rastreamento.

Start installation

Etapa 3. Ver rastreamento

Depois de instrumentar cada um de seus serviços com o agente APM, gere algum tráfego em sua aplicação para que possamos capturar algum rastro. Aqui estão algumas maneiras de visualizar seu rastreamento na interface:

Para obter mais ajuda para encontrar seu rastreamento na interface:

• Compreender e usar a interface distributed tracing
• Consultar dados distributed trace

Configurar rastreamento infinito

distributed tracing padrão para o agente APM (acima) captura até 10% do seu rastreamento, mas se você quiser que analisemos todos os seus dados e encontremos o rastreamento mais relevante, você pode configurar o Rastreamento Infinito.

Antes de começar, primeiro certifique-se de atender aos requisitos.

Etapa 1. Conclua a instalação do novo agente

A configuração do Rastreamento Infinito baseia-se na etapa de instrumentação da instalação do novo agente para distributed tracing padrão. Após concluir a instalação do agente, continue com a configuração do observador trace .

Etapa 2. Configurar o observador trace

O observador trace é um serviço New Relic baseado em AWS que coleta e analisa todos os seus rastreamentos. Siga as instruções em Configurar o observador trace . Quando terminar, retorne aqui com as informações do observador trace e continue com a próxima etapa para configurar o agente.

Etapa 3: configurar o agente para rastreamento infinito

As definições de configuração do Infinite Tracing incluem o distributed tracing padrão, além de informações sobre o observador trace . Observe que a configuração no lado do servidor não está disponível para Infinite Tracing.

Etapa 4. (Opcional) Personalizar rastreamento infinito

Depois de adicionar as definições de configuração do agente, você deverá começar a ver os dados na interface do New Relic. Depois de passar algum tempo analisando seus dados, você pode querer ajustar alguns recursos do Infinite Tracing:

• Configurar o monitoramento do observador trace
• Configurar filtro trace de atributo span
• Configurar filtro trace aleatório

Opções para agente PHP mais antigo

Se você tiver um agente PHP mais antigo, confirme se o recurso distributed tracing que você deseja tem suporte antes de habilitá-lo.

Guia de compatibilidade

Depois de revisar as informações de compatibilidade abaixo, consulte Configurar seu agente PHP mais antigo.

Configure seu agente PHP mais antigo

Veja as configurações abaixo para ativar distributed tracing.

Definir nível de detalhe trace

O suporte distributed tracing depende do tracerde transação do agente PHP. Quando distributed tracing está ativado, um intervalo é criado para cada segmento visto pelo tracer de transação.

À medida que os spans são amostrados, o agente PHP priorizará os spans relacionados a chamadas externas acima de outros spans, que serão então registrados em ordem decrescente de duração.

Se você descobrir que há muitos intervalos sem importância sendo relatados para chamadas de função PHP, poderá reduzir os detalhes do tracer de transação definindo newrelic.transaction_tracer.detail como 0. Você pode então usar a definição de configuração newrelic.transaction_tracer.custom ou o método de API newrelic_add_custom_tracer para adicionar segmentos e intervalos trace para a função ou métodos PHP específicos que deseja adicionar ao seu rastreamento.

Manualmente instrumento aplicativo e serviços com API do agente PHP

newrelic_create_distributed_trace_payload()
newrelic_accept_distributed_trace_payload($payload)

newrelic_insert_distributed_trace_headers($outbound_headers)
newrelic_accept_distributed_trace_headers($inbound_headers)

Se você estiver usando uma biblioteca não suportada ou tiver um componente de sistemas distribuídos não baseado em HTTP (como fila de mensagens), poderá usar a API do agente PHP para identificar manualmente a transação a ser incluída em um distributed trace. Este é um processo de duas etapas:

1. Modifique seu serviço ou aplicativo para

   create

   ou

   insert

   os dados distributed tracing

2. Modifique seu serviço ou aplicativo para

   accept

   dados distributed trace criados por outras transações ou solicitações.

O exemplo a seguir usa uma fila genérica de mensagens/trabalhos. Embora os detalhes reais variem dependendo do tipo de sistema que você está tentando adicionar a um distributed trace, os conceitos básicos são os mesmos. Além disso, embora tenhamos usado uma fila de tarefas como exemplo, você pode usar esses métodos com o componente any sistemas distribuídos.

Para obter mais informações sobre como usar instrumentação manual para obter mais detalhes ou ver conexões entre serviços, consulte a documentação sobre distributed tracing API.

API de cabeçalho

// create a job object
$job = new \Generic\Queue\Job;

// set the information needed to run the queue job
$job->setData('info', $info);

// save the job
$job->save();

$outbound_headers = array();
if (newrelic_insert_distributed_trace_headers($outbound_headers)) {

    // create a job object
    $job = new \Generic\Queue\Job;

    // set the information needed to run the queue job
    $job->setData('info', $info);

    // add the headers to the job data
    $job->setData('nr_dt_headers', $outbound_headers);

    // save the job
    $job->save();
} else {
    echo "Unable to obtain distributed tracing headers";
}

// create the job runner
$jobRunner = \Generic\Queue\Runner;

// grab jobs until there aren't any
while($job = $jobRunner->next()) {
    // run the job
    $job->run();
}

// create the job runner
$jobRunner = \Generic\Queue\Runner;

while($job = $jobRunner->next()) {
    $inbound_headers = $job->getData('nr_dt_headers');
    if($inbound_headers) {
        newrelic_accept_distributed_trace_headers($inbound_headers);
    }
    $job->run();
}

API de carga útil (obsoleta)

// create a job object
$job = new \Generic\Queue\Job;

// set the information needed to run the queue job
$job->setData('info', $info);

// save the job
$job->save();

$payload = newrelic_create_distributed_trace_payload();

// create a job object
$job = new \Generic\Queue\Job;

// set the information needed to run the queue job
$job->setData('info', $info);

// add the payload data to the job data as a text json string
$job->setData('dt_payload', $payload->Text());

// save the job
$job->save();

// create the job runner
$jobRunner = \Generic\Queue\Runner;

// grab jobs until there aren't any
while($job = $jobRunner->next()) {
    // run the job
    $job->run();
}

// create the job runner
$jobRunner = \Generic\Queue\Runner;

while($job = $jobRunner->next()) {
    $payload = $job->getData('dt_payload');
    if($payload) {
        newrelic_accept_distributed_trace_payload($payload);
    }
    $job->run();
}

// create the HTTP safe payload string 
$payload = newrelic_create_distributed_trace_payload();
$httpSafePayload = $payload->httpSafe();

// ...

// accept the HTTP safe payload string
newrelic_accept_distributed_trace_payload_httpsafe($httpSafePayload);

Programas PHP de linha de comando

Os programas PHP executados a partir da linha de comando PHP são sempre amostrados pelo tracer distribuído do agente. Dependendo dos programas que você executa, esses processos podem ter uma representação excessiva em sua coleção de rastreamentos distribuídos. Nessas situações, você pode optar por desativar a instrumentação de linha de comando usando a configuração per-directory newrelic.enabled em seu newrelic.ini files.