> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Logs, traces e métricas de exemplo
> Primeiros passos com o ClickStack e um conjunto de dados de exemplo com logs, sessões, traces e métricas
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return
;
};
Este guia demonstra o ClickStack Open Source e o Managed ClickStack usando um conjunto de dados de exemplo.
O guia a seguir pressupõe que você concluiu o [Guia de Introdução ao Managed ClickStack](/docs/pt-BR/clickstack/deployment/managed) e tem as [credenciais de conexão anotadas](/docs/pt-BR/clickstack/getting-started/managed#next-steps).
Selecione o serviço com Managed ClickStack na página inicial do ClickHouse Cloud.
Selecione `ClickStack` no menu à esquerda para acessar a ClickStack UI, onde sua autenticação será feita automaticamente.
Para preencher a UI com dados de exemplo, baixe o arquivo a seguir:
[Dados de exemplo](https://storage.googleapis.com/hyperdx/sample.tar.gz)
```shell theme={null}
# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# or
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz
```
Este arquivo contém logs, métricas e traces de exemplo da nossa [demo pública do OpenTelemetry](https://github.com/ClickHouse/opentelemetry-demo) — uma loja virtual simples com microsserviços. Copie este arquivo para um diretório de sua escolha.
Para carregar esses dados, basta enviá-los ao endpoint HTTP do coletor OpenTelemetry (OTel) implantado.
Execute o comando a seguir para enviar os dados ao OTel collector:
```shell theme={null}
for filename in $(tar -tf sample.tar.gz); do
endpoint="http://localhost:4318/v1/${filename%.json}"
echo "loading ${filename%.json}"
tar -xOf sample.tar.gz "$filename" | while read -r line; do
printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
-H "Content-Type: application/json" \
-H "authorization: ${CLICKSTACK_API_KEY}" \
--data-binary @-
done
done
```
Isso simula fontes OTLP de logs, traces e metrics enviando dados para o OTel collector. Em produção, essas fontes podem ser clientes para linguagens específicas ou até mesmo outros OTel collectors.
Ao voltar para a visualização `Busca`, você deverá ver que os dados começaram a carregar (ajuste o período para `Last 1 hour` se os dados não aparecerem):
O carregamento dos dados levará alguns minutos. Aguarde a conclusão do carregamento antes de prosseguir para as próximas etapas.
Suponha que tenhamos relatos de que nossos usuários estão enfrentando problemas ao pagar por produtos. Podemos visualizar a experiência deles usando os recursos de replay de sessão do HyperDX.
Selecione `Client Sessions` no menu à esquerda.
Esta visualização nos permite ver as sessões de front-end da nossa loja de e-commerce. As sessões permanecem como Anonymous até que os usuários finalizem a compra e tentem concluir um pagamento.
Observe que algumas sessões com e-mails têm um erro associado, o que pode confirmar os relatos de transações com falha.
Selecione um trace com falha e um e-mail associado. A visualização seguinte nos permite reproduzir a sessão do usuário e analisar o problema. Pressione play para assistir à sessão.
A reprodução mostra o usuário navegando pelo site e adicionando itens ao carrinho. Sinta-se à vontade para avançar para um ponto mais adiante da sessão, quando ele tenta concluir o pagamento.
Os erros são anotados na linha do tempo em vermelho.
O usuário não conseguiu concluir o pedido, sem nenhum erro óbvio. Role até a parte inferior do painel esquerdo, que contém os eventos de rede e de console do navegador do usuário. Você notará que um erro 500 foi gerado ao fazer uma chamada para `/api/checkout`.
Selecione esse erro `500`. Nem `Overview` nem `Column Values` indicam a origem do problema, além do fato de que o erro é inesperado, resultando em um `Internal Error`.
Navegue até a aba `Trace` para ver o trace distribuído completo.
Role para baixo no trace para ver a origem do erro: o span do serviço `checkout`. Selecione o span do serviço `Payment`.
Selecione a aba `Column Values` e role para baixo. Podemos ver que o problema está associado a um cache cheio.
Ao subir de volta no trace, podemos ver que os logs estão correlacionados com o span, graças à configuração anterior. Eles fornecem mais contexto.
Identificamos que um cache está ficando cheio no serviço de pagamento, o que está impedindo a conclusão dos pagamentos.
Para ver mais detalhes, podemos voltar para `Busca`:
Selecione `Logs` nas fontes e aplique um filtro no serviço `payment`.
Podemos ver que, embora o problema seja recente, o número de pagamentos afetados é alto. Além disso, um cache relacionado aos pagamentos com Visa parece estar causando problemas.
Embora um erro tenha sido claramente inserido no código, podemos usar métricas para confirmar o tamanho do cache. Navegue até a visualização `Chart Explorer`.
Selecione `Metrics` como a fonte de dados. Complete o construtor de gráficos para plotar o `Maximum` de `visa_validation_cache.size (Gauge)` e pressione o botão play. O cache estava claramente aumentando até atingir um tamanho máximo, após o qual erros passaram a ser gerados.
O exemplo a seguir pressupõe que você iniciou o Open Source ClickStack seguindo as [instruções para a imagem all-in-one](/docs/pt-BR/clickstack/getting-started/oss) e se conectou à [instância local do ClickHouse](/docs/pt-BR/clickstack/getting-started/oss#complete-connection-credentials).
Acesse [http://localhost:8080](http://localhost:8080) para abrir a ClickStack UI.
Acesse [`Team Settings`](http://localhost:8080/team) e copie a `API key de ingestão` da seção `API Keys`. Essa API key garante a segurança da ingestão de dados pelo coletor do OpenTelemetry.
Para preencher a UI com dados de exemplo, baixe o arquivo a seguir:
[Dados de exemplo](https://storage.googleapis.com/hyperdx/sample.tar.gz)
```shell theme={null}
# curl
curl -O https://storage.googleapis.com/hyperdx/sample.tar.gz
# or
# wget https://storage.googleapis.com/hyperdx/sample.tar.gz
```
Este arquivo contém logs, métricas e rastreamentos de exemplo do nosso [demo público do OpenTelemetry](https://github.com/ClickHouse/opentelemetry-demo) - uma loja virtual simples com microsserviços. Copie este arquivo para um diretório de sua escolha.
Para carregar esses dados, basta enviá-los ao endpoint HTTP do coletor OpenTelemetry (OTel) implantado.
Primeiro, exporte a chave de API copiada acima.
```shell theme={null}
# export API key
export CLICKSTACK_API_KEY=
```
Execute o comando a seguir para enviar os dados ao OTel collector:
```shell theme={null}
for filename in $(tar -tf sample.tar.gz); do
endpoint="http://localhost:4318/v1/${filename%.json}"
echo "loading ${filename%.json}"
tar -xOf sample.tar.gz "$filename" | while read -r line; do
printf '%s\n' "$line" | curl -s -o /dev/null -X POST "$endpoint" \
-H "Content-Type: application/json" \
-H "authorization: ${CLICKSTACK_API_KEY}" \
--data-binary @-
done
done
```
Isso simula fontes OTLP de logs, traces e metrics enviando dados para o OTel collector. Em produção, essas fontes podem ser clientes para linguagens específicas ou até mesmo outros OTel collectors.
Ao voltar para a visualização `Busca`, você deverá ver que os dados começaram a carregar (ajuste o período para `Last 1 hour` se os dados não aparecerem):
O carregamento dos dados levará alguns minutos. Aguarde a conclusão do carregamento antes de prosseguir para as próximas etapas.
Suponha que tenhamos relatos de que nossos usuários estão enfrentando problemas para pagar por produtos. Podemos visualizar a experiência deles usando os recursos de session replay do HyperDX.
Selecione [`Client Sessions`](http://localhost:8080/sessions?from=1747312320000\&to=1747312920000\&sessionSource=l1324572572) no menu à esquerda.
Essa visualização nos permite ver as sessões de front-end da nossa loja de e-commerce. As sessões permanecem anônimas até que os usuários avancem para o checkout e tentem concluir uma compra.
Observe que algumas sessões com e-mails têm um erro associado, o que pode confirmar os relatos de transações com falha.
Selecione um trace com falha e e-mail associado. A visualização seguinte nos permite reproduzir a sessão do usuário e analisar o problema. Pressione play para assistir à sessão.
A reprodução mostra o usuário navegando pelo site e adicionando itens ao carrinho. Se quiser, avance para um ponto posterior da sessão, quando ele tenta concluir o pagamento.
Todos os erros são marcados na linha do tempo em vermelho.
O usuário não conseguiu finalizar o pedido, sem nenhum erro evidente. Role até a parte inferior do painel esquerdo, que contém os eventos de rede e console do navegador do usuário. Você notará que um erro 500 foi gerado ao fazer uma chamada para `/api/checkout`.
Selecione esse erro `500`. Nem o `Overview` nem `Column Values` indicam a origem do problema, além do fato de que o erro é inesperado, causando um `Internal Error`.
Navegue até a aba `Trace` para ver o trace distribuído completo.
Role para baixo no trace para ver a origem do erro: o span do serviço `checkout`. Selecione o span do serviço `Payment`.
Selecione a aba `Column Values` e role para baixo. Podemos ver que o problema está associado a um cache cheio.
Ao subir de volta no trace, podemos ver que os logs estão correlacionados com o span, graças à configuração anterior. Eles fornecem mais contexto.
Identificamos que um cache está ficando cheio no serviço de pagamento, o que está impedindo a conclusão dos pagamentos.
Para mais detalhes, podemos voltar para a visualização [`Busca`](http://localhost:8080/search):
Selecione `Logs` nas fontes e aplique um filtro para o serviço `payment`.
Podemos ver que, embora o problema seja recente, o número de pagamentos afetados é alto. Além disso, um cache relacionado aos pagamentos com Visa parece estar causando problemas.
Embora um erro tenha sido claramente inserido no código, podemos usar métricas para confirmar o tamanho do cache. Navegue até a visualização `Chart Explorer`.
Selecione `Metrics` como a fonte de dados. Complete o construtor de gráficos para plotar o `Maximum` de `visa_validation_cache.size (Gauge)` e pressione o botão play. O cache estava claramente aumentando até atingir um tamanho máximo, após o qual erros passaram a ser gerados.