> ## 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.
# Dataset de demonstração remoto
> Primeiros passos com o ClickStack e um dataset de demonstração remoto
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
**O guia a seguir pressupõe que você implantou o ClickStack Open Source usando as [instruções da imagem all-in-one](/docs/pt-BR/clickstack/getting-started/oss) ou o [Modo local apenas](/docs/pt-BR/clickstack/deployment/local-mode-only) e concluiu a criação inicial do usuário. Como alternativa, você pode ignorar toda a configuração local e simplesmente se conectar à nossa demonstração hospedada do ClickStack em [play-clickstack.clickhouse.com](https://play-clickstack.clickhouse.com), que usa este conjunto de dados.**
Este guia usa um conjunto de dados de exemplo hospedado no ClickHouse playground público em [sql.clickhouse.com](https://sql.clickhouse.com), ao qual você pode se conectar a partir da sua implantação local do ClickStack.
**Sem suporte no Managed ClickStack**
Bancos de dados remotos não têm suporte ao usar Managed ClickStack. Portanto, este conjunto de dados também não é compatível.
Ele contém aproximadamente 40 horas de dados capturados da versão para ClickHouse da demonstração oficial do OpenTelemetry (OTel). Os dados são reproduzidos todas as noites, com os timestamps ajustados para a janela de tempo atual, permitindo que os usuários explorem o comportamento do sistema usando os logs, traces e métricas integrados do HyperDX.
**Variações nos dados**
Como o conjunto de dados é reproduzido a partir da meia-noite todos os dias, as visualizações exatas podem variar dependendo de quando você explora a demonstração.
## Cenário da demonstração
Nesta demonstração, investigamos um incidente envolvendo um site de e-commerce que vende telescópios e acessórios relacionados.
A equipe de suporte ao cliente informou que os usuários estão enfrentando problemas para concluir pagamentos na finalização da compra. O problema foi encaminhado à equipe de Site Reliability Engineering (SRE) para investigação.
Usando o HyperDX, a equipe de SRE analisará logs, traces e métricas para diagnosticar e resolver o problema — depois, revisará os dados de sessão para confirmar se suas conclusões correspondem ao comportamento real dos usuários.
## Demo do OpenTelemetry
Esta demo usa um [fork mantido pelo ClickStack](https://github.com/ClickHouse/opentelemetry-demo) da demo oficial do OpenTelemetry.
### Arquitetura da demo
A demo é composta por microsserviços escritos em diferentes linguagens de programação, que se comunicam entre si por gRPC e HTTP, e por um gerador de carga que usa o Locust para simular tráfego de usuários. O código-fonte original desta demo foi modificado para usar a [instrumentação do ClickStack](/docs/pt-BR/clickstack/ingesting-data/sdks/index).
*Crédito: [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
Mais detalhes sobre a demo podem ser encontrados em:
* [Documentação do OpenTelemetry](https://opentelemetry.io/docs/demo/)
* [Fork mantido pelo ClickStack](https://github.com/ClickHouse/opentelemetry-demo)
## Etapas da demonstração
**Instrumentamos esta demonstração com [ClickStack SDKs](/docs/pt-BR/clickstack/ingesting-data/sdks/index), com os serviços implantados no Kubernetes, dos quais também foram coletados métricas e logs.**
**Modo somente local**
Esta etapa pode ser ignorada se você clicou em `Connect to Demo Server` ao implantar no Modo local. Se estiver usando esse modo, os sources receberão o prefixo `Demo_`, por exemplo, `Demo_Logs`
Navegue até `Team Settings` e clique em `Edit` em `Local Connection`:
Renomeie a conexão para `Demo` e preencha o formulário a seguir com os seguintes detalhes da conexão do servidor de demonstração:
* `Connection Name`: `Demo`
* `Host`: `https://sql-clickhouse.clickhouse.com`
* `Username`: `otel_demo`
* `Password`: Deixe em branco
**Modo apenas local**
Este passo pode ser ignorado se você clicou em `Connect to Demo Server` ao implantar no modo local. Se estiver usando esse modo, as fontes terão o prefixo `Demo_`, por exemplo `Demo_Logs`
Volte até `Sources` e modifique cada uma das fontes — `Logs`, `Traces`, `Metrics` e `Sessions` — para usar o banco de dados `otel_v2`.
Talvez seja necessário recarregar a página para que a lista completa de bancos de dados apareça em cada fonte.
Ajuste o período para mostrar todos os dados do `1 day` anterior usando o seletor de tempo no canto superior direito.
Você poderá notar uma pequena diferença no número de erros no gráfico de barras da visão geral, com um pequeno aumento em vermelho em várias barras consecutivas.
A posição das barras será diferente dependendo de quando você consultar o conjunto de dados.
Para destacar ocorrências de erros, use o filtro `SeverityText` e selecione `error` para exibir apenas registros de nível de erro.
O erro deve ficar mais evidente:
Com o recurso de Clustering do HyperDX, você pode identificar erros automaticamente e agrupá-los em padrões significativos. Isso acelera a análise ao lidar com grandes volumes de logs e traces. Para usá-lo, selecione `Event Patterns` no menu `Analysis Mode` no painel esquerdo.
Os clusters de erro revelam problemas relacionados a falhas em pagamentos, incluindo um padrão chamado `Failed to place order`. Clusters adicionais também indicam problemas na cobrança de cartões e caches lotados.
Observe que esses clusters de erro provavelmente se originam de serviços diferentes.
Clique nos clusters de erro mais evidentes, que se correlacionam com o problema relatado de usuários conseguirem concluir pagamentos: `Failed to place order`.
Isso exibirá uma lista de todas as ocorrências desse erro associadas ao serviço `frontend`:
Selecione qualquer um dos erros resultantes. Os metadados dos logs serão exibidos em detalhes. Ao percorrer `Overview` e `Column Values`, fica evidente um problema na cobrança dos cartões devido a um cache:
`failed to charge card: could not charge the card: rpc error: code = Unknown desc = Visa cache full: cannot add new item.`
Identificamos um erro relacionado ao cache que provavelmente está causando falhas nos pagamentos. Ainda precisamos identificar a origem desse problema em nossa arquitetura de microsserviços.
Diante do problema de cache, faz sentido investigar a infraestrutura subjacente — talvez haja algum problema de memória nos pods associados. No ClickStack, logs e métricas são unificados e exibidos em contexto, o que facilita encontrar rapidamente a causa raiz.
Selecione a aba `Infrastructure` para ver as métricas associadas aos pods subjacentes do serviço `frontend` e amplie o intervalo de tempo para `1d`:
O problema não parece estar relacionado à infraestrutura — nenhuma métrica mudou de forma significativa ao longo do período, nem antes nem depois do erro. Feche a aba `Infrastructure`.
No ClickStack, os traces também são correlacionados automaticamente com logs e métricas. Vamos explorar o trace vinculado ao log selecionado para identificar o serviço responsável.
Selecione `Trace` para visualizar o trace associado. Ao rolar para baixo nessa visualização, podemos ver como o HyperDX consegue representar o trace distribuído entre os microsserviços, conectando os spans em cada serviço. Um pagamento claramente envolve vários microsserviços, incluindo aqueles que realizam checkout e conversões de moeda.
Ao rolar até a parte inferior da visualização, podemos ver que o serviço `payment` está causando o erro, que por sua vez se propaga de volta pela cadeia de chamadas.
Estabelecemos que os usuários não estão conseguindo concluir compras devido a um problema de cache no serviço de pagamento. Vamos explorar os traces desse serviço com mais detalhes para ver se conseguimos identificar melhor a causa raiz.
Mude para a visualização principal da Busca selecionando `Search`. Altere a fonte de dados para `Traces` e selecione a visualização `Tabela de resultados`. **Certifique-se de que o intervalo de tempo ainda esteja definido para o último dia.**
Essa visualização mostra todos os traces do último dia. Sabemos que o problema se origina no nosso serviço de pagamento, então aplique o filtro `payment` em `ServiceName`.
Se aplicarmos o agrupamento de eventos aos traces selecionando `Padrões de eventos`, podemos ver imediatamente o problema de cache no serviço `payment`.
Alterne para a visualização de resultados clicando em `Results table`. Filtre por erros usando o filtro `StatusCode` e o valor `Error`.
Selecione o erro `Error: Visa cache full: cannot add new item.`, mude para a aba `Infrastructure` e amplie o intervalo de tempo para `1d`.
Ao correlacionar traces com métricas, podemos ver que a memória e a CPU aumentaram no serviço `payment`, antes de voltarem a `0` (podemos atribuir isso à reinicialização de um pod do Kubernetes), o que sugere que o problema de cache causou problemas de recursos. Podemos esperar que isso tenha afetado os tempos de conclusão dos pagamentos.
Event Deltas ajudam a revelar anomalias ao atribuir mudanças no desempenho ou nas taxas de erro a subconjuntos específicos de dados, facilitando a rápida identificação da causa raiz.
Embora saibamos que o serviço `payment` tem um problema de cache, causando um aumento no consumo de recursos, ainda não identificamos totalmente a causa raiz.
Retorne à visualização da tabela de resultados e selecione o período que contém os erros para limitar os dados. Certifique-se de selecionar várias horas antes dos erros e, se possível, também depois deles (o problema ainda pode estar ocorrendo):
Remova o filtro de erros e selecione `Event Deltas` no menu `Analysis Mode`, à esquerda.
O painel superior mostra a distribuição das durações, com cores indicando a densidade dos eventos (número de spans). O subconjunto de eventos fora da concentração principal normalmente é o que vale a pena investigar.
Se selecionarmos os eventos com duração maior que `1ms` e aplicarmos o filtro `Filter by selection`, poderemos analisar as diferenças entre os eventos "normais" e o grupo de alta densidade de spans com duração de \~0ms:
Com a análise realizada no subconjunto de dados, podemos ver que os spans de "Background" fora da seleção são, em sua maioria, transações Visa, associadas a respostas de 0ms devido a erros de cache.
No ClickStack, podemos criar gráficos de qualquer valor numérico de logs, traces ou métricas para ter mais contexto.
Já estabelecemos que:
* O problema está no serviço de pagamento
* Um cache está cheio
* Isso causou aumento no consumo de recursos
* O problema impediu a conclusão de pagamentos com Visa — ou, no mínimo, fez com que levassem muito tempo para serem concluídos.
Selecione `Chart Explorer` no menu à esquerda. Preencha os valores a seguir para criar um gráfico do tempo que os pagamentos levam para ser concluídos:
* `Data Source`: `Traces`
* `Metric`: `Maximum`
* `SQL Column`: `Duration`
* `Where`: `ServiceName: payment`
* `Timespan`: `Last 1 day`
Ao clicar em `▶️`, você verá como o desempenho dos pagamentos se degradou ao longo do tempo.
Se definirmos `Group By` como `SpanAttributes['app.payment.card_type']` (basta digitar `card` para usar o preenchimento automático), poderemos ver como o desempenho do serviço se degradou para transações Visa em relação à Mastercard:
Observe que, quando o erro ocorre, as respostas passam a retornar em `0s`.
Por fim, vamos visualizar o tamanho do cache como uma métrica para ver como ele se comportou ao longo do tempo e, assim, obter mais contexto.
Preencha os seguintes valores:
* `Data Source`: `Metrics`
* `Metric`: `Maximum`
* `SQL Column`: `visa_validation_cache.size (gauge)` (basta digitar `cache` para o preenchimento automático)
* `Where`: `ServiceName: payment`
* `Group By`: ``
Podemos ver como o tamanho do cache aumentou ao longo de um período de 4–5 horas (provavelmente após uma implantação de software) antes de atingir o tamanho máximo de `100,000`. Em `Sample Matched Events`, vemos que nossos erros se correlacionam com o cache atingindo esse limite e, depois disso, ele passa a ser registrado com tamanho `0`, com as respostas também retornando em `0s`.
Em resumo, ao explorar logs, traces e, por fim, métricas, concluímos:
* Nosso problema está no serviço de pagamento
* Uma mudança no comportamento do serviço, provavelmente devido a uma implantação, resultou em um aumento gradual do cache de Visa ao longo de 4–5 horas, até atingir o tamanho máximo de `100,000`.
* Isso causou aumento no consumo de recursos à medida que o cache crescia — provavelmente devido a uma implementação inadequada
* À medida que o cache crescia, o desempenho dos pagamentos Visa se degradava
* Ao atingir o tamanho máximo, o cache passou a rejeitar pagamentos e a ser reportado com tamanho `0`.
As sessões nos permitem reproduzir a experiência do usuário, oferecendo um registro visual de como um erro ocorreu sob a perspectiva dele. Embora normalmente não sejam usadas para diagnosticar a causa raiz, elas são valiosas para confirmar problemas reportados ao suporte ao cliente e podem servir como ponto de partida para uma investigação mais aprofundada.
No HyperDX, as sessões são vinculadas a traces e logs, fornecendo uma visão completa da causa subjacente.
Por exemplo, se a equipe de suporte fornecer o email de um usuário que encontrou um problema de pagamento `Ronny.Windler@gmail.com`, em geral é mais eficaz começar pela sessão dele do que pesquisar diretamente em logs ou traces.
Navegue até a aba `Client Sessions` no menu à esquerda e verifique se a fonte de dados está definida como `Sessions` e se o período está definido como `Last 1 day`:
Pesquise por `SpanAttributes.userEmail: Ronny.Windler` para encontrar a sessão do nosso cliente. Ao selecionar a sessão, os eventos do navegador e os spans associados à sessão do cliente serão exibidos à esquerda, enquanto a experiência do usuário no navegador será reproduzida à direita:
As sessões podem ser reproduzidas pressionando o botão ▶️. Alternar entre `Highlighted` e `All Events` permite diferentes níveis de granularidade dos spans, com a primeira opção destacando eventos-chave e erros.
Se rolarmos até o fim dos spans, podemos ver um erro `500` associado a `/api/checkout`. Ao selecionar o botão ▶️ desse span específico, a reprodução é movida para esse ponto da sessão, o que nos permite confirmar a experiência do cliente: o pagamento simplesmente parece não funcionar, sem nenhum erro exibido.
Ao selecionar o span, podemos confirmar que isso foi causado por um erro interno. Ao clicar na aba `Trace` e percorrer os spans conectados, conseguimos confirmar que o cliente de fato foi vítima do nosso problema de cache.