Como usar o Cloud Trace com Zipkin

Nesta página, descrevemos como usar um servidor Zipkin para receber traces de clientes Zipkin e encaminhá-los para o Cloud Trace para análise.

Convém usar um servidor Zipkin se o aplicativo for instrumentado com Zipkin e você não quiser executar seu próprio back-end de trace ou se quiser acessar as ferramentas de análise avançadas do Cloud Trace.

Esta página descreve várias maneiras de configurar seu servidor Zipkin:

Usando uma imagem de contêiner para configurar o servidor

Uma imagem de contêiner do coletor Zipkin do Cloud Trace está disponível no GitHub. Esse repositório contém a definição de build do Docker e apresenta os níveis de suporte do Google Cloud na imagem base do Zipkin Docker, além das etapas detalhadas de configuração.

Você pode executar essa imagem no host de contêiner de sua preferência, incluindo o Google Kubernetes Engine.

Para executar a imagem, execute o código a seguir:

$ docker run -d -p 9411:9411 \
-e STORAGE_TYPE=stackdriver \
-e GOOGLE_APPLICATION_CREDENTIALS=/root/.gcp/credentials.json \
-e STACKDRIVER_PROJECT_ID=your_project \
-v $HOME/.gcp:/root/.gcp:ro \
openzipkin/zipkin-gcp

Se você estiver executando esse contêiner no Google Cloud, como em uma instância do Compute Engine ou um cluster do Google Kubernetes Engine, as credenciais padrão do ambiente serão capturadas automaticamente e os traces serão enviados automaticamente para o Cloud Trace.

Para ver o processo completo de configuração, acesse o repositório do GitHub para a imagem do Zipkin Docker.

Conforme descrito nesta página, você também precisa configurar os rastreadores do Zipkin.

Como executar seu servidor fora do Google Cloud

Se você quiser criar e executar o coletor fora do Google Cloud, como em um servidor físico em execução no local, siga estas etapas:

Crie ou selecione um projeto.

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

Não é necessário ter uma conta de faturamento porque o coletor não está sendo executado no Google Cloud.

Crie uma conta de serviço

Para permitir que seu serviço seja autenticado na API Cloud Trace:

  1. Crie uma conta de serviço.
    1. Verifique se a nova conta de serviço recebeu um papel de editor de projeto para que possa gravar dados na Trace API.
    2. Selecione Fornecer uma nova chave privada e escolha JSON.
    3. Salve o arquivo de credenciais JSON em um diretório na máquina que executará o serviço do coletor.

Configurar o firewall

Ajuste sua configuração de rede para permitir que o tráfego TCP na porta 9411 passe para a máquina por meio da execução do coletor Zipkin.

Se os aplicativos estiverem hospedados fora do firewall, o tráfego do rastreador para o coletor Zipkin não será criptografado nem autenticado. As conexões entre o coletor Zipkin do Cloud Trace e a API Cloud Trace são criptografadas e autenticadas, assim como as conexões originadas das bibliotecas de instrumentação do Cloud Trace.

Configurar seu servidor com a imagem de contêiner

Para mais informações, consulte Como usar uma imagem de contêiner.

Configurar rastreadores do Zipkin

Siga as instruções na seção comum Configurar rastreadores do Zipkin nesta página.

Modificando um servidor Zipkin existente

O projeto Zipkin mantém instruções sobre como usar o Cloud Trace como um destino de armazenamento para um servidor Zipkin existente. Estas instruções estão disponíveis no repositório do GitHub para a imagem do Zipkin Docker.

Como configurar os rastreadores do Zipkin

Independentemente de como hospedar o coletor Zipkin do Cloud Trace, você precisa configurar os rastreadores do Zipkin para enviar dados a ele.

Para fazer referência ao coletor, use o endereço IP interno, o endereço IP externo (se estiver recebendo traces de aplicativos hospedados fora do Google Cloud) ou o nome do host. Cada rastreador do Zipkin está configurado de maneira diferente. Por exemplo, para apontar um rastreador do Brave em um coletor com o endereço IP 1.2.3.4, as seguintes linhas precisam ser adicionadas à base de código Java:

    Reporter reporter = AsyncReporter.builder(OkHttpSender.create("1.2.3.4:9411/api/v1/spans")).build();
    Brave brave = Brave.Builder("example").reporter(reporter).build()

Perguntas frequentes

P: Quais são as limitações?

Esta versão tem duas limitações conhecidas:

  1. Os rastreadores do Zipkin precisam ser compatíveis com a semântica correta de duração e tempo do Zipkin. Para mais informações, acesse Como instrumentar uma biblioteca (em inglês) e role até a seção sobre Carimbos de data/hora e duração.

  2. Os rastreadores do Zipkin e as bibliotecas de instrumentação do Cloud Trace não podem anexar períodos aos mesmos traces porque usam formatos diferentes para propagar o contexto do trace entre os serviços. O resultado é que os traces capturados por uma biblioteca não contêm períodos para serviços instrumentados pela outra biblioteca.

    Por esse motivo, recomendamos que os projetos que queiram usar o Cloud Trace usem exclusivamente tracers compatíveis com Zipkin com o Zipkin Collector ou usem bibliotecas de instrumentação que funcionem com o Cloud Trace. Para mais informações sobre as bibliotecas do Cloud Trace, consulte Node.js, Java e Go.

    Exemplo:

    Ilustração das limitações de período.

    As solicitações feitas para o aplicativo da Web Node.js são rastreadas com a biblioteca do Zipkin e enviadas para o Cloud Trace. No entanto, esses traces não contêm períodos gerados pelo aplicativo da API ASP.NET. Os traces capturados pela biblioteca do Zipkin também não contêm períodos para as chamadas RPC que o aplicativo da API APS.NET faz para o banco de dados MySQL.

P: Isso funcionará como um servidor Zipkin completo?

Não, esse recurso grava dados apenas no Cloud Trace.