> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-86180b7b.mintlify.site/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}) => {
return
;
};
**O guia a seguir pressupõe que você implantou o ClickStack Open Source usando as [instruções da imagem all-in-one](/pt-BR/clickstack/getting-started/oss) ou o [Modo local apenas](/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](/pt-BR/clickstack/ingesting-data/sdks).
*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](/pt-BR/clickstack/ingesting-data/sdks), com os serviços implantados no Kubernetes, dos quais também foram coletados métricas e logs.**
### Conecte-se ao servidor de demonstração
**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, as 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 de conexão do servidor de demonstração:
* `Connection Name`: `Demo`
* `Host`: `https://sql-clickhouse.clickhouse.com`
* `Username`: `otel_demo`
* `Password`: Deixe em branco
### Modifique as fontes
**Modo apenas local**
Esta etapa pode ser ignorada se você clicou em `Connect to Demo Server` ao implantar no modo local. Se estiver usando esse modo, as fontes virão com o prefixo `Demo_`, por exemplo, `Demo_Logs`
Role 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 garantir que a lista completa de bancos de dados apareça em cada fonte.
### Ajuste o intervalo de tempo
Ajuste o período para mostrar todos os dados do `1 day` anterior usando o seletor de tempo no canto superior direito.
Você pode 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.
### Filtrar por erros
Para destacar ocorrências de erros, use o filtro `SeverityText` e selecione `error` para exibir apenas registros no nível de erro.
O erro deve ficar mais evidente:
### Identifique os padrões de erro
Com o recurso Clustering do HyperDX, você pode identificar erros automaticamente e agrupá-los em padrões significativos. Isso agiliza a análise ao lidar com grandes volumes de logs e traces. Para usá-lo, selecione `Event Patterns` no menu `Analysis Mode` no painel à esquerda.
Os clusters de erro revelam problemas relacionados a falhas em pagamentos, incluindo um padrão chamado `Failed to place order`. Outros clusters também indicam problemas na cobrança de cartões e caches cheios.
Observe que esses clusters de erro provavelmente se originam de serviços diferentes.
### Explorar um padrão de erro
Clique no cluster de erro mais evidente, que corresponde ao 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 exibidos. Os metadados dos logs serão mostrados em detalhes. Ao percorrer `Overview` e `Column Values`, fica evidente um problema na cobrança dos cartões devido ao cache:
`failed to charge card: could not charge the card: rpc error: code = Unknown desc = Visa cache full: cannot add new item.`
### Explore a infraestrutura
Identificamos um erro relacionado ao cache que provavelmente está causando falhas nos pagamentos. Ainda precisamos identificar de onde esse problema está se originando na nossa arquitetura de microsserviços.
Diante do problema de cache, faz sentido investigar a infraestrutura subjacente — talvez haja um problema de memória nos pods associados. No ClickStack, logs e métricas são unificados e exibidos em contexto, o que facilita descobrir 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.
### Explore um trace
No ClickStack, os traces também são automaticamente correlacionados 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 a tela na visualização seguinte, podemos ver como o HyperDX consegue visualizar o trace distribuído entre os microsserviços, conectando os spans em cada serviço. Um pagamento claramente envolve vários microsserviços, incluindo os que processam o checkout e as conversões de moeda.
Ao rolar até o fim 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.
### Buscando traces
Já sabemos 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 em mais detalhes para ver se conseguimos entender melhor a causa raiz.
Mude para a visualização principal de Busca selecionando `Search`. Altere a fonte de dados para `Traces` e selecione a visualização `Results table`. **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` a `ServiceName`.
Se aplicarmos o agrupamento de eventos aos traces selecionando `Event Patterns`, veremos imediatamente o problema de cache no serviço `payment`.
### Analise a infraestrutura de um trace
Mude para a visualização de resultados clicando em `Results table`. Filtre os 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 o uso de memória e CPU do serviço `payment` aumentou antes de cair para `0` (podemos atribuir isso à reinicialização de um pod do Kubernetes), o que sugere que o problema de cache causou problemas de recursos. É de se esperar que isso tenha impactado os tempos de processamento dos pagamentos.
### Event Deltas para uma resolução mais rápida
O Event Deltas ajuda a destacar anomalias ao atribuir mudanças no desempenho ou nas taxas de erro a subconjuntos específicos de dados, facilitando a identificação rápida da causa raiz.
Embora saibamos que o serviço `payment` tem um problema de cache, causando aumento no consumo de recursos, ainda não identificamos completamente a causa raiz.
Volte para a visualização da tabela de resultados e selecione o período de tempo que contém os erros para restringir os dados. Certifique-se de selecionar várias horas antes dos erros e, se possível, também depois deles (o problema pode ainda estar ocorrendo):
Remova o filtro de erros e selecione `Event Deltas` no menu `Analysis Mode`, à esquerda.
O painel superior mostra a distribuição dos tempos, com cores indicando a densidade de eventos (número de spans). O subconjunto de eventos fora da concentração principal normalmente é o que mais 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 spans de alta densidade com duração de \~0ms:
Com a análise feita 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.
### Usando gráficos para mais contexto
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 demorassem muito 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 serem 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 voltam em `0s`.
### Explorando métricas com mais contexto
Por fim, vamos plotar o tamanho do cache como uma métrica para ver como ele se comportou ao longo do tempo, obtendo assim mais contexto.
Preencha os seguintes valores:
* `Data Source`: `Metrics`
* `Metric`: `Maximum`
* `SQL Column`: `visa_validation_cache.size (gauge)` (basta digitar `cache` para autocompletar)
* `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 estão correlacionados 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:
* O 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 do 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 registrar tamanho `0`.
### Usando sessões
As sessões nos permitem reproduzir a experiência do usuário, oferecendo um registro visual de como ocorreu um erro na perspectiva dele. Embora normalmente não sejam usadas para diagnosticar causas raiz, elas são valiosas para confirmar problemas relatados 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 e-mail de um usuário que teve um problema com pagamento `Ronny.Windler@gmail.com` - geralmente é mais eficaz começar pela sessão dele em vez de pesquisar diretamente em logs ou traces.
Navegue até a aba `Client Sessions` no menu à esquerda e, antes disso, 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, você verá à esquerda os eventos do navegador e os spans associados à sessão do cliente, enquanto a experiência dele no navegador será reproduzida à direita:
### Reproduzindo sessões
As sessões podem ser reproduzidas clicando no botão ▶️. Alternar entre `Highlighted` e `All Events` permite diferentes níveis de granularidade dos spans, sendo que a primeira opção destaca eventos-chave e erros.
Se rolarmos até o fim dos spans, podemos ver um erro `500` associado a `/api/checkout`. Selecionar o botão ▶️ desse span específico leva a reprodução para esse ponto da sessão, permitindo 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.
Esta demonstração apresenta um incidente real envolvendo falhas em pagamentos em um aplicativo de e-commerce e mostra como o ClickStack ajuda a identificar as causas raiz por meio de logs, traces, métricas e replays de sessão unificados - explore nossos [outros guias de primeiros passos](/pt-BR/clickstack/example-datasets) para se aprofundar em funcionalidades específicas.