> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Distributed tracing
> Siga uma requisição por serviços e aplicações: como o AppSignal reúne o subtrace de cada serviço em um único trace.
Onde uma requisição lenta realmente gasta seu tempo? O tempo de resposta da
sua aplicação web parece normal, o banco de dados está tranquilo, e a
requisição ainda assim leva quatro segundos.
Uma única requisição pode se autenticar em um serviço, carregar dados de uma
API interna, enfileirar um job em background e chamar a API de pagamento de
terceiros antes que a resposta volte. Quando ela é lenta ou falha, a causa
costuma estar em um serviço diferente daquele que reportou o problema.
O distributed tracing segue essa requisição enquanto ela atravessa essas
fronteiras e reúne o trabalho de todos os serviços sob um único trace, para
que você veja o percurso inteiro em vez de montá-lo a partir de cada serviço
isoladamente. Pense em um grupo de chat: cada serviço responde na mesma
thread, de forma que a requisição se lê como uma única conversa em vez de
cinco conversas separadas.
O que é distributed tracing?
Quando cada serviço reporta por conta própria, você vê que uma web action
está lenta, mas não que um serviço de estoque mais adiante na cadeia de
chamadas causou isso. No AppSignal, cada um desses serviços é um app ou
namespace separado. Para seguir uma requisição por eles, você precisa abrir
cada um e alinhar os timestamps.
O distributed tracing remove essas fronteiras. Conforme uma requisição se
move de um serviço para o próximo, cada serviço marca seu trabalho com o
mesmo ID de trace e registra qual trabalho o chamou. O AppSignal usa esses
IDs para reconstruir o caminho completo da requisição, por todos os serviços
que participaram.
Com um trace distribuído, você pode:
* Seguir uma requisição do seu ponto de entrada por todos os serviços
alcançados.
* Ver para onde o tempo foi, mesmo quando a parte lenta roda em um serviço ou
aplicação diferente.
* Descobrir em qual serviço um erro começou, não apenas onde ele apareceu.
Spans, traces e serviços
O AppSignal descreve um trace com três blocos de construção.
* **Span**: uma única unidade de trabalho, como uma requisição HTTP recebida,
uma query de banco de dados, uma chamada a outro serviço, ou um bloco de
código que você mesmo instrumenta. Um span tem um nome, uma duração e
atributos, e registra o span que o iniciou. Spans são a menor coisa da qual
um trace é feito.
* **Trace**: todos os spans que pertencem a uma operação de ponta a ponta.
Como cada span conhece seu span pai, os spans em um trace formam uma árvore
que descreve a requisição do início ao fim.
* **Serviço**: um componente nomeado que participa de um trace, como uma
aplicação web, um worker em background ou uma API interna. Você nomeia um
serviço com a opção `service_name` (ou a variável de ambiente
`APPSIGNAL_SERVICE_NAME`), e o AppSignal usa esse nome para diferenciar
serviços dentro de um trace. Um único trace geralmente atravessa vários
serviços, e esses serviços podem reportar para aplicações AppSignal
diferentes.
O AppSignal constrói traces sobre o OpenTelemetry, então esses termos
seguem os do OpenTelemetry. O AppSignal agrupa cada trace em uma
[action](/appsignal/terminology#actions) e um
[namespace](/application/namespaces), com base no endpoint, job ou task ao
qual o trace pertence.
Dentro do AppSignal, um trace é um tipo de
[sample](/appsignal/terminology#samples): o registro detalhado de uma
requisição, armazenado para que você possa abri-lo e lê-lo span por span. O
AppSignal deriva suas métricas de performance, como tempo de resposta e
throughput, a partir desses traces, então um gráfico de performance e um
único trace são duas visões dos mesmos dados.
Disponibilidade e configuração
O distributed tracing está disponível primeiro para Python, Ruby e PHP.
Outras linguagens, como Elixir e JavaScript, ainda não são suportadas.
Distributed tracing é um **recurso experimental disponível apenas** ao usar
o collector hospedado do AppSignal.
Se você precisa ativar algo depende de como sua integração reporta ao
AppSignal. Python e Ruby podem reportar tanto pelo agente incluído na
integração quanto por um collector, então o modo collector precisa ser
configurado. PHP e uma configuração personalizada do OpenTelemetry só
reportam por um collector, então não há nada para ativar.
* **Python e Ruby**: defina a opção `collector_endpoint` para a URL de um
collector hospedado em vez de um self-hosted. Veja [configuração do
collector para Python](/python/configuration/collector), [configuração do
collector para Ruby](/ruby/configuration/collector), e [collectors
hospedados vs self-hosted](/collector/hosted-vs-self-hosted) para a
diferença entre os dois.
* **PHP**: nada para configurar. O pacote PHP já reporta por um collector,
então o distributed tracing funciona assim que seu app reporta ao
AppSignal.
* **Uma configuração personalizada do OpenTelemetry**: nada para configurar.
Exportar para um collector é a única forma como essas configurações
reportam, então os traces se conectam sozinhos.
O distributed tracing é construído sobre o OpenTelemetry, então não se
limita às integrações acima. Qualquer aplicação instrumentada com
OpenTelemetry pode se juntar a um trace exportando seus dados para um
collector hospedado. Você pode fazer isso por uma integração do AppSignal
como o pacote PHP, ou por uma [configuração personalizada de SDK do
OpenTelemetry](/opentelemetry/installation).
Como isso funciona no AppSignal?
O AppSignal constrói traces distribuídos sobre o OpenTelemetry, que cuida da
parte que torna o distributed tracing possível: a **propagação de
contexto**. Quando um serviço instrumentado chama outro serviço, o
OpenTelemetry anexa o ID de trace e o span de origem à chamada de saída. Ele
viaja como headers em uma requisição HTTP, ou como metadados em um job
enfileirado, e o serviço que o recebe o lê e continua o mesmo trace.
Cada serviço reporta a porção do trace pela qual é responsável, chamada de
seu **subtrace**. O AppSignal recebe esses subtraces de forma independente,
muitas vezes de processos ou hosts diferentes, e os remonta em um único trace
usando o ID de trace compartilhado e os vínculos pai e filho entre os spans.
Você nunca configura a conexão entre serviços manualmente. Se uma biblioteca
está instrumentada, suas chamadas se juntam ao trace automaticamente.
O AppSignal faz sampling de traces em vez de manter todos eles, e toma essa
decisão entre serviços: quando um trace é mantido, o trabalho de cada serviço
nele também é mantido, então o trace chega inteiro em vez de em fragmentos
espalhados. O sampling favorece os traces que você mais quer ver, os com
erros e as requisições mais lentas. Lacunas ainda podem aparecer nas bordas,
quando um serviço não reporta ou seus dados chegam tarde demais.
Você explora o resultado na [página do trace](/trace-page) de duas formas: o
**service map**, que mostra os serviços no trace e as chamadas entre eles, e
a **linha do tempo do trace**, que dispõe cada span ao longo do tempo. A
página do trace explica como ler os dois.
Suporte entre aplicações
Um serviço no AppSignal não é a mesma coisa que uma aplicação. Vários
serviços podem reportar para uma aplicação AppSignal, e um único trace também
pode atravessar serviços que pertencem a aplicações totalmente separadas.
Por exemplo, uma aplicação web, um serviço de estoque e um serviço de
auditoria podem todos reportar para uma aplicação AppSignal, cada um com seu
próprio nome de serviço, enquanto um serviço separado reporta como sua
própria aplicação. Uma única ação do usuário, como um checkout, pode produzir
um trace que inclui serviços de ambas as aplicações.
O service map do AppSignal trata isso como um único trace, independentemente
de onde cada subtrace foi reportado. Ele identifica a aplicação dona de cada
serviço e vincula cada cartão à visão dessa aplicação sobre o mesmo trace.
Para seguir uma requisição por uma fronteira entre aplicações, selecione o
cartão do próximo serviço. Você passa de uma aplicação para a próxima ao
longo do mesmo trace, sem perder o fio.
Isso funciona porque o contexto se propaga por fronteiras de processo e de
aplicação da mesma forma que entre serviços, e o AppSignal corresponde
subtraces pelo seu ID de trace compartilhado, não pela aplicação ou host de
onde vieram.
Leia um trace: sua linha do tempo, detalhes dos spans, tags, logs
relacionados e triggers.
Inspecione os spans e eventos dentro de um único trace.
Adicione seus próprios spans ao trace quando os padrões não forem
suficientes.
Como o AppSignal agrupa traces por endpoint, job e task.
Experimente distributed tracing e outros recursos experimentais.