Automatização de Documentação com Gen AI: transforme logs de observability em uma documentação técnica

Manter a documentação técnica atualizada em times ágeis é sempre um desafio. Porém, a Inteligência Artificial Generativa (Generative AI – Gen AI) tem se mostrado uma grande aliada para as equipes de tecnologia. Por isso, para tentar trazer assertividade e agilidade para o dia a dia, buscamos uma forma de automatizar a criação de  documentação com Gen AI.

O processo inclui a geração de diagramas de sequência, request/response de APIs, correlação com OpenAPI, exemplos de queries e a criação de um arquivo Markdown pronto para publicação no GitHub Pages. O resultado é uma documentação que reflete a realidade do sistema em produção, reduzindo lacunas e acelerando o onboarding e o troubleshooting.

Os problemas 

Confira a seguir alguns problemas que podem acontecer quando não há documentação:

• Velocidade x documentação: a alta velocidade de entrega em times ágeis pode resultar uma documentação desatualizada.
• Conhecimento disperso: informações críticas ficam fragmentadas entre squads e microsserviços.
• Rastreamento de jornadas: dificuldade em mapear fluxos completos que envolve BFFs, backends e integrações.
• Observabilidade subutilizada: ferramentas como Splunk, Grafana e Datadog fornecem dados ricos, mas que raramente são reaproveitados para a documentação.

A proposta

Utilizar a StackSpot AI como uma orquestradora de automações para:

1. Processar logs exportados de ferramentas de observabilidade (Splunk, Grafana, Datadog, etc.) em um formato padronizado (JSON).
2. Organizar e normalizar a jornada (atores, chamadas, status).
3. Gerar diagramas de sequência com base nos eventos.
4. Correlacionar os logs com a documentação OpenAPI (Swagger) dos microsserviços.
5. Sugerir queries de troubleshooting para a ferramenta de observabilidade utilizada.
6. Montar a documentação final em Markdown com um template padronizado.
7. Publicar automaticamente no GitHub Pages.

Para isso, iremos usar dois recursos fundamentais da StackSpot AI:

Quick Command (QC): instruções predefinidas para executar e automatizar ações específicas.

Knowledge Sources (KS): fontes de conhecimento que trazem contextualização e personalização para as respostas da AI. 

Arquitetura em Alto Nível

• Fonte de Dados: Logs exportados de ferramentas de observabilidade (Splunk, Grafana, Datadog, etc.) em JSON.
• Orquestração: criação do Remote Quick Command na StackSpot AI. Confira a seguir como o QC foi criado: 

• Knowledge Sources: o KS foi a documentação OpenAPI dos microsserviços para validação e correlação.
• Automação Cliente: foi um script em Python para gerenciar o fluxo de execução, desde o envio dos logs até a publicação da documentação.

O código a seguir mostra a integração com o Quick Command criado por meio da StackSpot AI e o retorno do arquivo de documentação gerado:

Pipeline de Processamento:

Confira a seguir como foi criado a pipeline de processamento

1. Formatação e enriquecimento dos Logs:
   • Normalização do JSON exportado.
   • Ordenação dos eventos por linha do tempo.
   • Extração de campos relevantes (método, URL, statusCode, tempos, etc.).

2. Geração do diagrama de sequência:
   • Identificação dos participantes da jornada (App, BFF, serviços externos).
   • Criação de um esboço de sequência com base nos eventos reais.

3. Correlação com OpenAPI:
   • Validação de endpoints, verbos, paths e schemas observados contra a especificação Swagger.
   • Identificação de desvios entre o comportamento documentado e o comportamento real.

4. Sugestão de queries na ferramenta de observabilidade:
   • Geração de consultas práticas para troubleshooting, baseadas em campos como correlationId, path e status.

5. Montagem do Documento Final (Markdown):
   • Estrutura padrão:
     • Visão geral da jornada.
     • Diagrama de sequência.
     • Exemplos de request/response.
     • Lista de integrações e dependências.
     • Métricas e dicas de observabilidade.
     • Exemplos de queries na ferramenta de observabilidade.

O vídeo a seguir mostra como funciona o Agente, seguindo os passos explicados anteriormente. Ele já sabe qual é o padrão esperado para gerar a documentação.

Flexibilidade com ferramentas de observabilidade

Embora a prova de conceito tenha usado o Splunk, o processo também pode ser aplicado a outras ferramentas de observabilidade, como Grafana ou Datadog. O único requisito é padronizar o formato dos logs de entrada. Assim, o agente de IA da StackSpot AI conseguirá analisar as informações e executar seu trabalho.

Resultados da Prova de Conceito

• Documentação automatizada: gerada diretamente a partir dos eventos reais observados em produção.
• Onboarding acelerado: sequências e exemplos prontos para novos membros do time.
• Redução de lacunas: menor discrepância entre o que está documentado e o que realmente ocorre.
• Troubleshooting facilitado: queries úteis para suporte e SRE disponíveis na documentação.
• Processo replicável: pipeline versionada e pronta para escalar para outras jornadas.

Resultado da documentação: 

Próximos Passos

• Integração do pipeline à esteira CI/CD.
• Expansão do catálogo de Knowledge Sources.
• Inclusão de testes de conformidade entre logs e OpenAPI.
• Enriquecimento com métricas de APM (Monitoramento de Performance de Aplicações) e traces distribuídos.

Conclusão

Automatizar a documentação técnica com a StackSpot muda completamente a forma como as equipes gerenciam o conhecimento. Com a StackSpot, a documentação é sempre atualizada, refletindo o estado real do sistema. Isso reduz falhas de informação e acelera o onboarding de novos membros.

Ao integrar operação e conhecimento, a StackSpot permite que o próprio sistema gere sua documentação quase em tempo real.

Quer saber como aplicar essa solução no seu time? Entre em contato e descubra como elevar sua documentação técnica a um novo patamar com a StackSpot!