Em um mercado cada vez mais filtrado por algoritmos, visibilidade profissional deixou de ser vaidade. Para engenheiros de software, ela passou a ser parte da estratégia de carreira.

Historicamente, a reputação na engenharia de software foi construída no silêncio dos repositórios. Durante muito tempo, a senioridade de um profissional técnico parecia depender quase exclusivamente da robustez de suas entregas, da elegância de suas arquiteturas, da qualidade das decisões técnicas e da capacidade de resolver problemas complexos sob pressão. Esse modelo ajudou a consolidar um mito que ainda persiste em parte da comunidade: o de que o bom desenvolvedor deve ser invisível e de que o código, por si só, deveria ser suficiente para abrir portas. 📈

Durante um bom tempo, essa lógica pareceu razoável. Em mercados menos saturados, em ecossistemas mais locais e em um cenário em que o networking digital ainda não era tão dominante, ser tecnicamente muito bom de fato gerava reconhecimento de maneira relativamente orgânica. A reputação circulava por indicação, por histórico de entregas, por recomendações de líderes e pela capacidade de resolver problemas reais dentro das empresas.

O problema é que o mercado de tecnologia mudou.

Hoje, a competição é global, os processos de recrutamento são mais orientados por dados, as plataformas intermediam visibilidade e os algoritmos passaram a influenciar de maneira concreta quem é encontrado, quem é lembrado e quem é abordado. Em um ambiente assim, competência continua sendo essencial, mas visibilidade também passou a ser estratégica.

Isso não significa superficialidade. Não significa transformar engenharia em performance vazia. Também não significa substituir profundidade técnica por conteúdo raso. Significa apenas reconhecer que, em um mercado filtrado por plataformas, não basta ser bom. É preciso ser encontrável.

Essa talvez seja uma das mudanças mais desconfortáveis para muitos profissionais técnicos. A comunidade de engenharia foi treinada, por muitos anos, para acreditar que marketing pessoal era quase sempre sinônimo de vaidade, e que exposição pública diminuía o rigor técnico. Só que essa leitura não resiste bem à realidade atual. Se o mercado simplesmente não consegue enxergar sua trajetória, sua experiência e sua capacidade de pensar tecnicamente, parte do seu valor profissional deixa de circular.

É nesse ponto que o Social Selling Index, o SSI do LinkedIn, ganha relevância.

Embora o nome tenha uma conotação comercial, o SSI funciona, na prática, como um indicador de maturidade da presença profissional na plataforma. Ele mede, em uma escala de zero a cem, o quanto o perfil demonstra consistência em quatro pilares: marca profissional, conexão com as pessoas certas, compartilhamento de insights e construção de relacionamentos. No universo da engenharia, isso pode ser traduzido como autoridade técnica percebida, posicionamento estratégico e capacidade de atrair oportunidades de forma orgânica.

Muitos profissionais de tecnologia ignoram essa métrica. E, de certa forma, é compreensível. O nome não ajuda. A aparência sugere algo mais voltado para vendas do que para carreira técnica. Mas o erro está justamente em parar na superfície. O SSI não é apenas sobre vender. Ele é, sobretudo, sobre ser encontrado, compreendido e considerado relevante por uma rede profissional que opera cada vez mais por sinais de autoridade.

Para tornar essa análise menos abstrata, vale usar um exemplo prático.

No meu caso, o gráfico recente aponta uma pontuação geral de 51. Em uma leitura apressada, esse número poderia parecer apenas mediano dentro de uma escala de zero a cem. Mas o dado realmente importante não está apenas no número absoluto. Está no posicionamento relativo que ele gera. Com essa pontuação, o perfil já aparece entre os 9% melhores da indústria de desenvolvimento de software. Ao mesmo tempo, a média geral do setor está em 31

Veja como está seu SSI do Linkedin, clicando aqui. 🔎

Essa comparação é mais reveladora do que a pontuação isolada. Ela mostra que a maior parte dos profissionais da área ainda permanece distante de uma atuação estratégica dentro da rede. Em outras palavras, existe uma oportunidade real para quem consegue sair da invisibilidade técnica e construir presença com mais intenção.

Ao olhar os componentes do gráfico, o diagnóstico fica mais claro. Uma pontuação mais forte em marca profissional e construção de relacionamentos sugere que a base do perfil está relativamente sólida e que existe algum nível de rede ativa. Por outro lado, notas mais baixas em localização das pessoas certas e engajamento com insights revelam os gargalos da estratégia. O algoritmo, nesse caso, faz quase o papel de um avaliador silencioso. Ele mostra onde existe presença, mas também aponta onde ainda falta intencionalidade.

Essa leitura é importante porque ajuda a desmontar um equívoco comum. Muitas pessoas imaginam que autoridade digital é uma consequência espontânea da qualidade do trabalho. Na prática, não é bem assim. Autoridade percebida em plataformas depende de evidência distribuída. O mercado precisa ver sinais recorrentes de coerência, especialidade, profundidade e participação.

É por isso que o perfil importa.

Um perfil técnico mal estruturado costuma desperdiçar muito valor. Títulos genéricos, descrições superficiais, palavras-chave pouco aderentes ao mercado global, ausência de clareza sobre senioridade, setores de atuação e stack principal fazem com que o algoritmo entenda menos do que deveria. E se a plataforma entende menos, os recrutadores também enxergam menos.

No caso da área de software, isso fica ainda mais evidente quando o profissional busca mercado internacional. Um recrutador estrangeiro não parte do zero em uma busca manual. Ele utiliza filtros, palavras-chave, senioridade, sinais de atividade e contexto de perfil. Em muitos casos, o primeiro contato não nasce da candidatura do profissional, mas da capacidade do sistema de classificá-lo como relevante.

Isso muda completamente a lógica da carreira técnica.

Em vez de depender apenas de candidaturas ativas, o profissional passa a construir as condições para ser encontrado de forma passiva. Esse é um ponto especialmente importante para engenheiros mais experientes. Senioridade não deveria depender exclusivamente de enviar currículo em massa. Em muitos casos, ela deveria atrair conversas qualificadas.

Só que isso não acontece por acaso.

A estruturação da marca profissional é o primeiro passo. Isso significa um perfil bem escrito, headline objetiva, resumo coerente com posicionamento de carreira, experiências com narrativa clara, tecnologias relevantes descritas com contexto e uma linguagem que faça sentido tanto para humanos quanto para algoritmos. Não se trata de inflar o perfil. Trata-se de torná-lo inteligível.

No contexto internacional, isso ganha ainda mais peso. Termos locais, expressões muito informais ou descrições vagas reduzem a legibilidade do perfil para recrutadores estrangeiros. Em vez de usar apenas cargos pouco padronizados, faz mais sentido adotar nomenclaturas que dialoguem com o vocabulário global da indústria, como Senior Software Engineer, Backend Engineer, Full Stack Engineer, Distributed Systems Engineer ou Technical Lead, sempre de forma coerente com a trajetória real.

O segundo pilar do SSI envolve encontrar as pessoas certas. E esse ponto costuma ser subestimado por profissionais técnicos. Muitos enxergam a rede apenas como acúmulo de contatos, quando na prática o valor está muito mais na qualidade da malha de conexões. Conectar-se com recrutadores especializados, líderes de engenharia, CTOs, founders, staff engineers, principal engineers e profissionais de referência do setor amplia o contexto em que o perfil circula.

Essa conexão, por si só, não faz milagre. Mas ela muda o ambiente de distribuição da reputação.

Quando um profissional técnico publica bons insights, comenta com consistência ou participa de discussões relevantes dentro de uma rede qualificada, ele passa a ser visto no contexto certo. Isso é diferente de publicar para o vazio. É também diferente de falar apenas para a própria bolha imediata.

O terceiro pilar, o de insights, talvez seja o mais decisivo para quem quer sair do anonimato técnico sem perder profundidade. Muitos engenheiros continuam acreditando que produzir conteúdo é necessariamente superficial. Mas isso só é verdade quando o conteúdo é vazio. Existe um espaço enorme para publicações maduras, reflexivas, didáticas e estrategicamente técnicas.

Escrever sobre testes automatizados, arquitetura assíncrona, observabilidade, CI/CD, sistemas distribuídos, segurança, privacidade, performance, trade-offs de engenharia, liderança técnica e decisões reais de projeto não é virar influenciador genérico. É documentar inteligência aplicada. É transformar experiência em capital de reputação.

Essa transformação é importante porque ela rompe uma barreira silenciosa. Um excelente engenheiro pode construir soluções extraordinárias dentro da empresa em que atua e, ainda assim, permanecer invisível para o resto do mercado. Ao escrever, comentar e publicar com consistência, ele faz com que parte da sua capacidade deixe de ficar restrita aos sistemas internos que ajudou a construir.

Isso é especialmente poderoso quando o conteúdo é pensado de forma estratégica. Artigos no Medium, posts no LinkedIn, comentários maduros em discussões relevantes e análises próprias sobre temas da indústria criam sinais recorrentes de autoridade. O profissional deixa de ser apenas alguém que executa tecnicamente e passa a ser percebido como alguém que pensa tecnicamente.

Essa percepção tem impacto.

Ela influencia abordagens de recrutadores, qualidade das conexões, visibilidade em buscas, reconhecimento por pares e até confiança do mercado sobre seu nível de senioridade. Em muitos casos, o conteúdo não substitui a experiência, mas ajuda o mercado a reconhecer essa experiência com mais velocidade.

O quarto pilar, o de relacionamentos, é o que transforma visibilidade em rede. Porque autoridade digital sem relacionamento pode acabar se tornando apenas presença estática. E carreira, no fim, é profundamente relacional. Comentários relevantes, interações consistentes, trocas com outros profissionais, apoio a discussões qualificadas e manutenção de vínculos ao longo do tempo ajudam a construir profundidade.

Isso não precisa acontecer de maneira artificial. Muito pelo contrário. Em ambientes maduros, relacionamento digital funciona melhor quando nasce de interesse real, reciprocidade intelectual e contribuição consistente.

Ao juntar esses quatro pilares, o SSI se torna menos uma curiosidade estatística e mais um painel de diagnóstico da presença profissional. Ele não define a qualidade do engenheiro. Mas revela como essa qualidade está sendo percebida e distribuída dentro de uma das plataformas mais relevantes para recrutamento e posicionamento de carreira.

Existe ainda outro ponto importante: a volatilidade da reputação digital.

Muita gente acredita que autoridade no LinkedIn se comporta como um troféu permanente. Não funciona assim. Relevância em plataformas é dinâmica. Perfis que param de publicar, deixam de interagir, perdem clareza de posicionamento ou abandonam consistência tendem a reduzir presença. O mesmo vale para programas de reconhecimento mais visíveis, como ecossistemas de destaque editorial e selos de relevância. O mercado digital premia continuidade muito mais do que picos isolados.

Isso pode parecer duro, mas é coerente. O que a plataforma valoriza não é apenas a existência passada de um bom conteúdo, mas a recorrência da contribuição.

Para profissionais que desejam aumentar exposição internacional, esse ponto se torna ainda mais decisivo. Publicar em inglês, por exemplo, não é só uma escolha estética. É uma decisão de distribuição. Escrever apenas em português limita bastante o alcance geográfico do conteúdo. Isso não significa abandonar totalmente o idioma local, mas significa compreender que a língua também é uma camada de estratégia.

Outro ponto essencial é a qualidade semântica do perfil. O algoritmo trabalha por sinais. Se o perfil comunica com clareza tecnologias, senioridade, contexto de atuação e capacidade de entrega, ele se torna mais legível para ferramentas de busca e recrutamento. Se não comunica, perde espaço mesmo que a experiência real seja excelente.

No fundo, toda essa discussão gira em torno de uma verdade simples e desconfortável: muitos profissionais técnicos continuam escondidos. Não porque lhes falte competência. Mas porque lhes falta distribuição.

Essa distinção é central.

Ser bom continua indispensável. Mas ser visto passou a ser parte da equação profissional. O mercado não recompensa apenas quem sabe. Também recompensa quem consegue tornar o próprio conhecimento visível, confiável e encontrável.

Isso não reduz a engenharia. Isso amplia o alcance dela.

Talvez a frase que melhor resuma esse cenário seja esta: repositórios mostram o que você construiu, mas o LinkedIn mostra se o mercado consegue encontrar você.

A partir daí, a pergunta se torna inevitável. Sua carreira técnica está sendo descoberta pelo mercado ou continua presa aos bastidores da empresa onde você trabalha?

Se a resposta ainda aponta para invisibilidade, talvez o problema não esteja na sua competência. Talvez esteja apenas no fato de que a sua inteligência profissional ainda não foi estruturada de forma visível o suficiente para circular.

E, em um mercado global, circular também é uma forma de crescer.

Quando o conhecimento técnico ganha distribuição, ele deixa de ficar restrito à empresa atual e passa a circular no mercado global. 🌟

Testes automatizados, processos assíncronos, observabilidade e CI/CD não são apenas decisões técnicas. São a base que separa sistemas preparados para crescer de sistemas que apenas acumulam risco em silêncio.

Existe uma diferença muito importante entre um sistema que cresce e um sistema que escala. Essa diferença costuma ser ignorada no início de muitos projetos, principalmente quando tudo ainda parece estar sob controle. O time consegue entregar, os usuários conseguem utilizar, os problemas ainda são pontuais e a operação parece responder bem ao ritmo do negócio.

Nesse momento, crescer parece simples.

Mais usuários entram. Mais funcionalidades são desenvolvidas. Mais integrações são adicionadas. Mais dados passam a circular pelo sistema. O produto ganha corpo, a operação aumenta e a empresa começa a depender cada vez mais da tecnologia para funcionar.

O problema é que crescimento não é a mesma coisa que escala.

Crescer significa aumentar volume. Escalar significa sustentar esse aumento sem perder estabilidade, previsibilidade e capacidade de evolução. Um sistema pode crescer bastante e, ainda assim, não estar preparado para escalar. Pode ter muitos usuários e continuar frágil. Pode ter muitas funcionalidades e ser difícil de manter. Pode ter boa infraestrutura e ainda assim sofrer com deploys arriscados, falhas silenciosas, gargalos escondidos e medo constante de mudança.

Essa é uma das armadilhas mais comuns em tecnologia.

A empresa olha para o sistema funcionando e conclui que ele está saudável. Mas funcionamento não significa maturidade. Um sistema pode estar no ar e, ao mesmo tempo, estar acumulando risco. Pode responder requisições e, ainda assim, estar cada vez mais difícil de evoluir. Pode parecer estável por fora e estar cheio de dependências frágeis por dentro.

No começo, esse risco costuma ser invisível.

O time compensa com esforço manual. Alguém sabe onde mexer. Alguém lembra quais telas precisam ser testadas. Alguém acompanha o deploy. Alguém confere os logs. Alguém resolve a fila travada. Alguém reinicia o serviço. Alguém valida a integração externa. Alguém sabe o caminho.

O problema é que escala não combina com dependência informal.

Quando um sistema depende demais de pessoas específicas, validações manuais, conhecimento não documentado e sorte operacional, ele pode até continuar funcionando, mas não está operando com maturidade. Está apenas sendo sustentado por esforço humano.

E esforço humano tem limite.

Em algum momento, a complexidade supera a capacidade do time de controlar tudo manualmente. Mais pessoas entram no projeto, mais serviços são criados, mais áreas dependem do sistema, mais integrações se tornam críticas e mais alterações precisam acontecer ao mesmo tempo. O que antes era administrável passa a se tornar imprevisível.

É nesse ponto que os fundamentos aparecem.

Sistemas que escalam de verdade não dependem apenas de bons desenvolvedores, boa infraestrutura ou ferramentas modernas. Eles dependem de uma base de engenharia capaz de sustentar crescimento com consistência.

Essa base passa por quatro pilares principais: testes automatizados, processos assíncronos, observabilidade e CI/CD.

Esses quatro elementos não resolvem todos os problemas de um sistema, mas reduzem drasticamente o risco de crescimento desorganizado. Eles criam uma estrutura para que o software possa mudar, processar, ser compreendido e ser entregue com segurança.

Sem eles, o sistema pode crescer. Mas cresce acumulando fragilidade.

O primeiro pilar são os testes automatizados.

Testes automatizados são, muitas vezes, tratados como uma prática de qualidade. Essa leitura não está errada, mas é pequena demais. Em sistemas que precisam escalar, testes não existem apenas para encontrar bugs. Eles existem para criar confiança.

Confiança para alterar código. Confiança para refatorar. Confiança para corrigir problemas. Confiança para lançar novas funcionalidades. Confiança para permitir que mais pessoas trabalhem no mesmo sistema sem transformar cada mudança em risco.

Sem testes, o time passa a depender de validação manual. Isso funciona por um tempo, principalmente quando o sistema é pequeno e poucas pessoas conhecem bem o fluxo. Mas conforme o sistema cresce, a validação manual se torna insuficiente. Ninguém consegue lembrar de todos os cenários. Ninguém consegue testar tudo sempre. Ninguém consegue prever todos os impactos de uma alteração.

É nesse momento que o medo começa a substituir a fluidez.

Uma pequena mudança passa a exigir cuidado excessivo. Uma correção simples demanda múltiplas validações. Um deploy começa a gerar tensão. O time evita mexer em partes antigas do sistema. Bugs antigos reaparecem. Funcionalidades que funcionavam deixam de funcionar depois de mudanças aparentemente desconectadas.

O problema não é apenas técnico. É operacional.

Quando o time perde confiança no código, a empresa perde velocidade de evolução.

Ferramentas como Jest, Vitest, Testing Library, Cypress e Playwright ajudam no frontend, validando componentes, telas e jornadas do usuário. No backend, frameworks como xUnit, NUnit, PyTest, Mocha, Jest, PHPUnit e JUnit ajudam a validar regras de negócio, serviços, integrações e comportamentos críticos.

A diferença entre essas camadas é importante. No frontend, o foco está na experiência e na interação. No backend, o foco está na regra, no processamento e na consistência. Uma aplicação madura precisa olhar para as duas pontas.

Um teste simples de backend pode validar uma regra essencial de pedido:

describe('OrderService', () => {
  it('should calculate the order total correctly', async () => {
    const order = await OrderService.create({
      customerId: 10,
      items: [
        { productId: 1, quantity: 2, price: 100 }
      ]
    });
    expect(order.total).toBe(200);
    expect(order.status).toBe('pending');
  });
});

Esse exemplo é simples, mas representa algo fundamental: uma regra importante não depende apenas da memória de alguém para ser validada. Ela passa a fazer parte de uma base executável de confiança.

Testes automatizados não tornam o sistema perfeito. Nenhum teste faz isso. Mas eles reduzem a chance de erros previsíveis chegarem em produção. Eles ajudam a preservar comportamentos importantes. Eles tornam a evolução menos arriscada.

E, principalmente, eles permitem que o time continue mudando.

Porque um sistema que não pode ser alterado com segurança deixa de ser uma plataforma de crescimento e passa a ser uma fonte de medo.

O segundo pilar é processamento assíncrono.

Um dos sinais mais claros de fragilidade em sistemas que crescem é a dependência excessiva entre operações. No início, é comum que tudo aconteça dentro do mesmo fluxo. Uma requisição chega, o backend processa todas as etapas e retorna uma resposta.

Esse modelo é simples, produtivo e fácil de entender. Frameworks como Express, ASP.NET, Django, Laravel e Spring Boot tornam esse tipo de desenvolvimento bastante direto. Para sistemas pequenos, funciona muito bem.

O problema começa quando o fluxo cresce junto com o negócio.

Uma operação que antes apenas salvava um cadastro passa a validar dados, consultar APIs externas, enviar e-mails, atualizar dashboards, gerar histórico, publicar notificações e disparar integrações. Um pedido deixa de ser apenas um pedido. Ele passa a envolver estoque, pagamento, nota fiscal, comunicação, relatórios e sistemas terceiros.

Quando tudo isso acontece de forma síncrona, cada etapa adiciona tempo e risco à operação principal.

Se uma API externa fica lenta, o usuário espera. Se o serviço de e-mail falha, uma operação que não deveria depender dele pode ser bloqueada. Se uma integração está fora do ar, o fluxo inteiro pode ser comprometido. Se uma rotina pesada consome recursos demais, outros usuários podem ser afetados.

Esse é o efeito dominó aplicado à arquitetura.

Muitas empresas tentam resolver esse problema aumentando infraestrutura. Colocam mais servidores, aumentam memória, escalam containers, adicionam cache e criam réplicas. Tudo isso pode ajudar, mas não corrige o problema central quando a causa é acoplamento.

Se tudo depende de tudo, o sistema continua frágil.

Processos assíncronos mudam essa lógica. Eles permitem separar o que precisa acontecer agora daquilo que pode acontecer depois. Em vez de executar todas as etapas dentro da mesma requisição, o sistema publica eventos, envia mensagens para filas ou delega tarefas para workers.

Ferramentas como RabbitMQ, Kafka, AWS SQS, Google Pub/Sub e Azure Service Bus ajudam a implementar essa separação. RabbitMQ funciona muito bem para filas tradicionais e distribuição de tarefas. Kafka é forte para alto volume de eventos, streaming e múltiplos consumidores. SQS, Pub/Sub e Azure Service Bus simplificam esse modelo em ambientes cloud.

Mais importante do que a ferramenta é a mudança de mentalidade.

A pergunta deixa de ser “como faço tudo isso mais rápido?” e passa a ser “o que realmente precisa acontecer agora e o que pode acontecer depois?”.

Essa pergunta melhora a arquitetura.

Um fluxo síncrono de pedido poderia ser assim:

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await issueInvoice(order);
  await sendConfirmationEmail(order);
  await notifyExternalMarketplace(order);
  res.json({
    success: true,
    orderId: order.id
  });
});

Esse código parece organizado, mas concentra responsabilidades demais em um único fluxo. Uma versão mais resiliente poderia separar o essencial do complementar:

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await queue.publish('order.created', {
    orderId: order.id,
    customerId: order.customerId
  });
  res.json({
    success: true,
    orderId: order.id
  });
});

Nesse modelo, o fluxo principal responde ao usuário depois do que é essencial. O restante pode ser processado em segundo plano. Um worker envia e-mail. Outro emite nota. Outro atualiza relatórios. Outro notifica sistemas externos.

Isso não elimina falhas, mas impede que falhas secundárias derrubem o fluxo principal.

Essa é a essência da resiliência.

O terceiro pilar é observabilidade.

Se testes ajudam a validar o que deveria funcionar e processos assíncronos ajudam a organizar responsabilidades, observabilidade ajuda a responder uma pergunta essencial: o sistema está realmente se comportando como deveria em produção?

Essa pergunta é mais difícil do que parece.

Em sistemas simples, logs e métricas básicas costumam ser suficientes. Um erro aparece, alguém abre o log, encontra a exceção e corrige. Existe uma relação direta entre causa e efeito.

Em sistemas que crescem, essa relação fica menos óbvia.

Mais serviços entram no fluxo. Mais integrações são adicionadas. Filas processam eventos em segundo plano. Bancos diferentes são consultados. O frontend pode apresentar erros que o backend não enxerga. O backend pode estar saudável enquanto uma jornada do usuário está quebrada. Uma fila pode crescer silenciosamente sem afetar a interface imediatamente.

Nesse cenário, problemas não aparecem como respostas simples. Eles aparecem como sintomas.

Um endpoint fica lento. Uma integração falha de forma intermitente. Um usuário reclama de uma tela travada. Uma fila acumula mensagens. Um serviço consome mais memória do que deveria. O checkout demora apenas para alguns clientes. O erro real pode estar três serviços antes do ponto onde o sintoma apareceu.

Sem observabilidade, o time adivinha.

Com observabilidade, o time investiga.

Observabilidade normalmente se apoia em três sinais principais: métricas, logs e traces. Métricas mostram comportamento quantitativo ao longo do tempo, como latência, tráfego, erro e saturação. Logs registram eventos específicos. Traces mostram o caminho real de uma requisição entre diferentes serviços.

O valor aparece quando esses sinais são conectados.

Um trace pode mostrar algo assim:

Client
  → API Gateway: 45ms
    → Auth Service: 30ms
    → Order Service: 120ms
      → Database: 80ms
      → Payment Service: 2,400ms
        → External Provider: 2,200ms
    → Response: 2,610ms

Nesse exemplo, não é necessário adivinhar. O gargalo está no serviço de pagamento e, mais especificamente, no provedor externo. A discussão deixa de ser opinião e passa a ser diagnóstico.

Ferramentas como Datadog, New Relic, Grafana, Prometheus, Loki, Tempo, Jaeger e OpenTelemetry ajudam a construir essa visão. Algumas são mais completas e gerenciadas. Outras são mais flexíveis e exigem mais maturidade operacional. A escolha depende do contexto, mas o objetivo é o mesmo: transformar sinais dispersos em entendimento.

Observabilidade não é excesso de dashboard. Também não é coletar tudo para sempre. É saber quais sinais realmente ajudam a operar melhor o sistema.

Isso vale para backend, frontend, filas, infraestrutura e jornadas de negócio.

Em aplicações frontend, ferramentas como Sentry, LogRocket, Datadog RUM e New Relic Browser ajudam a enxergar erros JavaScript, lentidão em telas, falhas por navegador, problemas de dispositivo e impacto real na experiência do usuário. Isso é importante porque nem todo problema de produção está no servidor.

Às vezes, a API está saudável, mas a interface quebrou uma jornada crítica.

Sem observabilidade, a empresa enxerga apenas parte da realidade.

E meia realidade pode levar a decisões erradas.

O quarto pilar é CI/CD.

Se testes criam confiança, processos assíncronos aumentam resiliência e observabilidade gera entendimento, CI/CD transforma entrega em processo. Sem ele, toda essa base perde força no momento em que o código precisa chegar em produção.

Existe um sinal muito claro de baixa maturidade: deploy com medo.

Quando cada publicação exige tensão, checklist manual, acompanhamento excessivo e esperança, o problema raramente está apenas no código. O problema está no processo de entrega.

No início, publicar software manualmente parece aceitável. O time é pequeno, o sistema é simples e todos sabem o que precisa ser feito. Mas conforme o negócio cresce, a entrega manual passa a se tornar um risco.

Mais desenvolvedores contribuem. Mais serviços precisam ser publicados. Mais variáveis precisam ser configuradas. Mais clientes são impactados. Mais integrações dependem do sistema funcionando corretamente.

Nesse contexto, cada deploy manual aumenta a chance de erro.

CI/CD significa integração contínua e entrega contínua ou implantação contínua. Mais importante do que a sigla é o conceito: toda alteração deve seguir um caminho confiável de validação, build, testes, publicação e acompanhamento.

Ferramentas como GitHub Actions, Azure DevOps, Bitbucket Pipelines, GitLab CI e Jenkins ajudam a estruturar esse fluxo. GitHub Actions é produtivo para quem já usa GitHub. Azure DevOps é forte em ambientes corporativos e ecossistema Microsoft. Bitbucket Pipelines funciona bem para times que utilizam Bitbucket. GitLab CI é completo dentro do ecossistema GitLab. Jenkins é flexível, mas exige mais operação.

A ferramenta importa, mas não é o ponto principal.

Um pipeline ruim continua sendo ruim em qualquer plataforma.

O que define maturidade é o desenho do processo.

Um pipeline básico pode executar testes e build:

name: CI Pipeline
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Build application
        run: npm run build

Esse exemplo não resolve tudo, mas já cria um fluxo mínimo de validação. O código não depende apenas de alguém lembrar de rodar os comandos localmente. O processo passa a ser padronizado.

Em sistemas mais maduros, o pipeline pode incluir análise de segurança, validação de dependências, build de imagem Docker, publicação em registry, deploy em homologação, aprovação para produção, rollback, feature flags, canary release, blue-green deployment e validação pós-deploy.

O objetivo não é criar burocracia.

É reduzir risco.

CI/CD maduro não termina quando o código sobe. Ele precisa se conectar com observabilidade para confirmar se o sistema continua saudável depois da publicação. A taxa de erro aumentou? A latência piorou? O checkout falhou? A fila começou a acumular? A nova versão afetou uma jornada crítica?

Deploy bem-sucedido não é apenas aplicação no ar.

Deploy bem-sucedido é sistema se comportando como esperado.

Quando esses quatro pilares trabalham juntos, o comportamento do sistema muda.

Testes automatizados reduzem medo de mudança. Processos assíncronos reduzem propagação de falhas. Observabilidade reduz trabalho no escuro. CI/CD reduz improviso na entrega.

Nenhum desses pilares funciona sozinho em sua melhor forma.

Testes sem CI/CD dependem de alguém lembrar de executá-los. CI/CD sem testes apenas automatiza risco. Processos assíncronos sem observabilidade podem transformar filas em caixas pretas. Observabilidade sem boas práticas de arquitetura apenas mostra com clareza um sistema que continua difícil de operar.

O valor está na combinação.

Essa combinação cria uma base onde o sistema pode evoluir com mais segurança. O time consegue alterar código com menos medo. A aplicação consegue absorver falhas sem derrubar tudo. A operação consegue entender problemas com mais rapidez. A entrega consegue seguir um caminho previsível até produção.

Isso não elimina complexidade.

Mas organiza a complexidade.

E sistemas que escalam não são sistemas sem complexidade. São sistemas onde a complexidade foi tratada com responsabilidade.

Essa responsabilidade aparece em decisões que muitas vezes não são visíveis para o usuário final. O cliente não vê os testes rodando. Não vê a fila processando eventos. Não vê os traces conectando serviços. Não vê o pipeline validando build. Não vê o rollback disponível. Não vê o alerta antes do incidente.

Mas ele sente o resultado.

Sente quando o sistema é estável. Sente quando a experiência é consistente. Sente quando problemas são resolvidos rápido. Sente quando novas funcionalidades chegam sem quebrar o que já funcionava. Sente quando a plataforma responde bem mesmo em momentos de pressão.

Engenharia boa nem sempre aparece.

Mas a ausência dela aparece muito.

Aparece em deploy com medo. Aparece em bug recorrente. Aparece em sistema lento sem explicação. Aparece em fila travada que ninguém viu. Aparece em integração que falha silenciosamente. Aparece em funcionalidade que quebra outra. Aparece em time que evita mexer no próprio código. Aparece em cliente que perde confiança.

Por isso, esses quatro pilares não devem ser tratados como luxo técnico.

Eles são parte da seriedade de uma empresa que depende de software para operar.

Uma empresa que cresce sem testes está acumulando risco de mudança. Uma empresa que cresce sem processos assíncronos está acumulando dependência. Uma empresa que cresce sem observabilidade está acumulando cegueira operacional. Uma empresa que cresce sem CI/CD está acumulando risco de entrega.

No começo, tudo isso parece administrável.

Depois, vira custo.

E quando vira custo, geralmente já está afetando o produto, o time e o negócio.

Existe uma frase que resume bem essa lógica: sistemas não quebram apenas porque cresceram. Eles quebram porque cresceram sobre uma base que não estava preparada.

Essa base precisa ser construída com intenção.

Não precisa começar perfeita. Nenhum sistema começa maduro em todos os pontos. Mas precisa começar em algum lugar. Um conjunto mínimo de testes. Uma fila para separar tarefas críticas. Um painel para enxergar fluxos importantes. Um pipeline para padronizar validações. Um processo simples de rollback. Uma métrica de negócio acompanhada em produção.

Maturidade técnica não nasce pronta.

Ela é construída por camadas.

O problema é quando a empresa adia todas essas camadas até o momento em que não consegue mais evoluir sem sofrimento. Quando isso acontece, cada melhoria passa a competir com urgências, incidentes, retrabalho e pressão de negócio.

É sempre mais caro organizar depois.

Não apenas em dinheiro, mas em energia, confiança e tempo.

E tempo é uma das coisas mais caras em empresas que estão crescendo.

Porque enquanto o time está apagando incêndio, o produto deixa de evoluir. Enquanto o time está investigando problema sem contexto, o cliente está sentindo o impacto. Enquanto o deploy exige tensão, a inovação desacelera. Enquanto o sistema depende de esforço manual, a empresa perde previsibilidade.

No fim, escala não é apenas uma questão de infraestrutura.

Escala é uma questão de maturidade.

Infraestrutura pode sustentar volume. Mas maturidade sustenta evolução.

E evolução é o que mantém um produto vivo.

Empresas que levam software a sério precisam olhar para esses pilares não como uma lista técnica, mas como parte da estratégia de crescimento. O sistema não é apenas um apoio ao negócio. Em muitos casos, ele é o próprio negócio. Ele vende, atende, processa, integra, calcula, comunica, valida, registra e entrega valor.

Se esse sistema não consegue mudar com segurança, o negócio desacelera.

Se não consegue absorver falhas, o negócio fica vulnerável.

Se não consegue ser observado, o negócio opera no escuro.

Se não consegue ser entregue com previsibilidade, o negócio passa a temer evolução.

Essa é a razão pela qual engenharia de software não pode ser vista apenas como execução. Engenharia é capacidade de sustentar crescimento com responsabilidade.

E responsabilidade, nesse contexto, significa construir sistemas que não dependem de sorte para continuar funcionando.

Sorte não é processo. Esperança não é estratégia. Esforço manual não é escala.

Um sistema sério precisa ser capaz de responder a perguntas simples.

Se eu alterar essa regra, o que garante que não quebrei outra? Se essa integração falhar, o que acontece com o fluxo principal? Se o usuário reclamar de lentidão, consigo entender onde está o problema? Se esse deploy falhar, consigo voltar com segurança? Se o volume dobrar, o sistema absorve ou colapsa? Se o time crescer, o processo continua previsível?

Essas perguntas dizem muito sobre a maturidade de uma empresa.

E a resposta raramente está em uma única ferramenta.

Está na arquitetura. Está no processo. Está na cultura. Está na disciplina de tratar software como algo vivo, crítico e em constante evolução.

No fim, sistemas que escalam de verdade não são aqueles que nunca falham. São aqueles que foram preparados para mudar, falhar parcialmente, se recuperar, ser compreendidos e continuar evoluindo.

Essa é a diferença entre crescimento e escala.

Crescimento pode acontecer por tração de mercado, esforço comercial ou aumento de demanda.

Escala exige engenharia.

A pergunta que fica é simples: sua empresa está construindo uma base real para escalar ou apenas empilhando complexidade até o próximo incidente? 🚀

Quando a entrega depende de validação manual, cuidado excessivo e sorte, o deploy deixa de ser processo e passa a ser risco operacional.

Existe um momento bastante claro na evolução de um sistema em que o deploy deixa de ser apenas uma etapa natural do desenvolvimento e passa a ser tratado como um evento. Esse momento nem sempre aparece em um relatório técnico, mas fica evidente no comportamento do time.

Antes, publicar uma nova versão era simples. O desenvolvedor terminava uma funcionalidade, fazia uma validação manual, subia o código e acompanhava se tudo continuava funcionando. Em sistemas pequenos, esse modelo parece suficiente. Poucas pessoas mexem no código, as regras são mais fáceis de entender, as integrações são limitadas e o impacto de uma falha geralmente pode ser corrigido rapidamente.

Durante um tempo, isso funciona.

O problema é que sistemas não permanecem pequenos quando o negócio começa a crescer. Mais desenvolvedores passam a contribuir. Mais funcionalidades entram no produto. Mais serviços se comunicam entre si. Mais clientes dependem da aplicação funcionando corretamente. Mais integrações externas entram no fluxo. O que antes era um processo simples começa a se tornar um ponto de tensão.

Nesse momento, o deploy muda de natureza.

Ele deixa de ser rotina e passa a ser risco.

Esse risco aparece de várias formas. O time evita publicar em determinados horários. Deploy em sexta-feira se torna assunto proibido. Cada nova versão exige uma reunião de alinhamento. Alguém precisa acompanhar logs manualmente. Outro precisa validar telas. Alguém fica responsável por testar uma funcionalidade específica. Se algo falha, a equipe precisa correr para entender o que aconteceu e, muitas vezes, desfazer a alteração às pressas.

Esse comportamento é um sintoma.

Ele mostra que a empresa não possui um processo confiável de entrega.

Quando uma empresa depende de cuidado manual para publicar software, ela está operando em um modelo frágil. Não importa se o time é bom, experiente ou cuidadoso. Em algum momento, a complexidade supera a capacidade humana de lembrar todos os detalhes, validar todos os caminhos e prever todos os impactos.

É aqui que CI/CD deixa de ser apenas uma prática técnica e passa a ser uma estrutura fundamental para crescimento.

CI/CD significa Continuous Integration e Continuous Delivery ou Continuous Deployment. Em português, costuma ser traduzido como integração contínua e entrega contínua ou implantação contínua. Mas mais importante do que a tradução é entender o conceito.

CI/CD é a criação de um fluxo confiável para que cada alteração no código seja validada, construída, testada e entregue de forma consistente.

Isso muda completamente a lógica da entrega.

Sem CI/CD, cada deploy depende de pessoas executando etapas manualmente. Com CI/CD, cada alteração passa por um caminho padronizado. O código é versionado, o pipeline é acionado, as validações são executadas, os testes rodam, o build é gerado e a entrega segue critérios definidos.

O objetivo não é apenas publicar mais rápido.

O objetivo é publicar com previsibilidade.

Essa distinção é importante porque muitas empresas confundem CI/CD com velocidade. Elas imaginam que o principal benefício é entregar mais vezes por dia ou reduzir o tempo de publicação. Embora isso possa acontecer, esse não é o ponto central.

O verdadeiro valor está em reduzir incerteza.

Em um sistema que cresce, incerteza é cara. Ela aparece no medo de alterar código, no receio de publicar uma nova versão, no aumento de validações manuais, no retrabalho depois de incidentes e na perda de confiança entre negócio e tecnologia.

Quando o pipeline é bem construído, a empresa cria uma espécie de trilho para a entrega. Cada mudança passa por etapas conhecidas. Cada validação ocorre da mesma forma. Cada falha interrompe o processo antes que o problema chegue em produção.

Esse é o ponto onde CI/CD se conecta diretamente com testes automatizados.

Um pipeline sem testes relevantes é apenas uma esteira levando código para produção. Ele pode até automatizar a entrega, mas não necessariamente reduz risco. Se a aplicação não possui validações automatizadas, o pipeline não tem como saber se uma regra importante foi quebrada.

Por isso, CI/CD e testes não deveriam ser tratados como temas separados.

Testes dão segurança para validar o comportamento do sistema. CI/CD garante que essa validação aconteça sempre, de forma consistente, antes da entrega.

Imagine uma aplicação Node.js simples. Sem pipeline, alguém precisa lembrar de instalar dependências, rodar testes, gerar build e publicar. Com pipeline, esse fluxo pode ser automatizado.

Um exemplo básico com GitHub Actions poderia ser assim:

name: CI Pipeline
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Build application
        run: npm run build

Esse pipeline ainda é simples, mas já resolve um problema importante: nenhuma alteração passa sem executar uma sequência mínima de validações. O repositório é baixado, a versão do Node.js é configurada, as dependências são instaladas, os testes são executados e o build é gerado.

Esse tipo de automação reduz a dependência de validação manual.

Mas CI/CD não termina aqui.

Em sistemas reais, o pipeline precisa evoluir conforme a maturidade da aplicação cresce. Pode incluir análise estática de código, validação de padrões, verificação de segurança, testes de integração, geração de artefatos, publicação de imagens Docker, deploy em ambiente de homologação, aprovação manual para produção, rollback e validação pós-deploy.

O ponto não é criar um pipeline complexo por vaidade técnica. O ponto é construir um fluxo que reflita o risco real do sistema.

Uma aplicação interna simples talvez precise de um pipeline mais direto. Um sistema financeiro, de saúde, e-commerce ou plataforma crítica provavelmente precisa de validações mais rigorosas. O nível de controle precisa acompanhar o impacto da falha.

Essa é uma diferença importante entre automatizar e amadurecer.

Automatizar é fazer uma máquina executar uma sequência de comandos. Amadurecer é desenhar uma sequência de validações que protege o negócio.

Ferramentas como GitHub Actions, Azure DevOps, Bitbucket Pipelines, GitLab CI e Jenkins existem para ajudar nessa construção. Todas elas permitem criar pipelines, executar tarefas, integrar com repositórios, rodar testes e publicar aplicações. Mas cada uma tem características diferentes.

GitHub Actions costuma ser muito produtivo para times que já utilizam GitHub. Ele se integra diretamente ao repositório, possui uma grande comunidade de actions prontas e permite configurar fluxos de forma relativamente simples. É uma ótima escolha para startups, produtos digitais, projetos open source e times que desejam velocidade sem muita complexidade inicial.

Azure DevOps costuma aparecer com força em ambientes corporativos, especialmente onde existe uso intenso de ecossistema Microsoft, .NET, Azure, boards, releases e governança mais centralizada. Ele oferece uma estrutura mais ampla, integrando repositório, pipeline, backlog, artefatos e controle de entrega.

Bitbucket Pipelines é uma opção prática para times que utilizam Bitbucket. Ele é direto, integrado ao repositório e costuma atender bem projetos que precisam de um fluxo mais enxuto, sem uma estrutura operacional muito pesada.

GitLab CI é bastante completo, principalmente para empresas que utilizam GitLab como plataforma central. Ele permite integrar repositório, issues, merge requests, pipelines, registry e deploy em um único ambiente.

Jenkins é uma ferramenta mais tradicional e extremamente flexível. Por outro lado, exige mais manutenção, configuração e cuidado operacional. Em ambientes onde já existe uma base consolidada, pode fazer sentido. Em times que querem reduzir esforço de operação, soluções mais gerenciadas podem ser mais interessantes.

A escolha da ferramenta importa, mas não é o ponto principal.

Um pipeline ruim no Azure DevOps continua sendo ruim. Um pipeline ruim no GitHub Actions continua sendo ruim. Um pipeline ruim no Jenkins continua sendo ruim.

A maturidade não está no nome da ferramenta.

Está no desenho do processo.

E um bom processo começa com uma pergunta simples: o que precisa ser verdade para que esse código possa chegar em produção com segurança?

Essa pergunta muda a forma como o pipeline é pensado.

Se a aplicação depende de testes unitários, eles precisam rodar. Se existem testes de integração, eles precisam ser considerados. Se há risco de vulnerabilidades em dependências, uma checagem de segurança pode fazer sentido. Se o sistema é containerizado, a imagem precisa ser construída de forma padronizada. Se o deploy ocorre em Kubernetes, os manifests ou charts precisam ser validados. Se existem variáveis sensíveis, secrets precisam ser tratados corretamente.

Cada etapa deve existir por um motivo.

Um pipeline cheio de etapas sem propósito gera lentidão e ruído. Um pipeline simples demais para um sistema crítico gera risco. O equilíbrio está em criar validações suficientes para proteger a entrega sem transformar o processo em burocracia inútil.

Esse equilíbrio é o que separa engenharia madura de ritual técnico.

Em muitos times, o primeiro grande ganho de CI/CD é eliminar o famoso “na minha máquina funciona”. Quando o build roda em um ambiente padronizado, com versões definidas e comandos consistentes, a subjetividade diminui. O código deixa de depender da configuração local de cada desenvolvedor e passa a ser validado em um ambiente reproduzível.

Isso parece básico, mas é extremamente importante.

Um sistema que depende da máquina de uma pessoa para ser publicado não possui processo. Possui dependência individual.

Essa dependência é perigosa. Se apenas uma pessoa sabe publicar, essa pessoa vira gargalo. Se apenas uma máquina tem a configuração correta, essa máquina vira risco. Se o deploy depende de passos manuais não documentados, a empresa está apostando que ninguém vai esquecer nada.

E esquecer acontece.

Principalmente sob pressão.

CI/CD reduz esse tipo de fragilidade porque transforma conhecimento operacional em processo executável. Aquilo que antes estava na cabeça de alguém passa a estar descrito no pipeline.

Isso não significa remover responsabilidade humana. Significa reduzir erro humano em etapas repetitivas e críticas.

Um pipeline mais completo poderia incluir build de imagem Docker:

name: Build and Push Docker Image
on:
  push:
    branches:
      - main
jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Login to container registry
        run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.example.com -u "${{ secrets.REGISTRY_USER }}" --password-stdin
      - name: Build image
        run: docker build -t registry.example.com/my-app:${{ github.sha }} .
      - name: Push image
        run: docker push registry.example.com/my-app:${{ github.sha }}

Nesse exemplo, cada versão da aplicação pode ser empacotada em uma imagem identificada pelo hash do commit. Isso cria rastreabilidade. Se uma versão apresentou problema, fica mais fácil saber exatamente qual código foi publicado.

Rastreabilidade é um dos aspectos mais importantes de uma entrega madura.

Quando algo falha em produção, a empresa precisa saber o que mudou. Qual commit entrou? Qual versão foi publicada? Qual pipeline executou? Quais testes passaram? Quem aprovou? Em qual ambiente a falha apareceu?

Sem rastreabilidade, incidentes viram investigação manual.

Com rastreabilidade, a análise começa com evidência.

Esse ponto conecta CI/CD diretamente com observabilidade. O pipeline entrega a mudança, mas a observabilidade mostra como essa mudança se comporta em produção. Um bom processo de engenharia não termina quando o deploy é concluído. Ele continua depois da publicação.

É por isso que validação pós-deploy é importante.

Muitas empresas tratam deploy como sucesso no momento em que a aplicação sobe. Mas subir não significa funcionar corretamente. Um serviço pode estar no ar e ainda assim falhar em fluxos críticos. Uma API pode retornar status 200 em health check e mesmo assim quebrar uma jornada importante. Um frontend pode carregar e ainda assim impedir o usuário de concluir uma ação.

Deploy bem-sucedido não é apenas infraestrutura ativa.

Deploy bem-sucedido é sistema se comportando como esperado.

Uma abordagem mais madura inclui acompanhar métricas depois da publicação. Taxa de erro aumentou? Latência piorou? Fila começou a acumular? Checkout caiu? Login ficou lento? Algum serviço passou a consumir mais CPU ou memória? O número de exceções aumentou?

Essas perguntas deveriam fazer parte da cultura de entrega.

Sem isso, o deploy é visto como fim do processo, quando na verdade ele é apenas o começo da validação em ambiente real.

Outro ponto essencial é rollback.

Todo sistema sério precisa considerar a possibilidade de falha. Não porque o time seja ruim, mas porque produção é um ambiente vivo. Usuários se comportam de formas inesperadas, integrações oscilam, dados reais expõem cenários não previstos e mudanças simples podem gerar efeitos colaterais.

A questão não é se um deploy algum dia vai falhar.

A questão é quanto tempo sua empresa leva para se recuperar quando isso acontece.

Rollback é a capacidade de voltar rapidamente para uma versão anterior quando algo dá errado. Em alguns ambientes, isso pode ser feito revertendo uma imagem Docker. Em outros, pode envolver troca de versão em Kubernetes, estratégias blue-green, canary releases ou feature flags.

Cada abordagem tem sua função.

Blue-green deployment trabalha com dois ambientes. Um está ativo, o outro recebe a nova versão. Depois da validação, o tráfego é direcionado para a nova versão. Se algo der errado, é possível voltar para o ambiente anterior com mais rapidez.

Canary release libera a nova versão para uma pequena porcentagem de usuários antes de expandir para todos. Isso reduz impacto, porque problemas podem ser detectados em uma amostra menor.

Feature flags permitem ativar ou desativar funcionalidades sem necessariamente fazer um novo deploy. Elas são muito úteis para reduzir risco em lançamentos, testar comportamentos e controlar exposição de funcionalidades.

Essas estratégias mostram que CI/CD não é apenas “subir código”.

É controlar risco.

Uma empresa que publica tudo de uma vez para todos os usuários assume um tipo de risco. Uma empresa que libera gradualmente, mede impacto e tem plano de retorno assume outro nível de maturidade.

Isso não significa que todo projeto precisa começar com blue-green, canary e feature flags. Mais uma vez, contexto importa. Mas empresas que crescem precisam entender que deploy não é apenas uma ação técnica. É uma decisão operacional.

E decisões operacionais precisam de processo.

Um dos erros comuns em empresas em crescimento é acreditar que CI/CD só deve ser implementado quando o sistema já estiver grande. Essa visão inverte a lógica. Quanto mais tarde o pipeline entra, mais difícil fica padronizar o processo.

Quando a aplicação já possui múltiplos serviços, várias formas de deploy, diferentes padrões de configuração e pouca documentação, criar CI/CD se torna mais trabalhoso. O pipeline passa a precisar organizar uma bagunça já existente.

O ideal é que a cultura de entrega comece cedo, ainda que simples.

Um pipeline inicial pode rodar testes e build. Depois pode publicar em homologação. Depois pode adicionar análise de segurança. Depois pode automatizar deploy. Depois pode incluir rollback, validação pós-deploy e estratégias progressivas.

A maturidade cresce por camadas.

O erro é não começar.

Também existe um impacto direto no time. Quando o deploy depende de etapas manuais, as pessoas ficam mais tensas. O medo de quebrar produção aumenta. Novos desenvolvedores demoram mais para ganhar autonomia. Pessoas específicas viram guardiãs do processo. O conhecimento fica concentrado.

Com CI/CD, a entrega se torna mais democrática e previsível.

Isso não significa que qualquer pessoa deve publicar qualquer coisa sem responsabilidade. Significa que o processo passa a proteger a entrega, independentemente de quem fez a alteração.

Essa mudança melhora a cultura do time.

O desenvolvedor passa a receber feedback mais rápido. Se um teste falha, ele descobre antes. Se o build quebra, ele descobre antes. Se uma dependência apresenta vulnerabilidade, ele descobre antes. Se a aplicação não empacota corretamente, ele descobre antes.

Feedback rápido reduz custo.

Quanto mais cedo um problema é identificado, mais barato ele é para corrigir. Um erro encontrado no pipeline é mais barato do que um erro encontrado em produção. Um build quebrado em pull request é mais barato do que um deploy emergencial. Uma falha detectada antes da publicação é mais barata do que uma falha percebida pelo cliente.

Esse é um dos motivos pelos quais CI/CD tem impacto direto no negócio.

Não se trata apenas de produtividade técnica. Trata-se de reduzir retrabalho, aumentar previsibilidade, diminuir incidentes, acelerar resposta ao mercado e aumentar confiança no produto.

Quando o negócio sabe que a engenharia consegue entregar com segurança, a relação muda.

As áreas deixam de tratar tecnologia como gargalo e passam a enxergar tecnologia como capacidade de execução.

Mas isso só acontece quando existe consistência.

Entrega irregular gera desconfiança. Deploys problemáticos geram medo. Incidentes repetidos geram resistência a mudanças. E quando o negócio começa a ter medo de mudança, a empresa perde velocidade estratégica.

Nesse sentido, CI/CD é mais do que uma prática de engenharia.

É uma ferramenta de confiança organizacional.

Outro aspecto importante é segurança.

Pipelines modernos podem incluir validações de segurança em diferentes etapas. Isso pode envolver análise de dependências vulneráveis, verificação de secrets expostos, análise estática de código, validação de imagens Docker e políticas de infraestrutura.

Ferramentas como Snyk, Dependabot, SonarQube, Trivy, Checkov e OWASP Dependency-Check podem ser integradas ao fluxo. O objetivo não é transformar o pipeline em uma barreira insuportável, mas identificar riscos antes que cheguem em produção.

Segurança não deveria ser uma etapa manual no fim do projeto.

Ela precisa fazer parte do fluxo.

Esse conceito se aproxima de DevSecOps: segurança integrada ao desenvolvimento e à operação. Quando bem aplicada, a segurança deixa de ser um bloqueio tardio e passa a ser uma validação contínua.

Isso é especialmente importante em ambientes regulados, sistemas financeiros, plataformas com dados sensíveis, health techs, marketplaces e produtos que lidam com informações críticas de usuários.

Um exemplo simples de verificação de dependências poderia ser integrado assim:

name: Security Check
on:
  pull_request:
    branches:
      - main
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Run npm audit
        run: npm audit --audit-level=high

Esse exemplo é básico, mas mostra o princípio: problemas conhecidos podem ser identificados antes que a alteração entre na branch principal.

Em pipelines mais maduros, esse tipo de validação pode ser combinado com análise de imagem Docker, varredura de infraestrutura como código e políticas de aprovação.

Mais uma vez, o objetivo não é criar burocracia. É reduzir risco.

Existe uma diferença enorme entre um processo seguro e um processo pesado. Um bom pipeline protege sem paralisar. Um pipeline ruim gera lentidão, desvio e frustração. A maturidade está em calibrar o nível de controle ao risco real do sistema.

Também é importante falar sobre ambientes.

Muitas empresas possuem apenas desenvolvimento e produção. Isso pode funcionar em projetos muito pequenos, mas se torna arriscado conforme o sistema cresce. Ambientes como staging, homologação ou preview environments ajudam a validar mudanças antes da publicação final.

Em aplicações modernas, especialmente com GitHub Actions, Vercel, Netlify, Kubernetes ou plataformas cloud, é comum criar ambientes temporários para cada pull request. Isso permite que o time visualize a mudança funcionando antes de aprovar.

Esse tipo de prática reduz ruído.

Produto consegue validar. QA consegue testar. Desenvolvedores conseguem revisar comportamento. O negócio consegue enxergar a entrega antes que ela chegue ao usuário final.

Mas é preciso tomar cuidado para não transformar ambientes em uma fonte de inconsistência. Se homologação é muito diferente de produção, ela perde valor. Se staging não usa configurações parecidas, os testes podem enganar. Se dados são irreais demais, cenários importantes podem não aparecer.

Ambientes precisam ser suficientemente parecidos para gerar confiança.

Esse é outro ponto onde CI/CD ajuda, porque infraestrutura, variáveis, versões e deploys podem ser padronizados.

Quando a empresa trabalha com containers, por exemplo, a mesma imagem pode ser promovida entre ambientes. Isso reduz o risco de “funcionou em homologação, mas quebrou em produção” por diferença de build.

Essa ideia de promover artefatos é importante.

Em vez de reconstruir a aplicação várias vezes, o pipeline gera um artefato versionado e promove esse artefato entre ambientes. O que foi testado é o que será publicado. Isso aumenta rastreabilidade e reduz variação.

CI/CD bem feito cria esse tipo de consistência.

Sem isso, cada ambiente vira uma interpretação diferente do sistema.

E interpretação diferente gera surpresa.

A surpresa pode até ser interessante em produto, mas em deploy geralmente é problema.

Outro cuidado importante é com segredos e variáveis de ambiente. Um pipeline não pode expor senhas, tokens, chaves privadas ou credenciais sensíveis. Secrets precisam ser armazenados em locais apropriados, com controle de acesso, rotação e uso restrito.

Esse é um ponto onde muitos processos falham.

Às vezes, a empresa automatiza deploy, mas deixa credenciais expostas em arquivos, logs ou variáveis mal protegidas. Isso transforma o pipeline em risco de segurança.

CI/CD precisa ser confiável também do ponto de vista de proteção de dados e acesso.

O ideal é que cada ambiente tenha seus próprios secrets, que permissões sejam mínimas e que o pipeline execute apenas o que precisa executar. Contas de serviço devem seguir o princípio do menor privilégio. Logs do pipeline não devem exibir informações sensíveis. Aprovações devem existir quando o risco justificar.

Maturidade de pipeline também envolve governança.

Em ambientes mais controlados, pode fazer sentido exigir revisão em pull requests, bloquear merge se testes falharem, exigir aprovação para produção, registrar quem aprovou e manter histórico de deploys. Isso não precisa ser burocrático. Pode ser parte natural do fluxo.

O importante é que a empresa saiba responder perguntas básicas.

O que foi publicado? Quando foi publicado? Quem aprovou? Quais validações passaram? Qual versão está em produção? Como voltar se der errado?

Se a empresa não consegue responder isso rapidamente, ela ainda não possui controle real sobre a entrega.

Existe também uma relação direta entre CI/CD e arquitetura. Sistemas monolíticos podem ter pipelines eficientes. Microserviços podem ter pipelines ruins. A arquitetura por si só não garante maturidade de entrega.

Em um monólito bem organizado, o pipeline pode rodar testes, gerar build, publicar uma versão e manter rastreabilidade. Em microserviços desorganizados, cada serviço pode ter um processo diferente, dependências mal definidas e deploys difíceis de coordenar.

O problema não é monólito ou microserviço.

O problema é falta de padrão.

Quando a empresa começa a ter muitos serviços, padronizar pipelines se torna ainda mais importante. Caso contrário, cada time cria sua própria forma de publicar, validar e operar. Isso gera inconsistência e dificulta governança.

Uma boa prática é criar templates reutilizáveis de pipeline. Assim, serviços diferentes seguem uma base comum, mas ainda podem adaptar detalhes conforme sua necessidade.

Isso reduz manutenção e melhora previsibilidade.

Também ajuda novos desenvolvedores, porque eles não precisam aprender um processo completamente diferente para cada projeto.

Em empresas que escalam, padronização não é inimiga da flexibilidade. Pelo contrário. Ela cria uma base comum para que a flexibilidade aconteça com menos risco.

No fim, CI/CD é a disciplina de transformar entrega em processo.

E essa disciplina muda a forma como a empresa evolui.

Sem CI/CD, cada deploy depende de uma combinação de cuidado, memória, disponibilidade de pessoas e sorte. Com CI/CD, a entrega passa a depender de um fluxo validado, repetível e rastreável.

Isso não elimina todos os problemas. Nenhum processo elimina. Mas reduz drasticamente a chance de falhas previsíveis chegarem em produção.

Também reduz medo.

E medo é um dos maiores inimigos da evolução de sistemas.

Quando o time tem medo de publicar, a empresa desacelera. Quando a empresa desacelera, o produto perde capacidade de resposta. Quando o produto perde capacidade de resposta, o negócio perde competitividade.

Por isso, deploy não deveria ser um evento traumático.

Deveria ser uma consequência natural de um processo confiável.

Se cada deploy exige tensão, reunião emergencial, validação manual excessiva e esperança, talvez o problema não esteja apenas no código. Talvez esteja na ausência de uma estrutura real de entrega.

Empresas que querem escalar precisam entender isso cedo.

Não basta escrever código. Não basta ter bons desenvolvedores. Não basta ter cloud, Kubernetes, microserviços ou ferramentas modernas. Se a entrega continua manual, imprevisível e frágil, o sistema ainda carrega um risco estrutural.

CI/CD não é luxo. Não é detalhe. Não é apenas coisa de empresa grande.

É uma das primeiras evidências de que a engenharia está sendo tratada com seriedade.

Porque software que cresce sem processo de entrega não escala de forma saudável.

Ele apenas aumenta a distância entre mudança e controle.

E quanto maior essa distância, maior o risco.

A pergunta que fica é simples: seu deploy é um processo confiável ou ainda é um momento de tensão disfarçado de rotina? 🚀

Isolated logs may show that something failed, but only observability allows you to understand the real behavior of a system in production.

There is an important difference between knowing that a system failed and understanding why it failed. This difference may seem small when the application is simple, but it becomes massive as the system grows, gains new integrations, processes more data, and starts depending on multiple services working at the same time.

In a small system, the relationship between cause and effect is usually direct. An error appears on a screen, the developer opens the log, finds the exception, understands the problem, and fixes it. This flow is simple because the path traveled by the request is also simple. The user performs an action, the backend processes it, the database responds, and the result returns to the interface.

For a while, this works.

The problem is that real systems rarely remain simple when the business starts to grow. New features are added, external integrations enter the flow, asynchronous routines start running in the background, queues begin processing events, different databases are queried, and multiple services start communicating with each other.

At that point, the system stops being a straight line.

It becomes a network.

And when a network starts having problems, looking at only one isolated point is not enough to understand the whole.

This is one of the reasons why many companies believe they have control over their systems when, in reality, they only have scattered records of events. There is a log. There may be a CPU and memory dashboard. There may even be an error alert. But there is no context. There is no correlation. There is no clear way to understand the complete path of an operation.

This is where observability comes in.

Observability is not just having logs. It is not just having metrics either. And it is not simply installing a nice-looking tool with modern dashboards. Observability is the ability to understand the internal behavior of a system based on the signals it emits in production.

This definition matters because it changes the focus of the discussion.

The goal is not only to know that something went wrong. The goal is to understand what is happening, where it is happening, why it is happening, and what impact it has on the rest of the system.

This difference is fundamental for companies that are scaling.

Imagine an order system. The user completes a purchase, the backend creates the order, validates stock, processes payment, publishes an event to a queue, sends an email, updates reports, and notifies an external integration. This flow may involve an API, database, cache, queue, worker, payment service, email service, and third-party integration.

If something fails, where is the problem?

It could be in the main endpoint. It could be in the database. It could be in the queue. It could be in the worker. It could be in the external API. It could be intermittent slowness. It could be a business rule that started consuming more time after a change. It could be a service that works well for most of the day but fails under load.

Without observability, the team tries to figure this out manually.

They open logs from one service. Then another. They compare timestamps. They search for error messages. They try to reproduce the behavior. They add new logs. They deploy again. They wait for it to happen again. And while all of this is happening, the system continues impacting users or accumulating failures in the background.

This is one of the invisible costs of lacking observability: the time lost trying to understand the problem.

And time in production is expensive.

Not only because of the technical team’s cost, but because of the impact on the customer, the operation, and the business’s trust. A poorly understood incident tends to take longer to resolve. An intermittent problem without traceability tends to reappear. A failure without context tends to generate superficial fixes.

Knowing that there was an error is very different from understanding the behavior that led to that error.

Consider a simple example in Node.js:

app.get('/checkout/:id', async (req, res) => {
  const order = await getOrder(req.params.id);
  const customer = await getCustomer(order.customerId);
  const payment = await getPaymentStatus(order.paymentId);
  const shipping = await calculateShipping(order.address);
  res.json({
    order,
    customer,
    payment,
    shipping
  });
});

This code looks simple. It fetches an order, loads customer data, checks the payment status, calculates shipping, and returns a response. In a small application, this might work without major issues.

But in production, each one of these functions may hide a different dependency. getOrder may query a database under heavy load. getCustomer may call another internal service. getPaymentStatus may depend on an external API. calculateShipping may use a logistics service that becomes slow at certain times of the day.

If this endpoint starts taking five seconds to respond, what is the cause?

A traditional log may only say that the request took too long. In some cases, it may register a timeout. But that does not answer the main question. Is the problem in the database? In the customer service? In the payment gateway? In the shipping calculation? In all of them at the same time? Or in none of them individually, but in the sum of their latencies?

Without context, the team guesses.

With observability, the team investigates.

That difference completely changes the operation.

Observability usually relies on three major signals: metrics, logs, and traces. Each one has a different role, and the real value appears when they are analyzed together.

Metrics help understand the general state of the system over time. They show quantitative behavior: average response time, error rate, CPU usage, memory usage, number of messages in a queue, throughput, requests per minute, latency by endpoint, among other indicators. Metrics are useful for identifying trends and noticing when something has moved away from the expected pattern.

Logs record specific events. They show messages, errors, exceptions, contextual data, and useful information for punctual analysis. A good log helps explain what happened at a given moment, as long as it is well structured and contains relevant information.

Traces show the path traveled by a request or operation across different parts of the system. In distributed architectures, this is one of the most important elements because it allows the team to follow the complete journey of a call.

A trace may look like this:

Client
  → API Gateway: 45ms
    → Auth Service: 30ms
    → Order Service: 120ms
      → Database: 80ms
      → Payment Service: 2,400ms
        → External Provider: 2,200ms
    → Response: 2,610ms

In this example, it becomes clear that the bottleneck is not in the gateway, not in the order service, and not in the database. Most of the time is being spent in the payment service and, more specifically, in the external provider. This visibility completely changes how the team reacts to the problem.

Without a trace, someone might try to optimize the main endpoint. Someone might increase infrastructure. Someone might add cache where it is not needed. Someone might investigate the database unnecessarily. With a trace, the discussion stops being based on opinion and starts being based on evidence.

That is operational maturity.

Tools such as Datadog, Grafana, and New Relic offer this type of visibility in an integrated way, combining APM, logs, metrics, traces, alerts, and dashboards in a single platform. They are often good options for companies that need to accelerate observability adoption without building the entire infrastructure from scratch.

Grafana, Prometheus, Loki, Tempo, and Jaeger follow a more flexible and composable approach. Prometheus is widely used for metrics collection. Grafana is strong in visualization. Loki helps with logs. Jaeger and Tempo are used for distributed tracing. This approach usually offers more control, but also requires more technical maturity to configure, maintain, and evolve.

OpenTelemetry is becoming increasingly important in this scenario. It is not exactly a final visualization tool, but an open standard for instrumenting applications and collecting signals such as traces, metrics, and logs. The main advantage is reducing vendor lock-in and allowing the company to send data to different platforms.

In practical terms, instrumenting an application means making it emit useful signals about its own behavior.

A simplified example with OpenTelemetry in Node.js could look like this:

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('checkout-service');
async function processCheckout(orderId) {
  return await tracer.startActiveSpan('processCheckout', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      const order = await getOrder(orderId);
      const payment = await processPayment(order);
      const shipping = await calculateShipping(order);
      span.setAttribute('payment.status', payment.status);
      return {
        order,
        payment,
        shipping
      };
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: 2, message: error.message });
      throw error;
    } finally {
      span.end();
    }
  });
}

This type of instrumentation helps transform a common operation into something observable. The system starts emitting information about what it is doing, how long it is taking, which attributes matter, and which errors occurred.

This does not replace good logs or good metrics. But it creates a layer of context that isolated logs cannot provide.

And context is what separates observability from simple monitoring.

Traditional monitoring usually answers known questions. Did CPU go above 80%? Is memory usage high? Did the endpoint return a 500 error? Is the server down? These questions are important, but limited. They assume that you already know what you need to observe.

Observability allows you to investigate questions you did not yet know you would need to ask.

Why is checkout slow only for some users? Why does the queue grow only at a specific time? Why does the integration fail only when order volume is high? Why did response time increase after an apparently simple change? Why is an asynchronous routine delayed without generating an explicit error?

These questions are common in real systems.

And they are hard to answer with scattered logs alone.

Observability transforms scattered signals into context so the team can understand the real behavior of the system in production.

The lack of observability also creates a cultural problem. When the team does not have clear data, technical discussions start depending on perceptions. One developer thinks the problem is in the database. Another believes it is in the external API. Someone suggests increasing server capacity. Someone else argues for refactoring the service. Without evidence, the conversation becomes a dispute of opinions.

In mature environments, data reduces noise.

Observability does not eliminate the need for technical experience, but it directs that experience. A good engineer remains essential to interpret signals, raise hypotheses, and make decisions. The difference is that they are no longer working in the dark.

This is especially true for asynchronous processes.

When an operation is sent to a queue, it leaves the main flow. This improves resilience, but also increases the need for visibility. If a message gets stuck, fails, is retried, or takes longer than expected, someone needs to know.

Without observability, the system may look healthy at the interface while accumulating problems in the background.

The user receives a positive response, but the email was not sent. The order was created, but the external integration was not notified. The transaction was recorded, but the report was not updated. The queue is growing, but no one notices until the delay becomes an incident.

This is one of the most dangerous risks of poorly monitored modern architectures: silent failure.

It does not explode immediately. It accumulates.

Not every failure appears to the user immediately. Some accumulate silently until they become an incident.

Observability should also not be confused with excessive information. There is a big difference between collecting a lot of data and collecting useful data. A system can generate thousands of logs per minute and still be difficult to understand. It can have dozens of dashboards and none of them answer the important questions. It can have alerts for everything and, precisely because of that, make the team ignore alerts.

This is known as alert fatigue.

When everything alerts, nothing alerts.

A good observability system needs to be designed with intention. Metrics must reflect relevant behavior. Logs need structure and context. Traces must follow critical flows. Alerts must indicate situations that require real action.

Alerting because CPU went up for a few seconds may not make sense. Alerting because the checkout error rate increased, because the payment queue is accumulating, or because login latency passed an acceptable threshold can be much more relevant.

The question should not be only “what can we measure?”. The question should be “what do we need to understand in order to operate the system better?”.

This change in question is essential.

In many systems, four signals are a good starting point: latency, traffic, errors, and saturation. Latency shows how long operations take. Traffic shows how much the system is being used. Errors show explicit failures. Saturation shows how close resources are to their limits.

These signals do not solve everything, but they offer an important base for understanding system health.

In backend applications, this may mean tracking response time by endpoint, error rate by service, slow database queries, connection usage, CPU and memory consumption, queue size, and average worker processing time.

In frontend applications, observability also matters. Many companies forget that the user experience starts in the browser or in the application. Metrics such as loading time, JavaScript errors, API failures, device-specific performance, Core Web Vitals, and real user behavior help understand problems that the backend alone may never see.

Tools such as Sentry, LogRocket, Datadog RUM, New Relic Browser, and OpenTelemetry for frontend can help at this point. They allow teams to identify interface errors, slowness in specific screens, and real impacts on the user experience.

This matters because not every production problem lives on the server.

Sometimes the API is healthy, but the frontend broke a critical journey. Sometimes the backend responds quickly, but the user suffers because of a heavy screen. Sometimes the error happens only in a specific browser, operating system, or app version.

Without observability in the frontend, the company sees only part of reality.

And half a reality can lead to wrong decisions.

The user experience depends on both ends: what happens in the interface and what happens in the infrastructure behind it.

Another important point is the relationship between observability and business. Systems do not exist just to return status 200. They exist to support real processes. Sales, payments, registrations, customer service, proposals, queries, integrations, reports, internal operations.

For that reason, good observability should not look only at infrastructure. It should also look at critical journeys.

How many checkouts failed? How many orders remained pending? How many proposals were not processed? How many integrations were delayed? How many users could not complete registration? Which step of the funnel has the highest error rate?

These questions connect engineering to business.

And when engineering can demonstrate impact clearly, the conversation changes level.

The team stops talking only about CPU, memory, and 500 errors. It starts talking about conversion, operational stability, avoided loss, recovery time, reliability, and user experience.

This is one of the great strengths of observability: it brings technology and business closer together.

In companies that are scaling, this is decisive. The larger the system, the harder it becomes to make decisions based only on perception. It is necessary to understand where the bottlenecks are, which failures have the greatest impact, which services need priority, and which problems truly affect the user.

Without observability, everything seems urgent.

With observability, it becomes easier to prioritize.

This also affects how incidents are handled. In immature companies, incidents are usually chaotic. Many people join a call, each one looks at a different part, hypotheses appear one after another, and decisions are made under pressure.

In more mature companies, observability does not eliminate pressure, but it reduces disorder. The team can quickly identify the scope of the problem, understand which users were impacted, locate the responsible service, and follow the recovery.

After the incident, the data also helps with the postmortem analysis. Not to look for blame, but to understand behavior, identify process failures, and improve the system.

This is another important difference.

Observability should not be used as a tool to monitor people. It should be used as a tool to learn about systems.

The focus is not “who caused the problem?”. The focus is “why did the system allow this problem to have this impact?”.

This mindset changes engineering culture.

It takes the team out of defensive mode and puts the company in a posture of continuous improvement.

It is also important to recognize that observability has a cost. Collecting, storing, and processing data can become expensive, especially in high-volume systems. Managed tools offer a lot of convenience, but they need to be configured carefully to avoid unnecessary costs. Self-managed stacks offer control, but require operation.

That is why observability also needs strategy.

It is not about recording everything forever. It is about defining what matters, how long to keep it, what level of detail makes sense, and which signals truly help decision-making.

Debug logs in production without control can generate cost and noise. Tracing 100% of requests may be unnecessary in some scenarios. Metrics without standardization can make analysis difficult. The balance is collecting enough information to understand the system without turning observability into a problem of its own.

This maturity comes with time.

The important thing is to start with what sustains the operation.

Critical flows first. Most important services first. Journeys that impact users and revenue first. Then coverage evolves.

In a company that depends on checkout, observe checkout. In a company that depends on onboarding, observe onboarding. In a company that depends on integrations, observe integrations. In a company that depends on asynchronous processing, observe queues and workers.

It sounds obvious, but many companies start with what is easy to measure, not with what is important to understand.

This inversion reduces the value of observability.

In the end, observability is a form of responsibility. It means recognizing that putting a system into production without the ability to understand its behavior is accepting an unnecessary risk. It means accepting that, in real environments, failures will happen, integrations will fluctuate, users will find unexpected paths, and changes will generate side effects.

The question is not whether something will fail.

The question is how long your company will take to notice, understand, and fix it.

Serious systems do not depend only on hope. They emit signals. They are monitored. They allow investigation. They provide context for decisions.

Without that, every stage of growth increases the distance between what the company thinks is happening and what is actually happening.

And that distance is dangerous.

Because a system can look healthy from the outside while accumulating problems inside. It can respond to part of the requests and fail in critical flows. It can have active servers and still deliver a poor experience. It can record logs and still offer no understanding.

Observability exists to reduce that distance.

It does not solve every problem, but it allows teams to see problems clearly. It does not prevent every failure, but it reduces reaction time. It does not replace architecture, tests, or good deployment processes, but it strengthens all of these pillars.

Without observability, tests say whether something should work. CI/CD delivers changes consistently. Asynchronous processes distribute responsibilities. But when all of this reaches production, one essential question remains: is the system actually behaving as expected?

If you cannot answer that, you are not controlling the system.

You are only hoping it is working.

And hope is not a scaling strategy.

The question that remains is simple: does your company understand the real behavior of the system in production, or does it still depend on isolated logs to discover what happened? 🔭

Logs isolados podem mostrar que algo falhou, mas somente observabilidade permite entender o comportamento real do sistema em produção.

Existe uma diferença importante entre saber que um sistema falhou e entender por que ele falhou. Essa diferença parece pequena quando a aplicação é simples, mas se torna enorme conforme o sistema cresce, ganha novas integrações, passa a processar mais dados e começa a depender de múltiplos serviços funcionando ao mesmo tempo.

Em um sistema pequeno, a relação entre causa e efeito costuma ser direta. Um erro aparece em uma tela, o desenvolvedor abre o log, encontra a exceção, entende o problema e corrige. Esse fluxo é simples porque o caminho percorrido pela requisição também é simples. O usuário faz uma ação, o backend processa, o banco responde e o resultado volta para a interface.

Durante um tempo, isso funciona.

O problema é que sistemas reais raramente permanecem simples quando o negócio começa a crescer. Novas funcionalidades são adicionadas, integrações externas entram no fluxo, rotinas assíncronas passam a ser executadas em segundo plano, filas começam a processar eventos, bancos diferentes passam a ser consultados e múltiplos serviços começam a conversar entre si.

Nesse momento, o sistema deixa de ser uma linha reta.

Ele passa a ser uma rede.

E quando uma rede começa a apresentar problemas, olhar apenas para um ponto isolado não é suficiente para entender o todo.

Essa é uma das razões pelas quais muitas empresas acreditam que têm controle sobre seus sistemas, quando na verdade têm apenas registros soltos de eventos. Existe log. Existe algum painel de CPU e memória. Existe talvez um alerta de erro. Mas falta contexto. Falta correlação. Falta uma forma clara de entender o caminho completo de uma operação.

É aqui que entra a observabilidade.

Observabilidade não é apenas ter logs. Também não é apenas ter métricas. E não é simplesmente instalar uma ferramenta bonita com dashboards modernos. Observabilidade é a capacidade de compreender o comportamento interno de um sistema a partir dos sinais que ele emite em produção.

Essa definição é importante porque muda o foco da discussão.

O objetivo não é apenas saber que algo deu errado. O objetivo é entender o que está acontecendo, onde está acontecendo, por que está acontecendo e qual impacto isso gera no restante do sistema.

Essa diferença é fundamental para empresas que estão escalando.

Imagine um sistema de pedidos. O usuário finaliza uma compra, o backend cria o pedido, valida estoque, processa pagamento, publica um evento em uma fila, envia e-mail, atualiza relatórios e notifica uma integração externa. Esse fluxo pode envolver API, banco de dados, cache, fila, worker, serviço de pagamento, serviço de e-mail e integração de terceiros.

Se algo falhar, onde está o problema?

Pode estar no endpoint principal. Pode estar no banco. Pode estar na fila. Pode estar no worker. Pode estar na API externa. Pode estar em uma lentidão intermitente. Pode estar em uma regra de negócio que passou a consumir mais tempo depois de uma alteração. Pode estar em um serviço que funciona bem na maior parte do dia, mas falha sob carga.

Sem observabilidade, o time tenta descobrir isso manualmente.

Abre logs de um serviço. Depois de outro. Compara horários. Procura mensagens de erro. Tenta reproduzir o comportamento. Adiciona novos logs. Faz um novo deploy. Espera acontecer de novo. E, enquanto isso, o sistema continua impactando usuários ou acumulando falhas em segundo plano.

Esse é um dos custos invisíveis da falta de observabilidade: o tempo perdido para entender o problema.

E tempo, em produção, é caro.

Não apenas pelo custo da equipe técnica, mas pelo impacto no cliente, na operação e na confiança do negócio. Um incidente mal compreendido tende a demorar mais para ser resolvido. Um problema intermitente sem rastreabilidade tende a reaparecer. Uma falha sem contexto tende a gerar correções superficiais.

Saber que houve erro é muito diferente de entender o comportamento que levou até o erro.

Considere um exemplo simples em Node.js:

app.get('/checkout/:id', async (req, res) => {
  const order = await getOrder(req.params.id);
  const customer = await getCustomer(order.customerId);
  const payment = await getPaymentStatus(order.paymentId);
  const shipping = await calculateShipping(order.address);
  res.json({
    order,
    customer,
    payment,
    shipping
  });
});

Esse código parece simples. Ele busca um pedido, carrega dados do cliente, consulta o status do pagamento, calcula o frete e retorna uma resposta. Em uma aplicação pequena, talvez isso funcione sem grandes problemas.

Mas, em produção, cada uma dessas funções pode esconder uma dependência diferente. getOrder pode consultar um banco de dados com alta carga. getCustomer pode chamar outro serviço interno. getPaymentStatus pode depender de uma API externa. calculateShipping pode usar um serviço de logística que apresenta lentidão em determinados horários.

Se esse endpoint começar a demorar cinco segundos para responder, qual é a causa?

O log tradicional talvez diga apenas que a requisição demorou. Em alguns casos, pode registrar um timeout. Mas isso não responde à pergunta principal. O problema está no banco? No serviço de cliente? No gateway de pagamento? No cálculo de frete? Em todos ao mesmo tempo? Em nenhum deles isoladamente, mas na soma das latências?

Sem contexto, o time adivinha.

Com observabilidade, o time investiga.

Essa diferença muda completamente a operação.

A observabilidade normalmente se apoia em três grandes sinais: métricas, logs e traces. Cada um tem uma função diferente, e o valor real aparece quando eles são analisados em conjunto.

Métricas ajudam a entender o estado geral do sistema ao longo do tempo. Elas mostram comportamento quantitativo: tempo médio de resposta, taxa de erro, consumo de CPU, uso de memória, quantidade de mensagens em fila, throughput, número de requisições por minuto, latência por endpoint, entre outros indicadores. Métricas são úteis para identificar tendências e perceber quando algo saiu do padrão.

Logs registram eventos específicos. Eles mostram mensagens, erros, exceções, dados de contexto e informações úteis para análise pontual. Um bom log ajuda a explicar o que aconteceu em determinado momento, desde que esteja bem estruturado e contenha informações relevantes.

Traces mostram o caminho percorrido por uma requisição ou operação entre diferentes partes do sistema. Em arquiteturas distribuídas, esse é um dos elementos mais importantes, porque permite acompanhar a jornada completa de uma chamada.

Um trace pode mostrar algo como:

Client
  → API Gateway: 45ms
    → Auth Service: 30ms
    → Order Service: 120ms
      → Database: 80ms
      → Payment Service: 2.400ms
        → External Provider: 2.200ms
    → Response: 2.610ms

Nesse exemplo, fica claro que o gargalo não está no gateway, nem no serviço de pedidos, nem no banco. A maior parte do tempo está no serviço de pagamento e, mais especificamente, no provedor externo. Essa visibilidade muda completamente a forma como o time reage ao problema.

Sem trace, talvez alguém tentasse otimizar o endpoint principal. Talvez aumentasse infraestrutura. Talvez criasse cache onde não precisava. Talvez investigasse o banco sem necessidade. Com trace, a discussão deixa de ser baseada em opinião e passa a ser baseada em evidência.

Isso é maturidade operacional.

Ferramentas como Datadog, Grafana e New Relic oferecem essa visão de forma integrada, combinando APM, logs, métricas, traces, alertas e dashboards em uma única plataforma. Elas costumam ser boas opções para empresas que precisam acelerar a adoção de observabilidade sem montar toda a infraestrutura do zero.

Grafana, Prometheus, Loki, Tempo e Jaeger seguem uma linha mais flexível e componível. Prometheus é muito usado para coleta de métricas. Grafana é forte em visualização. Loki ajuda com logs. Jaeger e Tempo são usados para tracing distribuído. Essa abordagem costuma oferecer mais controle, mas também exige mais maturidade técnica para configurar, manter e evoluir.

OpenTelemetry entra como um ponto cada vez mais importante nesse cenário. Ele não é exatamente uma ferramenta final de visualização, mas um padrão aberto para instrumentar aplicações e coletar sinais como traces, métricas e logs. A grande vantagem é reduzir dependência de fornecedor e permitir que a empresa envie dados para diferentes plataformas.

Em termos práticos, instrumentar uma aplicação significa fazer com que ela emita sinais úteis sobre o próprio comportamento.

Um exemplo simplificado com OpenTelemetry em Node.js poderia seguir uma linha como esta:

const { trace } = require('@opentelemetry/api');

const tracer = trace.getTracer('checkout-service');
async function processCheckout(orderId) {
  return await tracer.startActiveSpan('processCheckout', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      const order = await getOrder(orderId);
      const payment = await processPayment(order);
      const shipping = await calculateShipping(order);
      span.setAttribute('payment.status', payment.status);
      return {
        order,
        payment,
        shipping
      };
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: 2, message: error.message });
      throw error;
    } finally {
      span.end();
    }
  });
}

Esse tipo de instrumentação ajuda a transformar uma operação comum em algo observável. O sistema passa a emitir informações sobre o que está fazendo, quanto tempo está levando, quais atributos são importantes e quais erros ocorreram.

Isso não substitui bons logs, nem boas métricas. Mas cria uma camada de contexto que logs isolados não conseguem oferecer.

E contexto é o que separa observabilidade de simples monitoramento.

Monitoramento tradicional geralmente responde a perguntas conhecidas. A CPU passou de 80%? A memória está alta? O endpoint retornou erro 500? O servidor está fora do ar? Essas perguntas são importantes, mas são limitadas. Elas partem do princípio de que você já sabe o que precisa observar.

Observabilidade permite investigar perguntas que você ainda não sabia que precisaria fazer.

Por que o checkout está lento apenas para alguns usuários? Por que a fila cresce somente em determinado horário? Por que a integração falha apenas quando há alto volume de pedidos? Por que o tempo de resposta aumentou depois de uma alteração aparentemente simples? Por que uma rotina assíncrona está atrasando sem gerar erro explícito?

Essas perguntas são comuns em sistemas reais.

E são difíceis de responder apenas com logs soltos.

A falta de observabilidade também cria um problema cultural. Quando o time não possui dados claros, as discussões técnicas passam a depender de percepções. Um desenvolvedor acha que o problema está no banco. Outro acredita que está na API externa. Alguém sugere aumentar servidor. Outro defende refatorar o serviço. Sem evidência, a conversa vira disputa de opinião.

Em ambientes maduros, dados reduzem ruído.

A observabilidade não elimina a necessidade de experiência técnica, mas direciona essa experiência. Um bom engenheiro continua sendo fundamental para interpretar os sinais, levantar hipóteses e tomar decisões. A diferença é que ele deixa de trabalhar no escuro.

Isso vale especialmente para processos assíncronos.

Quando uma operação é enviada para uma fila, ela sai do fluxo principal. Isso melhora a resiliência, mas também aumenta a necessidade de visibilidade. Se uma mensagem fica parada, falha, é reprocessada ou demora mais do que deveria, alguém precisa saber.

Sem observabilidade, o sistema pode parecer saudável na interface enquanto acumula problemas em segundo plano.

O usuário recebe uma resposta positiva, mas o e-mail não foi enviado. O pedido foi criado, mas a integração externa não foi notificada. A transação foi registrada, mas o relatório não foi atualizado. A fila está crescendo, mas ninguém percebe até que o atraso vire incidente.

Esse é um dos riscos mais perigosos de arquiteturas modernas mal acompanhadas: a falha silenciosa.

Ela não explode imediatamente. Ela se acumula.

Observabilidade também não deve ser confundida com excesso de informação. Existe uma diferença grande entre coletar muitos dados e coletar dados úteis. Um sistema pode gerar milhares de logs por minuto e ainda assim ser difícil de entender. Pode ter dezenas de dashboards e nenhum deles responder às perguntas importantes. Pode ter alertas para tudo e, justamente por isso, fazer com que o time ignore alertas.

Esse é o fenômeno conhecido como fadiga de alerta.

Quando tudo alerta, nada alerta.

Um bom sistema de observabilidade precisa ser desenhado com intenção. Métricas precisam refletir comportamento relevante. Logs precisam ter estrutura e contexto. Traces precisam acompanhar fluxos críticos. Alertas precisam indicar situações que exigem ação real.

Alertar porque a CPU subiu por alguns segundos talvez não faça sentido. Alertar porque a taxa de erro do checkout aumentou, porque a fila de pagamentos está acumulando ou porque a latência do login passou de um limite aceitável pode ser muito mais relevante.

A pergunta não deve ser apenas “o que podemos medir?”. A pergunta deve ser “o que precisamos entender para operar melhor o sistema?”.

Essa mudança de pergunta é essencial.

Em muitos sistemas, existem quatro sinais que ajudam bastante a começar: latência, tráfego, erros e saturação. Latência mostra quanto tempo as operações levam. Tráfego mostra quanto o sistema está sendo utilizado. Erros mostram falhas explícitas. Saturação mostra o quanto os recursos estão próximos do limite.

Esses sinais não resolvem tudo, mas oferecem uma base importante para entender a saúde do sistema.

Em aplicações backend, isso pode significar acompanhar tempo de resposta por endpoint, taxa de erro por serviço, consultas lentas no banco, uso de conexões, consumo de CPU e memória, tamanho de filas e tempo médio de processamento de workers.

Em aplicações frontend, observabilidade também importa. Muitas empresas esquecem que a experiência do usuário começa no navegador ou no aplicativo. Métricas como tempo de carregamento, erros JavaScript, falhas de API, performance por dispositivo, Core Web Vitals e comportamento real do usuário ajudam a entender problemas que o backend talvez nunca enxergue sozinho.

Ferramentas como Sentry, LogRocket, Datadog RUM, New Relic Browser e OpenTelemetry para frontend podem ajudar nesse ponto. Elas permitem identificar erros na interface, lentidão em telas específicas e impactos reais na experiência do usuário.

Isso é importante porque nem todo problema de produção está no servidor.

Às vezes, a API está saudável, mas o frontend quebrou uma jornada crítica. Às vezes, o backend responde rápido, mas o usuário sofre com uma tela pesada. Às vezes, o erro acontece apenas em um navegador, sistema operacional ou versão específica do aplicativo.

Sem observabilidade no frontend, a empresa enxerga apenas parte da realidade.

E meia realidade pode levar a decisões erradas.

Outro ponto importante é a relação entre observabilidade e negócio. Sistemas não existem apenas para retornar status 200. Eles existem para suportar processos reais. Vendas, pagamentos, cadastros, atendimentos, propostas, consultas, integrações, relatórios, operações internas.

Por isso, uma boa observabilidade não deve olhar apenas para infraestrutura. Deve olhar também para jornadas críticas.

Quantos checkouts falharam? Quantos pedidos ficaram pendentes? Quantas propostas não foram processadas? Quantas integrações atrasaram? Quantos usuários não conseguiram concluir o cadastro? Qual etapa do funil apresenta mais erro?

Essas perguntas conectam engenharia ao negócio.

E quando engenharia consegue demonstrar impacto com clareza, a conversa muda de nível.

O time deixa de falar apenas em CPU, memória e erro 500. Passa a falar em conversão, estabilidade operacional, perda evitada, tempo de recuperação, confiabilidade e experiência do usuário.

Essa é uma das grandes forças da observabilidade: ela aproxima tecnologia e negócio.

Em empresas que estão escalando, isso é decisivo. Quanto maior o sistema, mais difícil fica tomar decisões apenas com base em percepção. É preciso entender onde estão os gargalos, quais falhas têm maior impacto, quais serviços precisam de prioridade e quais problemas realmente afetam o usuário.

Sem observabilidade, tudo parece urgente.

Com observabilidade, fica mais fácil priorizar.

Isso também afeta a forma como incidentes são tratados. Em empresas pouco maduras, incidentes geralmente são caóticos. Muitas pessoas entram em uma chamada, cada uma olha uma parte, hipóteses surgem em sequência e decisões são tomadas sob pressão.

Em empresas mais maduras, a observabilidade não elimina a pressão, mas reduz a desordem. O time consegue identificar rapidamente o escopo do problema, entender quais usuários foram impactados, localizar o serviço responsável e acompanhar a recuperação.

Além disso, depois do incidente, os dados ajudam na análise pós-mortem. Não para buscar culpados, mas para entender comportamento, identificar falhas de processo e melhorar o sistema.

Essa é outra diferença importante.

Observabilidade não deve ser usada como ferramenta de vigilância sobre pessoas. Ela deve ser usada como ferramenta de aprendizado sobre sistemas.

O foco não é “quem causou o problema?”. O foco é “por que o sistema permitiu que esse problema tivesse esse impacto?”.

Essa mentalidade muda a cultura de engenharia.

Ela tira o time do modo defensivo e coloca a empresa em uma postura de melhoria contínua.

Também é importante reconhecer que observabilidade tem custo. Coletar, armazenar e processar dados pode ficar caro, especialmente em sistemas com grande volume. Ferramentas gerenciadas oferecem muita facilidade, mas precisam ser configuradas com critério para evitar custos desnecessários. Stacks próprias oferecem controle, mas exigem operação.

Por isso, observabilidade também precisa de estratégia.

Não se trata de registrar tudo para sempre. Trata-se de definir o que é importante, por quanto tempo manter, qual nível de detalhe faz sentido e quais sinais realmente ajudam na tomada de decisão.

Logs de debug em produção sem controle podem gerar custo e ruído. Traces em 100% das requisições podem ser desnecessários em alguns cenários. Métricas sem padronização podem dificultar análise. O equilíbrio está em coletar informação suficiente para entender o sistema sem transformar observabilidade em um problema próprio.

Essa maturidade vem com o tempo.

O importante é começar pelo que sustenta a operação.

Fluxos críticos primeiro. Serviços mais importantes primeiro. Jornadas que impactam usuário e receita primeiro. Depois, a cobertura evolui.

Em uma empresa que depende de checkout, observe checkout. Em uma empresa que depende de onboarding, observe onboarding. Em uma empresa que depende de integrações, observe integrações. Em uma empresa que depende de processamento assíncrono, observe filas e workers.

Parece óbvio, mas muitas empresas começam pelo que é fácil medir, não pelo que é importante entender.

Essa inversão reduz o valor da observabilidade.

No fim, observabilidade é uma forma de responsabilidade. É reconhecer que colocar um sistema em produção sem capacidade de entender seu comportamento é assumir um risco desnecessário. É aceitar que, em ambientes reais, falhas vão acontecer, integrações vão oscilar, usuários vão encontrar caminhos inesperados e mudanças vão gerar efeitos colaterais.

A questão não é se algo vai falhar.

A questão é quanto tempo sua empresa vai levar para perceber, entender e corrigir.

Sistemas sérios não dependem apenas de esperança. Eles emitem sinais. Eles são acompanhados. Eles permitem investigação. Eles oferecem contexto para decisão.

Sem isso, qualquer crescimento aumenta a distância entre o que a empresa acha que está acontecendo e o que realmente está acontecendo.

E essa distância é perigosa.

Porque um sistema pode parecer saudável por fora e estar acumulando problemas por dentro. Pode responder parte das requisições e falhar em fluxos críticos. Pode ter servidores ativos e ainda assim entregar uma experiência ruim. Pode registrar logs e, mesmo assim, não oferecer entendimento.

Observabilidade existe para reduzir essa distância.

Ela não resolve todos os problemas, mas permite enxergá-los com clareza. Não impede todas as falhas, mas reduz o tempo de reação. Não substitui arquitetura, testes ou bons processos de deploy, mas fortalece todos esses pilares.

Sem observabilidade, testes dizem se algo deveria funcionar. CI/CD entrega mudanças com consistência. Processos assíncronos distribuem responsabilidades. Mas, quando tudo isso chega em produção, ainda resta uma pergunta essencial: o sistema está realmente se comportando como deveria?

Se você não consegue responder, você não controla o sistema.

Você apenas espera que ele esteja funcionando.

E esperança não é estratégia de escala.

A pergunta que fica é simples: sua empresa entende o comportamento real do sistema em produção ou ainda depende de logs soltos para descobrir o que aconteceu? 🔭

When every operation depends on another one finishing immediately, the system may still work, but it starts growing with a silent fragility.

There is a very common idea in software development that growing systems fail because they are not fast enough. At first glance, this explanation seems to make sense. If more users are accessing the application, the system needs to respond faster. If more data is being processed, the infrastructure needs to support more load. If more integrations are added, the backend needs to handle more operations.

This interpretation is not entirely wrong, but it is incomplete.

In many cases, the real problem is not speed. It is dependency.

A system can be fast and still be fragile. It can respond well under normal conditions and still collapse when one part of the flow becomes slow. It can have good infrastructure and still suffer because too many things need to happen at the same time, inside the same request, within the same chain of responsibility.

This is one of the most important differences between systems that simply grow and systems that are truly prepared to scale.

At the beginning of a project, synchronous communication is usually the natural choice. A request reaches the backend, the application processes it, talks to the database, perhaps calls an external service, and returns a response. This model is easy to understand, easy to debug, and easy to implement.

Frameworks such as Express in Node.js, ASP.NET in .NET, Django in Python, Laravel in PHP, Spring Boot in Java, or Ruby on Rails make this flow extremely productive. A developer can create endpoints, implement rules, connect to the database, and deliver value quickly.

In a small application, this works very well. The flow is clear. The number of dependencies is limited. The response time is predictable. And if something fails, it is usually possible to identify the problem with relative ease.

The problem is that systems do not remain simple when the business starts to grow.

New rules appear. New screens are created. New integrations enter the flow. Processes that were once small begin to involve different parts of the application. A registration is no longer just a registration. It starts validating data, consulting external services, generating notifications, updating indicators, sending emails, recording logs, creating history records, recalculating balances, or triggering other routines.

At first, all of this is usually placed inside the same flow.

The user clicks a button. The backend receives the request. The system executes all the steps. Only then does it return a response.

It seems organized. It seems direct. It seems efficient.

Until the moment it no longer is.

Imagine, for example, an order system. When a customer completes a purchase, the backend needs to create the order, validate stock, calculate shipping, process payment, issue an invoice, send an email, update the admin dashboard, and notify external integrations.

In a fully synchronous model, all of these steps may end up happening inside the same operation. The flow might look something like this:

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await issueInvoice(order);
  await sendConfirmationEmail(order);
  await notifyExternalMarketplace(order);
  res.json({
    success: true,
    orderId: order.id
  });
});

This code is easy to understand. It looks clean, linear, and predictable. But there is a hidden problem in this simplicity: the success of the entire operation depends on every step working within the expected time.

If stock reservation takes too long, the user waits. If payment is slow, the user waits. If invoice generation fails, the entire order may be compromised. If the email service is down, an operation that should only depend on order creation may fail because of a secondary step. If the integration with an external marketplace is unstable, the checkout may be affected by something that should not block the main user experience.

This is the point where the system starts showing fragility.

Not because the code is necessarily wrong, but because different responsibilities were placed inside the same critical flow.

The question that needs to be asked is simple: does all of this really need to happen before responding to the user?

In many cases, the answer is no.

Creating the order may need to happen immediately. Payment validation may also be part of the critical flow. But sending emails, notifying external systems, updating reports, triggering integrations, or processing auxiliary routines can usually happen later.

This separation completely changes how the system behaves.

When everything happens synchronously, each step adds time and risk to the main operation. The more dependencies exist inside the flow, the greater the chance that something will fail. And when one step fails, the impact can spread across the entire process.

It is the domino effect applied to software architecture.

An external API becomes slow and the whole system starts responding poorly. A third-party service goes down and internal operations are blocked. A heavy routine consumes too many resources and affects users who had nothing to do with that process.

In moments like these, many companies try to solve the problem by increasing infrastructure. They add more servers, more memory, better databases, replicas, cache, or scale containers. All of this can help, but only up to a point.

If the main problem is coupling, more infrastructure only buys time.

It does not fix the structure.

An overly coupled system remains fragile even when running on larger machines. It may support more volume for a while, but it remains vulnerable to the same type of failure. When dependency is built into the design of the flow, the solution needs to go through architecture.

This is where asynchronous processes come in.

Asynchronous processing is the practice of separating what needs to happen immediately from what can happen at another moment, without blocking the system’s main response. Instead of executing every step inside the same request, the application records an event, sends a message to a queue, or publishes a notification so another process can handle that task later.

The concept is not new, but it has become essential in modern systems.

Tools such as RabbitMQ, Apache Kafka, AWS SQS, Google Pub/Sub, and Azure Service Bus exist precisely to support this kind of separation. Each one has different characteristics, but they all start from the same central idea: allowing parts of the system to communicate without depending on an immediate response.

RabbitMQ is widely used for traditional task queues. It works very well when you need to distribute work among consumers, process messages reliably, and manage specific queues. It is common in scenarios such as email sending, image processing, report generation, notifications, integrations, and internal routines.

Kafka has a different nature. It is stronger in scenarios involving high-volume events, data streaming, and distributed processing. Instead of thinking only in terms of a task queue, Kafka works very well when different consumers need to read events, process information in parallel, and keep event history for a period of time.

AWS SQS, Google Pub/Sub, and Azure Service Bus bring this logic into managed cloud environments. The advantage is reducing operational effort. Instead of directly managing servers, clusters, or tool maintenance, the company uses a service managed by the cloud provider.

The choice of tool depends on the context. The mistake is believing that the tool is the main point.

It is not.

The main point is the change in mindset.

Instead of asking “how do I make all of this faster?”, the question becomes “what really needs to happen now and what can happen later?”.

When asked properly, this question improves the system’s architecture.

Returning to the order example, the flow could be reorganized like this:

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await queue.publish('order.created', {
    orderId: order.id,
    customerId: order.customerId
  });
  res.json({
    success: true,
    orderId: order.id
  });
});

In this model, the main flow handles what is essential to respond to the user. After that, it publishes an event informing that an order was created. From this event, other processes can take responsibility for complementary tasks.

One worker can issue the invoice. Another can send the email. Another can update reports. Another can notify the marketplace. Each process now has a clearer and more independent responsibility.

A simple consumer example could look like this:

queue.consume('order.created', async (message) => {
  const { orderId } = message;
  const order = await getOrder(orderId);
  await sendConfirmationEmail(order);
  await notifyExternalMarketplace(order);
});

This code represents an important change. Email sending and external notification no longer block order creation. If the email service is unavailable, the order can still be created. If the marketplace is unstable, the message can be retried later. The system no longer depends on everything working at the same time.

This is the essence of resilience.

It does not mean ignoring failures. It means preventing a secondary failure from bringing down the main flow.

This separation also improves the user experience. Instead of waiting for every step to finish, the user receives a faster response about what truly matters at that moment. The rest of the processing happens in the background.

For the user, the feeling is speed.

For the system, the gain is stability.

There is a simple analogy that helps explain this to non-technical people. Imagine a restaurant. If the waiter had to take the order, cook the food, prepare the drink, wash the dishes, close the bill, and only then return to the table, the service would be slow and fragile. Any problem in one step would block the entire process.

A restaurant works better because responsibilities are separated. The waiter registers the order, the kitchen prepares it, the cashier handles payment, someone organizes delivery, and other people take care of cleaning. The customer does not need to wait for all internal restaurant routines to finish in order to know that the order was received.

Asynchronous systems follow a similar logic.

They do not eliminate work. They organize the work.

This organization is what allows scale.

When a system separates responsibilities, it gains the ability to absorb variation. If the email queue grows, you can increase consumers only for that queue. If invoice generation is slow, the rest of the system can continue working. If an external integration becomes unavailable, you can reprocess messages later without blocking the user.

This creates a more fault-tolerant architecture.

But it is important to say that asynchronous processes also bring new challenges.

The first one is eventual consistency. In a synchronous system, the tendency is to expect everything to be updated at the same time. In an asynchronous system, some information may take a few seconds or minutes to be processed. This needs to be understood by the business and reflected in the user experience.

For example, an order may be created immediately, but the invoice may be issued a few seconds later. A report may not reflect a transaction at the exact moment it occurred. An integration may be processed in the background.

This is not necessarily a problem. Many times, it is the correct architectural choice. But it needs to be communicated and handled properly.

The second challenge is idempotency.

In systems with queues, the same message may be processed more than once in certain scenarios. For that reason, consumers need to be prepared to handle repetition without generating unwanted side effects.

If a payment worker processes the same message twice, it cannot charge the customer twice. If an email worker receives the same message again, it may need to verify whether that email was already sent. If an external integration is retried, the system must ensure that duplicates will not be created.

This requires care.

A simple protection example would be:

queue.consume('invoice.issue', async (message) => {
  const { orderId } = message;const existingInvoice = await findInvoiceByOrderId(orderId);
  if (existingInvoice) {
    return;
  }
  await issueInvoice(orderId);
});

Here, before issuing an invoice, the system checks whether it already exists. This kind of validation prevents message reprocessing from creating business problems.

The third challenge is observability.

When the system stops being linear, understanding what is happening becomes harder. In a synchronous flow, you follow a request from beginning to end. In an asynchronous flow, the process can pass through queues, workers, retries, and different services.

Without observability, queues become black boxes.

You need to know how many messages are pending, how many failed, which ones are being retried, how long each task takes, and where the bottlenecks are. Otherwise, the system may look healthy at the interface while silently accumulating problems in the background.

This is why asynchronous processing and observability need to walk together.

RabbitMQ, Kafka, SQS, or Pub/Sub solve communication. But the company still needs to monitor behavior, failures, delays, and retries. Tools such as Datadog, New Relic, Grafana, Prometheus, and OpenTelemetry come in at this point to provide visibility into the flow.

Another important point is that asynchronous processing should not be used as an excuse for disorder. Putting everything into queues without criteria can create a system that is harder to understand than the original one. The decision needs to be guided by responsibility, criticality, and user impact.

Not everything needs to be asynchronous.

Operations that require an immediate response, critical validations, or decisions that must be confirmed at the moment of the request may remain synchronous. The mistake is placing inside the main flow what does not need to be there.

Good architecture is not architecture that uses queues everywhere. It is architecture that knows where queues make sense.

This discernment is what separates technical usage from architectural maturity.

In financial systems, for example, certain validations need to happen immediately. You cannot simply tell the user that a transaction was approved if the critical validation has not yet occurred. On the other hand, notifications, reconciliations, complementary audits, and report updates can be processed asynchronously.

In e-commerce systems, the order and payment may be part of the main flow, while emails, recommendations, CRM updates, and secondary integrations can go to queues.

In healthcare systems, the recording of critical information needs to be reliable at the moment of the operation, while notification routines, synchronization, or analytical processing can happen later.

In real estate, automotive, or marketplace platforms, integrations with external portals, data enrichment, report generation, and notifications often benefit greatly from an asynchronous approach.

The practical application changes according to the industry, but the principle remains the same.

Separate the essential from the complementary.

This separation improves performance, but that is not the only benefit. It may not even be the main one.

The greatest benefit is reducing the impact of failures.

When everything is coupled, a small failure can compromise an entire operation. When responsibilities are separated, the failure remains isolated. It can be monitored, retried, and corrected without bringing down the main flow.

This changes the system’s behavior under pressure.

And every growing system goes through moments of pressure.

Traffic spikes, external instability, increased processing, commercial campaigns, integrations going down, rule changes, user base growth. At some point, the system will be tested outside ideal conditions.

The question is whether it was built to absorb this or whether it depends on everything working perfectly all the time.

Systems that depend on perfection do not scale well.

They only work while the environment is favorable.

When a business begins to grow, the number of unpredictable situations increases. This is the moment when architecture needs to stop being merely functional and start being resilient.

Asynchronous processes are part of this transition.

They allow the system to continue operating even when some parts are slow, unavailable, or overloaded. They allow work to be distributed. They allow failures to be retried. They protect the user from steps that do not need to block the experience.

This kind of architecture shows that the company has understood something important: not everything has the same urgency.

And when everything is treated as urgent, the system loses its ability to prioritize.

Maturity is knowing the difference.

There is also a direct impact on the development team. When responsibilities are separated, the code tends to become more organized. Services start having clearer functions. Workers can be developed, scaled, and monitored independently. The team can evolve parts of the system without touching the entire main flow.

This makes maintenance easier.

It also makes team scaling easier.

When everything is inside the same flow, every change requires extra caution because the impact may be broad. When responsibilities are well separated, the scope of change becomes clearer. This reduces fear, improves predictability, and allows safer evolution.

There is also a direct connection with automated tests here. The better separated the responsibilities are, the easier it is to test each part. A worker that processes email sending can be tested independently. A queue consumer for payments can have its rules validated with specific tests. An event producer can be verified without requiring the entire system to run together.

In other words, asynchronous processing is not just infrastructure. It influences architecture, testing, observability, deployment, and operations.

This is why companies that want to scale cannot treat messaging as a technical detail. It changes how the system thinks, reacts, and evolves.

But there is an important caution: unnecessary complexity is also a problem.

Implementing Kafka in a system that only needed a simple queue can create more cost than value. Creating dozens of events without governance can turn the system into a maze. Using messaging without clear standards can generate duplicate messages, inconsistent consumers, and flows that are hard to trace.

The tool must serve the problem, not technical ego.

RabbitMQ can be excellent for many queue scenarios. SQS may be enough for AWS-based systems that need operational simplicity. Kafka may be the right choice when there is high event volume, retention needs, and multiple consumers processing data in different ways. Azure Service Bus may make sense in Microsoft-heavy corporate environments. Google Pub/Sub may be natural for architectures running on GCP.

There is no universal tool.

There is context.

And context is what defines good architecture.

In the end, asynchronous processes are not just a way to make the system faster. They are a way to make the system more prepared for reality.

And the reality is that APIs fail, databases become slow, external services go down, users access systems in spikes, rules change, and integrations behave unpredictably.

A serious system cannot depend on everything working perfectly at the same time.

It needs to be designed to keep operating even when parts of the environment fail.

That is the central point.

When every operation depends on another one finishing immediately, the system may look stable at a small scale. But that stability is fragile because it depends on a perfect sequence of events.

As the business grows, that perfect sequence becomes less and less likely.

That is why the question is not only whether your application is fast today. The question is whether it will remain reliable when volume increases, when an integration fails, when a queue grows, when a service becomes slow, or when an operation needs to be retried.

Systems that scale are not systems that never face failures. They are systems designed to limit the impact of those failures.

Asynchronous processes help exactly with that.

They do not eliminate complexity, but they organize complexity. They do not remove failures, but they reduce propagation. They do not make everything happen immediately, but they allow the system to prioritize what really matters.

And this prioritization is one of the foundations of scale.

Without it, the company continues stacking responsibilities into the same flow, until the system becomes slow, fragile, and difficult to evolve.

At that point, the problem is no longer just technical. It starts affecting operations, user experience, team predictability, and the company’s ability to grow without turning every new demand into a risk.

That is why asynchronous processes are not an architectural luxury. They are not reserved only for large companies. They are not merely a technical choice for people who enjoy messaging systems.

They are a practical response to a real problem: growing systems cannot depend on everything happening at the same time.

If your company still treats every process as synchronous, every integration as blocking, and every operation as immediate, maybe the system is still working.

But that does not mean it is ready to scale.

The question that remains is simple: does your system separate what needs to happen now from what can happen later, or is it still allowing growth to depend on everything working at the same time? 🔥

Quando cada operação depende de outra para terminar imediatamente, o sistema pode até continuar funcionando, mas começa a crescer com uma fragilidade silenciosa.

Existe uma ideia bastante comum no desenvolvimento de software de que sistemas em crescimento falham porque não são rápidos o suficiente. À primeira vista, essa explicação parece fazer sentido. Se mais usuários estão acessando a aplicação, o sistema precisa responder mais rápido. Se mais dados estão sendo processados, a infraestrutura precisa suportar mais carga. Se mais integrações são adicionadas, o backend precisa lidar com mais operações.

Essa leitura não está totalmente errada, mas é incompleta.

Em muitos casos, o problema real não é velocidade. É dependência.

Um sistema pode ser rápido e ainda assim ser frágil. Pode responder bem em condições normais e mesmo assim entrar em colapso quando uma parte do fluxo fica lenta. Pode ter boa infraestrutura e continuar sofrendo porque coisas demais precisam acontecer ao mesmo tempo, dentro da mesma requisição, na mesma cadeia de responsabilidade.

Essa é uma das diferenças mais importantes entre sistemas que apenas crescem e sistemas realmente preparados para escalar.

No início de um projeto, a comunicação síncrona costuma ser a escolha natural. Uma requisição chega ao backend, a aplicação processa, conversa com o banco de dados, talvez chame um serviço externo e retorna uma resposta. Esse modelo é simples de entender, simples de depurar e simples de implementar.

Frameworks como Express no Node.js, ASP.NET no .NET, Django no Python, Laravel no PHP, Spring Boot no Java ou Ruby on Rails tornam esse fluxo extremamente produtivo. Um desenvolvedor consegue criar endpoints, implementar regras, conectar ao banco de dados e entregar valor rapidamente.

Em uma aplicação pequena, isso funciona muito bem. O fluxo é claro. A quantidade de dependências é limitada. O tempo de resposta é previsível. E, se algo falha, geralmente é possível identificar o problema com relativa facilidade.

O problema é que sistemas não permanecem simples quando o negócio começa a crescer.

Novas regras surgem. Novas telas são criadas. Novas integrações entram no fluxo. Processos que antes eram pequenos passam a envolver diferentes partes da aplicação. Um cadastro deixa de ser apenas um cadastro. Ele passa a validar dados, consultar serviços externos, gerar notificações, atualizar indicadores, disparar e-mails, registrar logs, criar históricos, recalcular saldos ou acionar outras rotinas.

No começo, tudo isso costuma ser colocado dentro do mesmo fluxo.

O usuário clica em um botão. O backend recebe a requisição. O sistema executa todas as etapas. Só depois retorna uma resposta.

Parece organizado. Parece direto. Parece eficiente.

Até o momento em que deixa de ser.

Imagine, por exemplo, um sistema de pedidos. Quando o cliente finaliza uma compra, o backend precisa criar o pedido, validar estoque, calcular frete, consultar pagamento, emitir nota, enviar e-mail, atualizar painel administrativo e notificar integrações externas.

Em um modelo totalmente síncrono, todas essas etapas podem acabar acontecendo dentro da mesma operação. O fluxo talvez seja parecido com isso:

app.pojast('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await issueInvoice(order);
  await sendConfirmationEmail(order);
  await notifyExternalMarketplace(order);
  res.json({
    success: true,
    orderId: order.id
  });
});

Esse código é fácil de entender. Ele parece limpo, linear e previsível. Mas existe um problema escondido nessa simplicidade: o sucesso da operação inteira depende de todas as etapas funcionarem no tempo esperado.

Se a reserva de estoque demorar, o usuário espera. Se o pagamento estiver lento, o usuário espera. Se a emissão de nota falhar, talvez o pedido inteiro seja comprometido. Se o serviço de e-mail estiver fora do ar, uma operação que deveria depender apenas da criação do pedido pode falhar por causa de uma etapa secundária. Se a integração com um marketplace externo estiver instável, o checkout pode ser impactado por algo que nem deveria bloquear a experiência principal.

Esse é o ponto em que o sistema começa a mostrar fragilidade.

Não porque o código está necessariamente errado, mas porque responsabilidades diferentes foram colocadas dentro do mesmo fluxo crítico.

A pergunta que precisa ser feita é simples: tudo isso realmente precisa acontecer antes de responder ao usuário?

Em muitos casos, a resposta é não.

Criar o pedido talvez precise acontecer imediatamente. Validar pagamento talvez também faça parte do fluxo crítico. Mas enviar e-mail, notificar sistemas externos, atualizar relatórios, disparar integrações ou processar rotinas auxiliares normalmente podem acontecer depois.

Essa separação muda completamente a forma como o sistema se comporta.

Quando tudo acontece de forma síncrona, cada etapa adiciona tempo e risco à operação principal. Quanto mais dependências existem no fluxo, maior a chance de alguma coisa falhar. E quando uma etapa falha, o impacto pode se espalhar para todo o processo.

É o famoso efeito dominó aplicado à arquitetura de software.

Uma API externa fica lenta e o sistema inteiro começa a responder mal. Um serviço de terceiros fica fora do ar e operações internas são bloqueadas. Uma rotina pesada consome recursos demais e prejudica usuários que nem estavam relacionados àquele processo.

Nesses momentos, muitas empresas tentam resolver o problema aumentando infraestrutura. Colocam mais servidores, aumentam memória, melhoram banco de dados, criam réplicas, adicionam cache ou escalam containers. Tudo isso pode ajudar, mas apenas até certo ponto.

Se o problema principal é acoplamento, mais infraestrutura só compra tempo.

Ela não corrige a estrutura.

Um sistema acoplado demais continua frágil mesmo rodando em máquinas maiores. Ele pode até suportar mais volume por algum tempo, mas permanece vulnerável ao mesmo tipo de falha. Quando a dependência está no desenho do fluxo, a solução precisa passar pela arquitetura.

É aqui que entram os processos assíncronos.

Processamento assíncrono é a prática de separar o que precisa acontecer imediatamente daquilo que pode acontecer em outro momento, sem bloquear a resposta principal do sistema. Em vez de executar todas as etapas dentro da mesma requisição, a aplicação registra um evento, envia uma mensagem para uma fila ou publica uma notificação para que outro processo cuide daquela tarefa posteriormente.

O conceito não é novo, mas se tornou essencial em sistemas modernos.

Ferramentas como RabbitMQ, Apache Kafka, AWS SQS, Google Pub/Sub e Azure Service Bus existem justamente para ajudar nesse tipo de separação. Cada uma tem características diferentes, mas todas partem de uma ideia central: permitir que partes do sistema se comuniquem sem depender de uma resposta imediata.

RabbitMQ é muito utilizado para filas tradicionais de tarefas. Ele funciona muito bem quando você precisa distribuir trabalho entre consumidores, processar mensagens de forma confiável e controlar filas específicas. É comum em cenários como envio de e-mails, processamento de imagens, geração de relatórios, notificações, integrações e rotinas internas.

Kafka tem uma natureza diferente. Ele é mais forte em cenários de alto volume de eventos, streaming de dados e processamento distribuído. Em vez de pensar apenas em uma fila de tarefas, Kafka trabalha muito bem quando diferentes consumidores precisam ler eventos, processar informações em paralelo e manter histórico de eventos por um período.

AWS SQS, Google Pub/Sub e Azure Service Bus trazem essa lógica para ambientes cloud gerenciados. A vantagem é reduzir esforço operacional. Em vez de cuidar diretamente de servidores, clusters ou manutenção da ferramenta, a empresa usa um serviço gerenciado pelo provedor de nuvem.

A escolha da ferramenta depende do contexto. O erro está em achar que a ferramenta é o ponto principal.

Não é.

O ponto principal é a mudança de mentalidade.

Em vez de perguntar “como faço tudo isso mais rápido?”, a pergunta passa a ser “o que realmente precisa acontecer agora e o que pode acontecer depois?”.

Essa pergunta, quando bem feita, melhora a arquitetura do sistema.

Voltando ao exemplo do pedido, o fluxo poderia ser reorganizado assim:

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);
  await reserveStock(order);
  await processPayment(order);
  await queue.publish('order.created', {
    orderId: order.id,
    customerId: order.customerId
  });
  res.json({
    success: true,
    orderId: order.id
  });
});

Nesse modelo, o fluxo principal cuida do que é essencial para responder ao usuário. Depois disso, publica um evento informando que um pedido foi criado. A partir desse evento, outros processos podem assumir tarefas complementares.

Um worker pode emitir a nota. Outro pode enviar e-mail. Outro pode atualizar relatórios. Outro pode notificar o marketplace. Cada processo passa a ter uma responsabilidade mais clara e independente.

Um exemplo simples de consumidor poderia ser:

queue.consume('order.created', async (message) => {
  const { orderId } = message;const order = await getOrder(orderId);
  await sendConfirmationEmail(order);
  await notifyExternalMarketplace(order);
});

Esse código representa uma mudança importante. O envio de e-mail e a notificação externa deixam de bloquear a criação do pedido. Se o serviço de e-mail estiver fora do ar, o pedido ainda pode ser criado. Se o marketplace estiver instável, a mensagem pode ser reprocessada depois. O sistema deixa de depender de tudo funcionando ao mesmo tempo.

Essa é a essência da resiliência.

Não significa ignorar falhas. Significa impedir que uma falha secundária derrube o fluxo principal.

Essa separação também melhora a experiência do usuário. Em vez de esperar todas as etapas concluírem, ele recebe uma resposta mais rápida sobre aquilo que realmente importa naquele momento. O restante do processamento acontece em segundo plano.

Para o usuário, a sensação é de velocidade.

Para o sistema, o ganho é de estabilidade.

Existe uma analogia simples que ajuda a explicar isso para quem não é técnico. Imagine um restaurante. Se o garçom precisasse anotar o pedido, cozinhar, preparar a bebida, lavar os pratos, fechar a conta e só então voltar à mesa, o atendimento seria lento e frágil. Qualquer problema em uma etapa bloquearia todo o processo.

Um restaurante funciona melhor porque as responsabilidades são separadas. O garçom registra o pedido, a cozinha prepara, o caixa cobra, alguém organiza a entrega e outras pessoas cuidam da limpeza. O cliente não precisa esperar todas as rotinas internas do restaurante terminarem para saber que seu pedido foi recebido.

Sistemas assíncronos seguem uma lógica parecida.

Eles não eliminam trabalho. Eles organizam o trabalho.

Essa organização é o que permite escalar.

Quando um sistema separa responsabilidades, ele ganha capacidade de absorver variações. Se a fila de e-mails cresce, você pode aumentar consumidores apenas para essa fila. Se a emissão de nota está lenta, o restante do sistema pode continuar funcionando. Se uma integração externa fica indisponível, você pode reprocessar mensagens depois sem bloquear o usuário.

Isso cria uma arquitetura mais tolerante a falhas.

Mas é importante dizer: processos assíncronos também trazem novos desafios.

O primeiro deles é a consistência eventual. Em um sistema síncrono, a tendência é esperar que tudo esteja atualizado ao mesmo tempo. Em um sistema assíncrono, algumas informações podem levar alguns segundos ou minutos para serem processadas. Isso precisa ser entendido pelo negócio e refletido na experiência do usuário.

Por exemplo, um pedido pode ser criado imediatamente, mas a nota fiscal pode ser emitida alguns segundos depois. Um relatório pode não refletir uma transação no mesmo instante em que ela ocorreu. Uma integração pode ser processada em segundo plano.

Isso não é necessariamente um problema. Muitas vezes é uma escolha arquitetural correta. Mas precisa ser comunicada e tratada.

O segundo desafio é a idempotência.

Em sistemas com filas, uma mesma mensagem pode ser processada mais de uma vez em determinados cenários. Por isso, os consumidores precisam estar preparados para lidar com repetição sem gerar efeitos colaterais indevidos.

Se um worker de pagamento processa a mesma mensagem duas vezes, ele não pode cobrar o cliente duas vezes. Se um worker de e-mail recebe a mesma mensagem novamente, talvez precise verificar se aquele e-mail já foi enviado. Se uma integração externa é reprocessada, o sistema precisa garantir que não haverá duplicidade.

Isso exige cuidado.

Um exemplo simples de proteção seria:

queue.consume('invoice.issue', async (message) => {
  const { orderId } = message;const existingInvoice = await findInvoiceByOrderId(orderId);
  if (existingInvoice) {
    return;
  }
  await issueInvoice(orderId);
});

Aqui, antes de emitir uma nota, o sistema verifica se ela já existe. Esse tipo de validação evita que o reprocessamento de mensagens gere problemas no negócio.

O terceiro desafio é observabilidade.

Quando o sistema deixa de ser linear, entender o que está acontecendo se torna mais difícil. Em um fluxo síncrono, você acompanha uma requisição do início ao fim. Em um fluxo assíncrono, o processo pode passar por filas, workers, reprocessamentos e diferentes serviços.

Sem observabilidade, filas viram caixas pretas.

Você precisa saber quantas mensagens estão pendentes, quantas falharam, quais estão sendo reprocessadas, quanto tempo cada tarefa demora e onde estão os gargalos. Caso contrário, o sistema pode parecer saudável na interface enquanto acumula problemas em segundo plano.

Esse é o motivo pelo qual assíncrono e observabilidade precisam andar juntos.

RabbitMQ, Kafka, SQS ou Pub/Sub resolvem a comunicação. Mas a empresa ainda precisa monitorar comportamento, falhas, atrasos e reprocessamentos. Ferramentas como Datadog, New Relic, Grafana, Prometheus e OpenTelemetry entram nesse ponto para dar visibilidade ao fluxo.

Outro ponto importante é que processos assíncronos não devem ser usados como desculpa para bagunça. Colocar tudo em fila sem critério pode criar um sistema mais difícil de entender do que o original. A decisão precisa ser orientada por responsabilidade, criticidade e impacto no usuário.

Nem tudo precisa ser assíncrono.

Operações que exigem resposta imediata, validações críticas ou decisões que precisam ser confirmadas no momento da requisição podem continuar síncronas. O erro está em colocar dentro do fluxo principal aquilo que não precisa estar ali.

Uma boa arquitetura não é aquela que usa fila em tudo. É aquela que sabe onde a fila faz sentido.

Esse discernimento é o que separa uso técnico de maturidade arquitetural.

Em sistemas financeiros, por exemplo, certas validações precisam acontecer imediatamente. Você não pode simplesmente dizer ao usuário que uma transação foi aprovada se a validação crítica ainda não ocorreu. Por outro lado, notificações, conciliações, auditorias complementares e atualizações de relatórios podem ser processadas de forma assíncrona.

Em e-commerces, o pedido e o pagamento podem fazer parte do fluxo principal, mas e-mails, recomendações, atualização de CRM e integrações secundárias podem ir para filas.

Em sistemas de saúde, o registro de uma informação crítica precisa ser confiável no momento da operação, mas rotinas de notificação, sincronização ou processamento analítico podem acontecer depois.

Em plataformas imobiliárias, automotivas ou marketplaces, integrações com portais externos, enriquecimento de dados, geração de relatórios e notificações normalmente se beneficiam muito de uma abordagem assíncrona.

A aplicação prática muda conforme o setor, mas o princípio permanece.

Separar o essencial do complementar.

Essa separação melhora a performance, mas esse não é o único benefício. Talvez nem seja o principal.

O maior benefício é reduzir o impacto de falhas.

Quando tudo está acoplado, uma falha pequena pode comprometer uma operação inteira. Quando responsabilidades estão separadas, a falha fica isolada. Ela pode ser monitorada, reprocessada e corrigida sem derrubar o fluxo principal.

Isso muda o comportamento do sistema em momentos de pressão.

E todo sistema que cresce passa por momentos de pressão.

Picos de acesso, instabilidade externa, aumento de processamento, campanhas comerciais, integrações fora do ar, mudanças de regra, crescimento de base de usuários. Em algum momento, o sistema será testado fora das condições ideais.

A pergunta é se ele foi construído para absorver isso ou se depende de tudo funcionando perfeitamente o tempo todo.

Sistemas que dependem de perfeição não escalam bem.

Eles apenas funcionam enquanto o ambiente é favorável.

Quando um negócio começa a crescer, a quantidade de situações imprevisíveis aumenta. É nesse momento que a arquitetura precisa deixar de ser apenas funcional e passar a ser resiliente.

Processos assíncronos fazem parte dessa transição.

Eles permitem que o sistema continue operando mesmo quando algumas partes estão lentas, indisponíveis ou sobrecarregadas. Permitem distribuir trabalho. Permitem reprocessar falhas. Permitem proteger o usuário de etapas que não precisam bloquear sua experiência.

Esse tipo de arquitetura mostra que a empresa entendeu uma coisa importante: nem tudo tem a mesma urgência.

E quando tudo é tratado como urgente, o sistema perde capacidade de priorização.

A maturidade está em saber diferenciar.

Existe também um impacto direto no time de desenvolvimento. Quando responsabilidades são separadas, o código tende a ficar mais organizado. Serviços passam a ter funções mais claras. Workers podem ser desenvolvidos, escalados e monitorados de forma independente. O time consegue evoluir partes do sistema sem mexer em todo o fluxo principal.

Isso facilita manutenção.

Também facilita escala de equipe.

Quando tudo está dentro do mesmo fluxo, qualquer alteração exige cuidado redobrado porque o impacto pode ser amplo. Quando responsabilidades são bem separadas, o escopo de mudança fica mais claro. Isso reduz medo, melhora previsibilidade e permite evolução mais segura.

Aqui existe uma ligação direta com testes automatizados. Quanto mais bem separadas estão as responsabilidades, mais fácil é testar cada parte. Um worker que processa envio de e-mail pode ser testado isoladamente. Um consumidor de fila de pagamento pode ter suas regras validadas com testes específicos. Um produtor de eventos pode ser verificado sem depender de todo o sistema rodando junto.

Ou seja, assíncrono não é apenas infraestrutura. Ele influencia arquitetura, testes, observabilidade, deploy e operação.

Essa é a razão pela qual empresas que querem escalar não podem tratar mensageria como detalhe técnico. Ela muda a forma como o sistema pensa, reage e evolui.

Mas existe um cuidado importante: complexidade desnecessária também é um problema.

Implementar Kafka em um sistema que só precisava de uma fila simples pode gerar mais custo do que benefício. Criar dezenas de eventos sem governança pode transformar o sistema em um labirinto. Usar mensageria sem padrões claros pode criar mensagens duplicadas, consumidores inconsistentes e fluxos difíceis de rastrear.

A ferramenta precisa servir ao problema, não ao ego técnico.

RabbitMQ pode ser excelente para uma grande parte dos cenários de fila. SQS pode ser suficiente para sistemas em AWS que precisam de simplicidade operacional. Kafka pode ser a escolha certa quando há alto volume de eventos, necessidade de retenção e múltiplos consumidores processando dados de formas diferentes. Azure Service Bus pode fazer sentido em ambientes corporativos Microsoft. Google Pub/Sub pode ser natural para arquiteturas em GCP.

Não existe ferramenta universal.

Existe contexto.

E contexto é o que define boa arquitetura.

No fim, processos assíncronos não são apenas uma forma de deixar o sistema mais rápido. São uma forma de tornar o sistema mais preparado para a realidade.

E a realidade é que APIs falham, bancos ficam lentos, serviços externos saem do ar, usuários acessam em picos, regras mudam e integrações se comportam de forma imprevisível.

Um sistema sério não pode depender de tudo funcionando perfeitamente ao mesmo tempo.

Ele precisa ser desenhado para continuar operando mesmo quando partes do ambiente falham.

Esse é o ponto central.

Quando cada operação depende de outra para terminar imediatamente, o sistema pode até parecer estável em pequena escala. Mas essa estabilidade é frágil, porque depende de uma sequência perfeita de acontecimentos.

À medida que o negócio cresce, essa sequência perfeita se torna cada vez menos provável.

Por isso, a pergunta não é apenas se sua aplicação está rápida hoje. A pergunta é se ela continuará confiável quando o volume aumentar, quando uma integração falhar, quando uma fila crescer, quando um serviço ficar lento ou quando uma operação precisar ser reprocessada.

Sistemas que escalam não são aqueles que nunca enfrentam falhas. São aqueles que foram desenhados para limitar o impacto dessas falhas.

Processos assíncronos ajudam exatamente nisso.

Eles não eliminam complexidade, mas organizam a complexidade. Não removem falhas, mas reduzem propagação. Não fazem tudo acontecer imediatamente, mas permitem que o sistema priorize o que realmente importa.

E essa priorização é uma das bases da escala.

Sem ela, a empresa continua empilhando responsabilidades no mesmo fluxo, até que o sistema se torne lento, frágil e difícil de evoluir.

Nesse ponto, o problema deixa de ser apenas técnico. Ele começa a afetar a operação, a experiência do usuário, a previsibilidade do time e a capacidade da empresa de crescer sem transformar cada nova demanda em risco.

Por isso, processos assíncronos não são luxo de arquitetura. Não são algo reservado apenas para grandes empresas. Não são apenas uma escolha técnica para quem gosta de mensageria.

Eles são uma resposta prática a um problema real: sistemas que crescem não podem depender de tudo acontecendo ao mesmo tempo.

Se sua empresa ainda trata todo processo como síncrono, toda integração como bloqueante e toda operação como imediata, talvez o sistema ainda esteja funcionando.

Mas isso não significa que ele esteja pronto para escalar.

A pergunta que fica é simples: seu sistema separa o que precisa acontecer agora do que pode acontecer depois, ou ainda está deixando o crescimento depender de tudo funcionar ao mesmo tempo? 🔥

It took me 3 days to reach the final solution. Not because I was missing a flag, but because the real problem was in how telemetry was born, connected, and consumed by New Relic’s UI.

If you have ever spent hours trying to make database observability work outside the officially supported path, this article may save you a lot of blind trial and error. What I want to show here is not just a working configuration. It is the reasoning that led me there, the path that failed, what I had to validate in NRQL, what New Relic’s interface was actually expecting to receive, and, in the end, the solution that finally made Query details and Execution plan work with MariaDB 10.5.

There is a very common assumption in observability that if the integration is installed, everything else should simply work. In practice, that is rarely true. Especially when you step outside the most comfortable path in the documentation and try to use an integration designed for a specific scenario on a database that is close, but not exactly within what the vendor officially supports. That is exactly what happened when I tried to make nri-mysql deliver the full monitoring experience for a MariaDB 10.5 environment.

The goal looked simple. I wanted New Relic to show, in a coherent way, slow queries, individual query details, and execution plan. What actually happened was very different. One part worked. Another part worked partially. And the most interesting part, which was Query details, remained empty. When that happens, the problem stops looking like ingestion and starts looking like internal telemetry coupling. That was the moment I stopped treating the situation as just another YAML configuration issue and started looking at it as I should have from the beginning, as a data model problem.

At first, the most obvious hypothesis was to blame MariaDB. After all, New Relic’s query performance flow is much more centered around MySQL 8 than MariaDB 10.5. So the idea of incompatibility felt natural. But there was one important detail. Wait time analysis was working. That meant New Relic was indeed receiving part of the database telemetry. The environment was not blind. The agent was not broken. Database access was not wrong. Collection existed, but the final view remained incomplete. And when collection exists but the interface still stays empty, the problem is usually no longer about being able to read the database. It is about how the events relate to each other.

This is the most common trap in this kind of troubleshooting. When an integration partially fails, the tendency is to keep pushing in the same direction. Change a flag, tweak a threshold, enable more metrics, restart the agent, test again. All of that solves configuration problems. None of that solves semantic problems. In my case, New Relic was showing an almost didactic situation. I had events arriving for some views. I had data in NRQL. I even had execution plans being generated in a custom format. But the native page remained empty. That was a strong indication that the interface did not merely want existing events. It wanted events that were coherent with each other.

That was when the investigation changed level. Instead of continuing to click around the interface waiting for something to unlock, I moved into NRQL and started checking what actually existed in New Relic’s event store. First, I confirmed that the individual events existed. Then I confirmed that the execution plan events also existed. Then I noticed a decisive detail. The native page was filtering by entityGuid. In other words, sending entityName was not enough. The page’s own internal query was using a different identifier. Once I understood that, an important piece finally fell into place.

Even after aligning the entity, the solution was still not complete. The top of the page depended on one thing. The execution plan depended on another. And both needed to talk to each other. At first, I had partial solutions coming from different places. One event coming from slow_log, another coming from performance_schema, and another one being artificially generated with EXPLAIN FORMAT=JSON. Separately, all of that looked reasonable. Together, it did not. Because New Relic’s UI does not want only three events with the correct names. It wants coherence between them. It wants the same query_id, the same event_id, the same thread_id, the same entity, and the same time window. Without that, the interface may receive data, but it still cannot assemble the full story.

That is why I abandoned the idea of mixing sources. The solution only started to become stable when I made all three event types be born from the same logical origin. What worked best was using recent statements from performance_schema.events_statements_current, performance_schema.events_statements_history, and performance_schema.events_statements_history_long. From there, I was able to generate MysqlIndividualQueriesSample, MysqlQueryExecutionSample, and MysqlSlowQueriesSample, all from the same recent set of queries. That was important because it allowed me to align the identifiers the UI uses to build the final view. Instead of three telemetry streams that merely looked similar, I ended up with three perspectives of the same telemetry.

When that part finally began to work, another issue appeared. Execution plan still looked strange. Some fields were coming back as zero. Some tables were only partially visible. Some steps simply disappeared. Once again, the database was not failing to respond. The problem was the format. EXPLAIN FORMAT=JSON in MariaDB 10.5 returns structures with repeated keys such as table, inside blocks that a more naive parser silently overwrites. The data was there. The parser was the thing throwing part of it away without noticing. Once I fixed that, the plan began to appear with much more coherence. Not perfect in every case, but functional. And functional was already much better than empty.

After that, another side effect showed up. The interface started to display queries that were useless for application analysis, such as SELECT version(), SELECT sleep(…), queries against information_schema, queries against performance_schema, EXPLAIN FORMAT=JSON, and SET commands. In other words, I had solved the pipeline, but I had still not solved panel quality. The answer was to filter that noise inside the script itself. It made no sense to send to the final view queries that only existed because of the inspection process itself or because of the monitoring process itself. From that point on, the screen started to show what actually mattered, which were real application queries.

In the end, the solution became much smaller than the problem initially suggested. I kept only two files, mariadb-config.yml and mariadb_query_execution.py. The first one defines nri-mysql-legacy and nri-flex. The second one uses performance_schema, filters noise, and generates the events compatible with New Relic’s interface. What unlocked Query details was not magic. It was the combination of origin coherence, entity identification coherence, and coherence between event identifiers.

Below are the two final files, already rewritten with flags and placeholders so that anyone can adapt them to their own environment without exposing usernames, passwords, real hostnames, or their own account identifiers.

mariadb-config.yml

integrations:
  - name: nri-mysql-legacy
    executable: /var/db/newrelic-infra/newrelic-integrations/bin/nri-mysql-legacy
    env:
      HOSTNAME: "${NR_MYSQL_HOST}"
      PORT: ${NR_MYSQL_PORT}
      USERNAME: "${NR_MYSQL_USER}"
      PASSWORD: "${NR_MYSQL_PASSWORD}"
      REMOTE_MONITORING: true
      EXTENDED_METRICS: true
      EXTENDED_INNODB_METRICS: true
      ENABLE_QUERY_MONITORING: true
      QUERY_MONITORING_RESPONSE_TIME_THRESHOLD: 1
      QUERY_MONITORING_COUNT_THRESHOLD: 20
    interval: 30s
    labels:
      env: "${NR_ENVIRONMENT}"
      role: "${NR_ROLE}"
    inventory_source: config/mysql

  - name: nri-flex
    config:
      name: mariadbQueryTelemetry
      apis:
        - name: mariadbFakeIndividualQueries
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=individual_queries
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlIndividualQueriesSample

        - name: mariadbSlowQueries
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=slow_queries
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlSlowQueriesSample

        - name: mariadbFakeQueryExecutionPlans
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=query_execution
                MYSQL_QUERY_PLAN_COMMAND_MODE=analyze
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlQueryExecutionSample

mariadb_query_execution.py

#!/usr/bin/env python3
"""
Generate fake MysqlQueryExecutionSample events for MariaDB by:
1. Reading recent SELECT/WITH statements from performance_schema
2. Running EXPLAIN FORMAT=JSON for each unique SQL text
3. Flattening MariaDB's JSON plan into step-based events that resemble
   New Relic's MysqlQueryExecutionSample shape

This is a compatibility workaround for environments where
MysqlIndividualQueriesSample and MysqlWaitEventsSample exist, but
MysqlQueryExecutionSample does not.
"""

import argparse
import binascii
from datetime import datetime
import json
import os
import re
import subprocess
import sys
import traceback
from typing import Any, Dict, List, Optional, Set, Tuple


DEBUG_ENABLED = os.getenv("MYSQL_QUERY_PLAN_DEBUG", "").lower() in ("1", "true", "yes", "on")


def debug(*parts: Any) -> None:
    if not DEBUG_ENABLED:
        return
    print("[mariadb_query_execution]", *parts, file=sys.stderr)


def mysql_command(
    *,
    host: str,
    port: str,
    user: str,
    password: str,
    database: Optional[str],
    sql: str,
) -> str:
    cmd = ["mysql", "--raw", "-N", "-B", "-h", host, "-P", str(port), "-u", user]
    if database:
        cmd.extend(["-D", database])
    cmd.extend(["-e", sql])

    env = os.environ.copy()
    env["MYSQL_PWD"] = password

    proc = subprocess.run(
        cmd,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        universal_newlines=True,
        env=env,
        check=False,
    )
    if proc.returncode != 0:
        raise RuntimeError(proc.stderr.strip() or proc.stdout.strip() or "mysql command failed")
    debug("mysql ok", "db=" + (database or ""), "sql=", " ".join(sql.split())[:240])
    return proc.stdout


def hexdecode_text(value: str) -> str:
    if not value:
        return ""
    return binascii.unhexlify(value.encode("ascii")).decode("utf-8", "replace")


def normalize_string(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, bool):
        return "true" if value else "false"
    return str(value)


def normalize_csv(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, list):
        return ",".join(str(item) for item in value)
    return str(value)


def normalize_int(value: Any) -> int:
    if value in (None, ""):
        return 0
    try:
        return int(value)
    except Exception:
        try:
            return int(float(value))
        except Exception:
            return 0


def normalize_float_string(value: Any) -> str:
    if value in (None, ""):
        return ""
    try:
        number = float(value)
    except Exception:
        return normalize_string(value)

    formatted = "{0:.3f}".format(number).rstrip("0").rstrip(".")
    return formatted or "0"


def format_bytes_human(value: Any) -> str:
    try:
        size = float(value)
    except Exception:
        return ""

    if size <= 0:
        return ""

    units = (
        (1024 ** 3, "G"),
        (1024 ** 2, "M"),
        (1024, "K"),
    )
    for threshold, suffix in units:
        if size >= threshold:
            scaled = size / threshold
            if abs(scaled - round(scaled)) < 0.05:
                return "{0}{1}".format(int(round(scaled)), suffix)
            return "{0:.1f}{1}".format(scaled, suffix)
    return str(int(round(size)))


def utc_now_iso() -> str:
    return datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")


def clean_identifier(value: str) -> str:
    text = normalize_string(value).strip()
    if not text:
        return ""
    text = text.replace("`", "")
    if "." in text:
        text = text.split(".")[-1]
    return text.strip()


def build_table_alias_map(query_text: str) -> Dict[str, str]:
    text = " ".join((query_text or "").replace("\n", " ").replace("\r", " ").split())
    if not text:
        return {}

    alias_map: Dict[str, str] = {}
    pattern = re.compile(
        r"(?i)\b(?:from|join)\s+"
        r"((?:`[^`]+`|\w+)(?:\s*\.\s*(?:`[^`]+`|\w+))?)"
        r"(?:\s+(?:as\s+)?(`[^`]+`|\w+))?"
    )

    for match in pattern.finditer(text):
        raw_table_name = match.group(1) or ""
        raw_alias = match.group(2) or ""

        table_name = clean_identifier(raw_table_name)
        alias = clean_identifier(raw_alias)
        if not table_name:
            continue

        alias_map[table_name.lower()] = table_name
        if alias:
            alias_map[alias.lower()] = table_name

    return alias_map


def is_noise_query(query_text: str) -> bool:
    text = " ".join((query_text or "").strip().lower().split())
    if not text:
        return True

    prefixes = (
        "set ",
        "show ",
        "explain ",
    )
    if text.startswith(prefixes):
        return True

    contains_any = (
        "select version(",
        "select `version`",
        "@@version_comment",
        "select sleep(",
        "information_schema.",
        "information_schema`",
        "performance_schema.",
        "performance_schema`",
        "events_statements_summary_by_digest",
        "innodb_trx",
    )
    return any(fragment in text for fragment in contains_any)


def preserve_duplicate_keys(pairs: List[Tuple[str, Any]]) -> Dict[str, Any]:
    data: Dict[str, Any] = {}
    for key, value in pairs:
        if key in data:
            existing = data[key]
            if isinstance(existing, list):
                existing.append(value)
            else:
                data[key] = [existing, value]
        else:
            data[key] = value
    return data


def parse_explain_json(raw: str) -> Dict[str, Any]:
    raw = raw.strip()
    if not raw:
        raise ValueError("empty EXPLAIN output")

    try:
        return json.loads(raw, object_pairs_hook=preserve_duplicate_keys)
    except json.JSONDecodeError:
        if "\\n" in raw or "\\t" in raw:
            try:
                return json.loads(
                    raw.encode("utf-8").decode("unicode_escape"),
                    object_pairs_hook=preserve_duplicate_keys,
                )
            except Exception:
                pass
        start = raw.find("{")
        end = raw.rfind("}")
        if start == -1 or end == -1 or start >= end:
            raise
        return json.loads(raw[start : end + 1], object_pairs_hook=preserve_duplicate_keys)


def extract_plan_steps(plan: Dict[str, Any], event_id: int, thread_id: int) -> List[Dict[str, Any]]:
    steps: List[Dict[str, Any]] = []
    step_id = 0
    root_query_cost = ""

    root_query_block = plan.get("query_block") if isinstance(plan.get("query_block"), dict) else {}
    if root_query_block:
        root_cost_info = root_query_block.get("cost_info") if isinstance(root_query_block.get("cost_info"), dict) else {}
        root_query_cost = normalize_string(root_cost_info.get("query_cost"))
        if not root_query_cost:
            root_query_cost = normalize_float_string(root_query_block.get("r_total_time_ms"))

    def visit(node: Any, inherited_query_cost: str = "", inherited_prefix_cost: str = "") -> None:
        nonlocal step_id

        if isinstance(node, dict):
            cost_info = node.get("cost_info") if isinstance(node.get("cost_info"), dict) else {}
            runtime_engine_stats = node.get("r_engine_stats") if isinstance(node.get("r_engine_stats"), dict) else {}

            query_cost = normalize_string(cost_info.get("query_cost")) or inherited_query_cost or root_query_cost
            if not query_cost:
                query_cost = normalize_float_string(node.get("r_total_time_ms"))

            table_name = normalize_string(node.get("table_name"))
            access_type = normalize_string(node.get("access_type"))

            if table_name:
                rows_value = node.get("rows_examined_per_scan", node.get("rows"))
                rows_join_value = node.get("rows_produced_per_join", node.get("rows"))
                filtered_value = node.get("r_filtered", node.get("filtered"))
                read_cost = normalize_string(cost_info.get("read_cost"))
                eval_cost = normalize_string(cost_info.get("eval_cost"))
                prefix_cost = normalize_string(cost_info.get("prefix_cost")) or inherited_prefix_cost
                data_read_per_join = normalize_string(cost_info.get("data_read_per_join"))

                if not read_cost:
                    read_cost = normalize_float_string(node.get("r_table_time_ms"))
                if not eval_cost:
                    eval_cost = normalize_float_string(node.get("r_other_time_ms"))
                if not prefix_cost:
                    prefix_cost = normalize_float_string(node.get("r_total_time_ms")) or query_cost
                if not data_read_per_join:
                    pages_accessed = runtime_engine_stats.get("pages_accessed")
                    pages_read_count = runtime_engine_stats.get("pages_read_count")
                    if pages_accessed not in (None, ""):
                        data_read_per_join = format_bytes_human(float(pages_accessed) * 16384)
                    elif pages_read_count not in (None, ""):
                        data_read_per_join = format_bytes_human(float(pages_read_count) * 16384)

                steps.append(
                    {
                        "event_id": int(event_id),
                        "thread_id": int(thread_id),
                        "step_id": step_id,
                        "query_cost": query_cost,
                        "table_name": table_name,
                        "access_type": access_type or "UNKNOWN",
                        "rows_examined_per_scan": normalize_int(rows_value),
                        "rows_produced_per_join": normalize_int(rows_join_value),
                        "filtered": normalize_float_string(filtered_value) or normalize_string(filtered_value),
                        "read_cost": read_cost,
                        "eval_cost": eval_cost,
                        "possible_keys": normalize_csv(node.get("possible_keys")),
                        "key": normalize_string(node.get("key")),
                        "used_key_parts": normalize_csv(node.get("used_key_parts")),
                        "ref": normalize_csv(node.get("ref")),
                        "prefix_cost": prefix_cost,
                        "data_read_per_join": data_read_per_join,
                        "using_index": normalize_string(node.get("using_index", False)),
                        "key_length": normalize_string(node.get("key_length")),
                    }
                )
                step_id += 1

            for value in node.values():
                visit(value, query_cost, prefix_cost if table_name else inherited_prefix_cost)

        elif isinstance(node, list):
            for item in node:
                visit(item, inherited_query_cost, inherited_prefix_cost)

    visit(plan)
    return steps


def is_useful_execution_step(step: Dict[str, Any]) -> bool:
    if normalize_int(step.get("event_id")) <= 0:
        return False
    if normalize_int(step.get("thread_id")) <= 0:
        return False
    if normalize_int(step.get("step_id")) < 0:
        return False

    table_name = normalize_string(step.get("table_name")).strip()
    access_type = normalize_string(step.get("access_type")).strip()

    if not table_name:
        return False
    if table_name.lower() == "other":
        return False
    if not access_type or access_type.upper() == "UNKNOWN":
        return False

    has_rows = (
        normalize_int(step.get("rows_examined_per_scan")) > 0
        or normalize_int(step.get("rows_produced_per_join")) > 0
    )
    has_index_details = any(
        normalize_string(step.get(field)).strip()
        for field in ("possible_keys", "key", "used_key_parts", "ref")
    )
    has_cost_details = any(
        normalize_string(step.get(field)).strip()
        for field in ("query_cost", "read_cost", "eval_cost", "prefix_cost", "data_read_per_join")
    )
    has_filter = normalize_string(step.get("filtered")).strip() not in ("", "0", "0.0")

    return has_rows or has_index_details or has_cost_details or has_filter


def candidate_query_sql(
    table_name: str, limit: int, threshold_ms: float, database_filter: Optional[str]
) -> str:
    where_parts = [
        "CURRENT_SCHEMA IS NOT NULL",
        "SQL_TEXT IS NOT NULL",
        "SQL_TEXT <> ''",
        "SQL_TEXT NOT LIKE '%?%'",
        "(SQL_TEXT LIKE 'SELECT %' OR SQL_TEXT LIKE 'WITH %')",
        f"TIMER_WAIT / 1000000000 > {threshold_ms}",
        "COALESCE(MYSQL_ERRNO, 0) = 0",
        "CURRENT_SCHEMA NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')",
    ]
    if database_filter:
        escaped_db = database_filter.replace("'", "''")
        where_parts.append(f"CURRENT_SCHEMA = '{escaped_db}'")

    return f"""
SELECT
  COALESCE(DIGEST, '') AS query_id,
  HEX(
    COALESCE(
      CASE
        WHEN CHAR_LENGTH(DIGEST_TEXT) > 4000 THEN CONCAT(LEFT(DIGEST_TEXT, 3997), '...')
        ELSE DIGEST_TEXT
      END,
      ''
    )
  ) AS query_text_hex,
  HEX(COALESCE(SQL_TEXT, '')) AS query_sample_text_hex,
  EVENT_ID,
  THREAD_ID,
  ROUND(TIMER_WAIT / 1000000000, 3) AS execution_time_ms,
  COALESCE(ROWS_SENT, 0) AS rows_sent,
  COALESCE(ROWS_EXAMINED, 0) AS rows_examined,
  COALESCE(CURRENT_SCHEMA, '') AS database_name
FROM performance_schema.{table_name}
WHERE {" AND ".join(where_parts)}
ORDER BY EVENT_ID DESC
LIMIT {int(limit)};
""".strip()


def slow_queries_sql(fetch_interval_seconds: int, query_count_threshold: int, database_filter: Optional[str]) -> str:
    where_parts = [
        "CONVERT_TZ(LAST_SEEN, @@session.time_zone, '+00:00') >= UTC_TIMESTAMP() - INTERVAL {0} SECOND".format(
            int(fetch_interval_seconds)
        ),
        "SCHEMA_NAME IS NOT NULL",
        "SCHEMA_NAME NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')",
    ]
    if database_filter:
        escaped_db = database_filter.replace("'", "''")
        where_parts.append("SCHEMA_NAME = '{0}'".format(escaped_db))

    return """
SELECT
  COALESCE(DIGEST, '') AS query_id,
  HEX(
    COALESCE(
      CASE
        WHEN CHAR_LENGTH(DIGEST_TEXT) > 4000 THEN CONCAT(LEFT(DIGEST_TEXT, 3997), '...')
        ELSE DIGEST_TEXT
      END,
      ''
    )
  ) AS query_text_hex,
  COALESCE(SCHEMA_NAME, '') AS database_name,
  COALESCE(COUNT_STAR, 0) AS execution_count,
  0 AS avg_cpu_time_ms,
  ROUND((SUM_TIMER_WAIT / NULLIF(COUNT_STAR, 0)) / 1000000000, 3) AS avg_elapsed_time_ms,
  COALESCE(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 0) AS avg_disk_reads,
  COALESCE(SUM_ROWS_AFFECTED / NULLIF(COUNT_STAR, 0), 0) AS avg_disk_writes,
  CASE
    WHEN SUM_NO_INDEX_USED > 0 THEN 'Yes'
    ELSE 'No'
  END AS has_full_table_scan,
  CASE
    WHEN DIGEST_TEXT LIKE 'SELECT%' THEN 'SELECT'
    WHEN DIGEST_TEXT LIKE 'INSERT%' THEN 'INSERT'
    WHEN DIGEST_TEXT LIKE 'UPDATE%' THEN 'UPDATE'
    WHEN DIGEST_TEXT LIKE 'DELETE%' THEN 'DELETE'
    ELSE 'OTHER'
  END AS statement_type,
  DATE_FORMAT(CONVERT_TZ(LAST_SEEN, @@session.time_zone, '+00:00'), '%Y-%m-%dT%H:%i:%sZ') AS last_execution_timestamp,
  DATE_FORMAT(UTC_TIMESTAMP(), '%Y-%m-%dT%H:%i:%sZ') AS collection_timestamp
FROM performance_schema.events_statements_summary_by_digest
WHERE {0}
ORDER BY avg_elapsed_time_ms DESC
LIMIT {1};
""".format(" AND ".join(where_parts), int(query_count_threshold)).strip()


def fetch_slow_query_summaries(args: argparse.Namespace) -> List[Dict[str, Any]]:
    sql = slow_queries_sql(args.fetch_interval_seconds, args.query_count_threshold, args.database_filter)
    raw = mysql_command(
        host=args.host,
        port=args.port,
        user=args.user,
        password=args.password,
        database=None,
        sql=sql,
    )

    summaries: List[Dict[str, Any]] = []
    for line in raw.splitlines():
        if not line.strip():
            continue
        parts = line.split("\t")
        if len(parts) != 12:
            continue

        (
            query_id,
            query_text_hex,
            database_name,
            execution_count,
            avg_cpu_time_ms,
            avg_elapsed_time_ms,
            avg_disk_reads,
            avg_disk_writes,
            has_full_table_scan,
            statement_type,
            last_execution_timestamp,
            collection_timestamp,
        ) = parts

        summaries.append(
            {
                "query_id": query_id,
                "query_text": hexdecode_text(query_text_hex),
                "database_name": database_name,
                "schema_name": database_name,
                "execution_count": normalize_int(execution_count),
                "avg_cpu_time_ms": float(avg_cpu_time_ms or 0),
                "avg_elapsed_time_ms": float(avg_elapsed_time_ms or 0),
                "avg_disk_reads": float(avg_disk_reads or 0),
                "avg_disk_writes": float(avg_disk_writes or 0),
                "has_full_table_scan": has_full_table_scan,
                "statement_type": statement_type,
                "last_execution_timestamp": last_execution_timestamp,
                "collection_timestamp": collection_timestamp,
            }
        )
    return summaries


def fetch_candidates(args: argparse.Namespace, allowed_query_ids: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
    candidates: List[Dict[str, Any]] = []
    seen: Set[Tuple[int, int]] = set()

    for table_name in (
        "events_statements_current",
        "events_statements_history",
        "events_statements_history_long",
    ):
        sql = candidate_query_sql(table_name, args.limit, args.threshold_ms, args.database_filter)
        raw = mysql_command(
            host=args.host,
            port=args.port,
            user=args.user,
            password=args.password,
            database=None,
            sql=sql,
        )
        debug("table", table_name, "rows", len([line for line in raw.splitlines() if line.strip()]))

        for line in raw.splitlines():
            if not line.strip():
                continue
            parts = line.split("\t")
            if len(parts) != 9:
                continue

            (
                query_id,
                query_text_hex,
                query_sample_text_hex,
                event_id,
                thread_id,
                execution_time_ms,
                rows_sent,
                rows_examined,
                database_name,
            ) = parts
            event_key = (normalize_int(event_id), normalize_int(thread_id))
            if event_key[0] <= 0 or event_key[1] <= 0:
                continue
            if event_key in seen:
                continue

            digest_text = hexdecode_text(query_text_hex).strip()
            query_sample_text = hexdecode_text(query_sample_text_hex).strip()
            if not query_sample_text:
                continue
            if is_noise_query(query_sample_text) or is_noise_query(digest_text):
                continue
            if allowed_query_ids is not None and query_id not in allowed_query_ids:
                continue

            seen.add(event_key)
            candidates.append(
                {
                    "query_id": query_id,
                    "query_text": digest_text,
                    "query_sample_text": query_sample_text,
                    "event_id": event_key[0],
                    "thread_id": event_key[1],
                    "execution_time_ms": float(execution_time_ms or 0),
                    "rows_sent": normalize_int(rows_sent),
                    "rows_examined": normalize_int(rows_examined),
                    "database_name": database_name,
                }
            )
            debug("candidate", table_name, event_key, query_sample_text[:180].replace("\n", "\\n"))

            if len(candidates) >= args.limit:
                return candidates[: args.limit]

    return candidates


def explain_query(args: argparse.Namespace, database_name: str, query_text: str) -> Dict[str, Any]:
    commands: List[str]
    if args.plan_command_mode == "auto":
        commands = ["ANALYZE FORMAT=JSON", "EXPLAIN FORMAT=JSON"]
    elif args.plan_command_mode == "analyze":
        commands = ["ANALYZE FORMAT=JSON"]
    else:
        commands = ["EXPLAIN FORMAT=JSON"]

    last_error: Optional[Exception] = None
    for command_prefix in commands:
        try:
            raw = mysql_command(
                host=args.host,
                port=args.port,
                user=args.user,
                password=args.password,
                database=database_name or None,
                sql=f"{command_prefix} {query_text}",
            )
            return parse_explain_json(raw)
        except Exception as exc:
            last_error = exc
            debug("plan command failed", command_prefix, str(exc))

    if last_error:
        raise last_error
    raise RuntimeError("unable to produce query plan")


def build_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    explain_cache: Dict[Tuple[str, str], List[Dict[str, Any]]] = {}
    events: List[Dict[str, Any]] = []

    for candidate in candidates:
        cache_key = (candidate["database_name"], candidate["query_sample_text"])
        alias_map = build_table_alias_map(candidate["query_sample_text"])

        if cache_key not in explain_cache:
            try:
                plan = explain_query(args, candidate["database_name"], candidate["query_sample_text"])
                explain_cache[cache_key] = extract_plan_steps(plan, 0, 0)
                debug(
                    "explain ok",
                    candidate["event_id"],
                    candidate["thread_id"],
                    "steps",
                    len(explain_cache[cache_key]),
                )
            except Exception:
                explain_cache[cache_key] = []
                debug(
                    "explain failed",
                    candidate["event_id"],
                    candidate["thread_id"],
                    candidate["query_sample_text"][:200].replace("\n", "\\n"),
                )
                debug(traceback.format_exc().strip())

        plan_steps = explain_cache[cache_key]
        if not plan_steps:
            continue

        for step in plan_steps:
            cloned = dict(step)
            cloned["event_id"] = candidate["event_id"]
            cloned["thread_id"] = candidate["thread_id"]
            cloned["query_id"] = candidate["query_id"]
            cloned["query_text"] = candidate["query_text"] or candidate["query_sample_text"]
            cloned["query_sample_text"] = candidate["query_sample_text"]
            cloned["database_name"] = candidate["database_name"]
            cloned["schema_name"] = candidate["database_name"]
            cloned["statement_type"] = (
                candidate["query_sample_text"].split(None, 1)[0].upper()
                if candidate["query_sample_text"].split(None, 1)
                else "UNKNOWN"
            )
            original_table_name = clean_identifier(cloned.get("table_name"))
            resolved_table_name = alias_map.get(original_table_name.lower(), "")
            if resolved_table_name and resolved_table_name != original_table_name:
                cloned["table_alias"] = original_table_name
                cloned["table_name"] = resolved_table_name
            if not is_useful_execution_step(cloned):
                debug(
                    "drop execution step",
                    cloned.get("event_id"),
                    cloned.get("thread_id"),
                    cloned.get("step_id"),
                    cloned.get("table_name"),
                    cloned.get("access_type"),
                )
                continue
            events.append(cloned)

    return events


def build_individual_query_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    events: List[Dict[str, Any]] = []
    for candidate in candidates:
        events.append(
            {
                "query_id": candidate["query_id"],
                "query_text": candidate["query_text"] or candidate["query_sample_text"],
                "event_id": candidate["event_id"],
                "thread_id": candidate["thread_id"],
                "execution_time_ms": candidate["execution_time_ms"],
                "rows_sent": candidate["rows_sent"],
                "rows_examined": candidate["rows_examined"],
                "database_name": candidate["database_name"],
            }
        )
    return events


def build_slow_query_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    grouped: Dict[str, Dict[str, Any]] = {}
    for candidate in candidates:
        query_id = candidate.get("query_id") or ""
        query_text = candidate.get("query_text") or candidate.get("query_sample_text") or ""
        group_key = query_id or query_text
        if not group_key:
            continue

        if group_key not in grouped:
            statement_type = (
                candidate["query_sample_text"].split(None, 1)[0].upper()
                if candidate.get("query_sample_text", "").split(None, 1)
                else "UNKNOWN"
            )
            grouped[group_key] = {
                "query_id": query_id,
                "query_text": query_text,
                "database_name": candidate["database_name"],
                "schema_name": candidate["database_name"],
                "execution_count": 0,
                "avg_cpu_time_ms": 0.0,
                "avg_elapsed_time_total_ms": 0.0,
                "avg_disk_reads_total": 0.0,
                "avg_disk_writes_total": 0.0,
                "has_full_table_scan": "Unknown",
                "statement_type": statement_type,
                "last_execution_timestamp": utc_now_iso(),
                "collection_timestamp": utc_now_iso(),
            }

        grouped[group_key]["execution_count"] += 1
        grouped[group_key]["avg_elapsed_time_total_ms"] += float(candidate.get("execution_time_ms", 0) or 0)
        grouped[group_key]["avg_disk_reads_total"] += float(candidate.get("rows_examined", 0) or 0)

    events: List[Dict[str, Any]] = []
    for summary in grouped.values():
        count = max(int(summary["execution_count"]), 1)
        events.append(
            {
                "query_id": summary["query_id"],
                "query_text": summary["query_text"],
                "database_name": summary["database_name"],
                "schema_name": summary["schema_name"],
                "execution_count": summary["execution_count"],
                "avg_cpu_time_ms": 0.0,
                "avg_elapsed_time_ms": round(summary["avg_elapsed_time_total_ms"] / count, 3),
                "avg_disk_reads": round(summary["avg_disk_reads_total"] / count, 3),
                "avg_disk_writes": 0.0,
                "has_full_table_scan": summary["has_full_table_scan"],
                "statement_type": summary["statement_type"],
                "last_execution_timestamp": summary["last_execution_timestamp"],
                "collection_timestamp": summary["collection_timestamp"],
            }
        )

    events.sort(key=lambda item: item.get("avg_elapsed_time_ms", 0), reverse=True)
    return events[: max(args.query_count_threshold, args.limit)]


def self_test() -> int:
    sample = {
        "query_block": {
            "select_id": 1,
            "nested_loop": [
                {
                    "table": {
                        "table_name": "tb_contratos",
                        "access_type": "ALL",
                        "possible_keys": ["PRIMARY"],
                        "key": "PRIMARY",
                        "key_length": "4",
                        "rows": 42,
                        "filtered": 100,
                        "using_index": True,
                        "cost_info": {
                            "query_cost": "12.40",
                            "read_cost": "11.10",
                            "eval_cost": "1.30",
                            "prefix_cost": "12.40",
                            "data_read_per_join": "16K"
                        }
                    }
                }
            ]
        }
    }
    events = extract_plan_steps(sample, 12345, 67890)
    print(json.dumps(events, indent=2))
    return 0 if events else 1


def parse_args(argv: List[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument("--host", default=os.getenv("MYSQL_HOST", "127.0.0.1"))
    parser.add_argument("--port", default=os.getenv("MYSQL_PORT", "3306"))
    parser.add_argument("--user", default=os.getenv("MYSQL_USER", "newrelic"))
    parser.add_argument("--password", default=os.getenv("MYSQL_PASSWORD", ""))
    parser.add_argument("--database-filter", default=os.getenv("MYSQL_DATABASE_FILTER", ""))
    parser.add_argument("--limit", type=int, default=int(os.getenv("MYSQL_QUERY_PLAN_LIMIT", "20")))
    parser.add_argument("--threshold-ms", type=float, default=float(os.getenv("MYSQL_QUERY_PLAN_THRESHOLD_MS", "1")))
    parser.add_argument(
        "--fetch-interval-seconds",
        type=int,
        default=int(os.getenv("MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS", "300")),
    )
    parser.add_argument(
        "--query-count-threshold",
        type=int,
        default=int(os.getenv("MYSQL_QUERY_MONITORING_COUNT_THRESHOLD", "20")),
    )
    parser.add_argument(
        "--mode",
        default=os.getenv("MYSQL_QUERY_PLAN_MODE", "query_execution"),
        choices=("query_execution", "individual_queries", "slow_queries"),
    )
    parser.add_argument(
        "--plan-command-mode",
        default=os.getenv("MYSQL_QUERY_PLAN_COMMAND_MODE", "auto"),
        choices=("auto", "analyze", "explain"),
    )
    parser.add_argument("--self-test", action="store_true")
    return parser.parse_args(argv)


def main(argv: List[str]) -> int:
    args = parse_args(argv)
    if args.self_test:
        return self_test()

    if not args.password:
        print("[]")
        return 0

    try:
        if args.mode == "individual_queries":
            events = build_individual_query_events(args)
        elif args.mode == "slow_queries":
            events = build_slow_query_events(args)
        else:
            events = build_events(args)
    except Exception:
        debug("build_events failed")
        debug(traceback.format_exc().strip())
        print("[]")
        return 0

    print(json.dumps(events))
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

At this point, the mechanical part is solved. What remains is showing how this is deployed and validated without exposing any sensitive data. First, I suggest defining the environment variables explicitly.

export NR_MYSQL_HOST="127.0.0.1"
export NR_MYSQL_PORT="3307"
export NR_MYSQL_USER="your_user"
export NR_MYSQL_PASSWORD="your_password"
export NR_MYSQL_DATABASE="your_database"
export NR_ENVIRONMENT="production"
export NR_ROLE="mariadb-3307"
export NR_APPLICATION_NAME="Your Application"
export NR_ENTITY_GUID="YOUR_ENTITY_GUID"
export NR_ENTITY_NAME="node:your-host:3307"
export NR_DISPLAY_NAME="your-host"
export NR_QUERY_PLAN_LIMIT="20"
export NR_QUERY_PLAN_THRESHOLD_MS="0"
export NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS="300"
export NR_QUERY_MONITORING_COUNT_THRESHOLD="20"

Then copy both files to the correct paths on the server.

sudo cp mariadb_query_execution.py /usr/local/bin/mariadb_query_execution.py
sudo chmod 755 /usr/local/bin/mariadb_query_execution.py
sudo cp mariadb-config.yml /etc/newrelic-infra/integrations.d/mariadb-config.yml

After that, I validated the script locally before restarting the agent. That step mattered because it removed the risk of debugging the interface while there was still a basic issue in the event generator itself.

python3 -m py_compile /usr/local/bin/mariadb_query_execution.py

Then I manually tested all three modes.

MYSQL_QUERY_PLAN_MODE=individual_queries python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool
MYSQL_QUERY_PLAN_MODE=slow_queries python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool
MYSQL_QUERY_PLAN_MODE=query_execution python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool

Only after that did I let nri-flex load the configuration and restart the agent.

sudo /usr/bin/nri-flex --config_path /etc/newrelic-infra/integrations.d/mariadb-config.yml --pretty --verbose
sudo systemctl restart newrelic-infra

The final validation in New Relic also stopped being purely visual. I wanted to confirm in NRQL whether the three event types existed, whether they were tied to the same entity, and whether what the interface was consuming was actually present in the event store

FROM MysqlIndividualQueriesSample
SELECT count(*)
WHERE entityGuid = 'YOUR_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

FROM MysqlQueryExecutionSample
SELECT count(*)
WHERE entityGuid = 'YOUR_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

FROM MysqlSlowQueriesSample
SELECT count(*)
WHERE entityGuid = 'YOUR_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

In the end, the interface’s own query became my strongest truth criterion. When it started returning the expected data, Query details stopped being empty. When Execution plan started building real steps with event_id, thread_id, and step_id, I knew the solution had stopped being an experiment and had become functional.

SELECT latest(execution_time_ms), latest(query_id), latest(query_text), latest(rows_examined), latest(rows_sent)
FROM MysqlIndividualQueriesSample
WHERE entityGuid = 'YOUR_ENTITY_GUID'
FACET event_id, thread_id
SINCE 30 minutes ago UNTIL now

SELECT latest(query_cost), latest(table_name), latest(access_type), latest(rows_examined_per_scan), latest(rows_produced_per_join), latest(filtered), latest(read_cost), latest(eval_cost), latest(prefix_cost), latest(data_read_per_join), latest(possible_keys), latest(key), latest(key_length), latest(used_key_parts), latest(ref), latest(using_index)
FROM MysqlQueryExecutionSample
WHERE entityGuid = 'YOUR_ENTITY_GUID'
FACET event_id, thread_id, step_id
SINCE 30 minutes ago UNTIL now

The biggest lesson from this experience was simple, but important. At first, I thought I was missing a flag. Then I thought I was missing a permission. Then I thought I was missing compatibility. In the end, what I was missing was coherence between events. That kind of detail does not usually appear in official setup guides because, in the supported scenario, it is already embedded in how the integration works. But when you need to adapt the flow for a database outside the vendor’s comfort zone, understanding the relationship between data stops being a luxury. It becomes the only way out of the dark.

Real observability is not about installing an agent. Real observability is about being able to trust that the story your dashboard is telling matches what the system is actually doing. Without that, you did not gain visibility. You only gained another pretty screen.

Foram 3 dias até a solução final. Não porque faltava uma flag, mas porque o problema real estava na forma como a telemetria nascia, se relacionava e era consumida pela UI do New Relic.

Se você já perdeu horas tentando fazer observabilidade de banco funcionar fora do cenário oficialmente suportado, este texto pode te poupar um bom tempo de tentativa cega. O que eu vou mostrar aqui não é apenas uma configuração pronta. É o raciocínio que me levou até ela, o caminho que falhou, o que precisei validar no NRQL, o que a interface do New Relic realmente esperava receber e, no fim, a solução que fez o Query details e o Execution plan finalmente funcionarem com MariaDB 10.5.

Existe uma ideia muito comum em observabilidade de que, se a integração está instalada, o resto deveria simplesmente funcionar. Na prática, quase nunca é assim. Principalmente quando você sai do caminho mais confortável da documentação e tenta usar uma integração desenhada para um cenário específico em um banco que está perto, mas não exatamente dentro do que o fornecedor considera oficialmente suportado. Foi exatamente isso que aconteceu comigo ao tentar fazer o nri-mysql entregar a experiência completa de monitoramento para um ambiente com MariaDB 10.5.

O objetivo parecia simples. Eu queria que o New Relic mostrasse, de forma coerente, slow queries, individual query details e execution plan. Só que o comportamento real era outro. Uma parte funcionava. Outra funcionava parcialmente. E justamente a parte mais interessante, que era o Query details, continuava vazia. Quando isso acontece, o problema deixa de parecer ingestão e começa a parecer acoplamento interno da telemetria. Foi nesse momento que eu parei de tratar a situação como mais uma configuração de YAML e comecei a olhar para ela como deveria ter olhado desde o começo, como um problema de modelo de dados.

No início, a hipótese mais óbvia era culpar o MariaDB. Afinal, a documentação do fluxo de query performance do New Relic gira muito mais em torno de MySQL 8 do que de MariaDB 10.5. Então a ideia de incompatibilidade parecia natural. Só que havia um detalhe importante. O Wait time analysis funcionava. Isso significava que o New Relic estava, sim, recebendo parte da telemetria do banco. O ambiente não estava cego. O agente não estava quebrado. O acesso ao banco não estava errado. A coleta existia, mas a visão final continuava incompleta. E quando a coleta existe, mas a interface permanece vazia, o problema normalmente não está mais em conseguir ler o banco. Ele está em como os eventos se relacionam entre si.

Essa é a armadilha mais comum nesse tipo de troubleshooting. Quando a integração falha parcialmente, a tendência é insistir sempre na mesma direção. Trocar flag, mudar threshold, ativar mais métricas, reiniciar agente, testar de novo. Tudo isso resolve problemas de configuração. Mas não resolve problemas de semântica. No meu caso, o New Relic mostrava uma situação quase didática. Eu tinha eventos chegando para algumas visões. Eu tinha dados no NRQL. Eu tinha até planos de execução sendo gerados em formato customizado. Mas a página nativa continuava vazia. Isso era um ótimo indicativo de que a interface não queria apenas eventos existentes. Ela queria eventos coerentes entre si.

Foi aí que a investigação mudou de nível. Em vez de continuar clicando na interface esperando que algo destravasse, eu fui para o NRQL e comecei a verificar o que realmente existia no banco de eventos do New Relic. Primeiro eu confirmei que os eventos individuais existiam. Depois eu confirmei que os eventos de plano de execução também existiam. Em seguida percebi um detalhe decisivo. A página nativa estava filtrando por entityGuid. Ou seja, não bastava mandar entityName. A própria consulta interna da tela estava usando um identificador diferente. Quando eu entendi isso, uma peça importante caiu no lugar.

Mesmo depois de alinhar a entidade, a solução ainda não estava pronta. O topo da tela dependia de uma coisa. O plano de execução dependia de outra. E os dois precisavam conversar. No começo, eu tinha soluções parciais vindas de lugares diferentes. Um evento vindo de slow_log, outro vindo de performance_schema e outro gerado artificialmente com EXPLAIN FORMAT=JSON. Separadamente, tudo parecia razoável. Juntos, não. Porque a UI do New Relic não quer apenas três eventos com nomes corretos. Ela quer coerência entre eles. Ela quer o mesmo query_id, o mesmo event_id, o mesmo thread_id, a mesma entidade e a mesma janela temporal. Sem isso, a interface até recebe dado, mas não consegue montar a história completa.

Foi por essa razão que eu abandonei a ideia de misturar fontes. A solução só começou a ficar estável quando eu fiz os três tipos de evento nascerem da mesma origem lógica. O que funcionou melhor foi usar statements recentes de performance_schema.events_statements_current, performance_schema.events_statements_history e performance_schema.events_statements_history_long. A partir deles, eu consegui gerar MysqlIndividualQueriesSample, MysqlQueryExecutionSample e MysqlSlowQueriesSample. Tudo a partir do mesmo conjunto de consultas recentes. Isso foi importante porque permitiu alinhar os identificadores que a UI usa para montar a visão. Em vez de três telemetrias parecidas, eu passei a ter três perspectivas da mesma telemetria.

Quando essa parte finalmente começou a funcionar, apareceu outro problema. O Execution plan ainda parecia estranho. Alguns campos vinham zerados. Algumas tabelas apareciam pela metade. Alguns passos simplesmente sumiam. Mais uma vez, o banco não estava deixando de responder. O problema era o formato. O EXPLAIN FORMAT=JSON do MariaDB 10.5 devolve estruturas com chaves repetidas, como table, em blocos que um parser mais ingênuo sobrescreve silenciosamente. O dado estava vindo. O parser é que estava jogando parte dele fora sem perceber. Quando eu corrigi isso, o plano começou a aparecer com muito mais coerência. Não perfeito em todos os casos, mas funcional. E funcional já era muito melhor do que vazio.

Depois disso, surgiu mais um efeito colateral. A interface começou a mostrar queries que não interessavam para a análise da aplicação, como SELECT version(), SELECT sleep(…), consultas a information_schema, consultas a performance_schema, EXPLAIN FORMAT=JSON e comandos SET. Ou seja, eu tinha resolvido o pipeline, mas ainda não tinha resolvido a qualidade do painel. A saída foi filtrar esse ruído no próprio script. Não fazia sentido mandar para a visão final queries que existiam apenas por causa do próprio processo de inspeção ou do próprio monitoramento. A partir daí, a tela começou a mostrar o que realmente importava, que eram as consultas reais da aplicação.

No fim, a solução ficou bem menor do que o problema parecia sugerir. Eu mantive apenas dois arquivos, mariadb-config.yml e mariadb_query_execution.py. O primeiro define o nri-mysql-legacy e o nri-flex. O segundo usa o performance_schema, filtra ruído e gera os eventos compatíveis para a interface do New Relic. O que destravou o Query details não foi uma mágica. Foi a combinação entre coerência de origem, coerência de identificação da entidade e coerência entre os identificadores dos eventos.

Abaixo estão os dois arquivos finais, já reescritos com flags e placeholders para que qualquer pessoa consiga adaptar ao próprio ambiente sem expor usuário, senha, hostname real ou identificadores da própria conta.

mariadb-config.yml

integrations:
  - name: nri-mysql-legacy
    executable: /var/db/newrelic-infra/newrelic-integrations/bin/nri-mysql-legacy
    env:
      HOSTNAME: "${NR_MYSQL_HOST}"
      PORT: ${NR_MYSQL_PORT}
      USERNAME: "${NR_MYSQL_USER}"
      PASSWORD: "${NR_MYSQL_PASSWORD}"
      REMOTE_MONITORING: true
      EXTENDED_METRICS: true
      EXTENDED_INNODB_METRICS: true
      ENABLE_QUERY_MONITORING: true
      QUERY_MONITORING_RESPONSE_TIME_THRESHOLD: 1
      QUERY_MONITORING_COUNT_THRESHOLD: 20
    interval: 30s
    labels:
      env: "${NR_ENVIRONMENT}"
      role: "${NR_ROLE}"
    inventory_source: config/mysql

  - name: nri-flex
    config:
      name: mariadbQueryTelemetry
      apis:
        - name: mariadbFakeIndividualQueries
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=individual_queries
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlIndividualQueriesSample

        - name: mariadbSlowQueries
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=slow_queries
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlSlowQueriesSample

        - name: mariadbFakeQueryExecutionPlans
          commands:
            - run: >-
                sh -c "MYSQL_HOST=${NR_MYSQL_HOST}
                MYSQL_PORT=${NR_MYSQL_PORT}
                MYSQL_USER=${NR_MYSQL_USER}
                MYSQL_PASSWORD='${NR_MYSQL_PASSWORD}'
                MYSQL_DATABASE_FILTER=${NR_MYSQL_DATABASE}
                MYSQL_QUERY_PLAN_LIMIT=${NR_QUERY_PLAN_LIMIT:-20}
                MYSQL_QUERY_PLAN_THRESHOLD_MS=${NR_QUERY_PLAN_THRESHOLD_MS:-0}
                MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS=${NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS:-300}
                MYSQL_QUERY_MONITORING_COUNT_THRESHOLD=${NR_QUERY_MONITORING_COUNT_THRESHOLD:-20}
                MYSQL_QUERY_PLAN_MODE=query_execution
                MYSQL_QUERY_PLAN_COMMAND_MODE=analyze
                python3 /usr/local/bin/mariadb_query_execution.py 2>/dev/null || echo '[]'"
          custom_attributes:
            application: "${NR_APPLICATION_NAME}"
            entityGuid: "${NR_ENTITY_GUID}"
            entityName: "${NR_ENTITY_NAME}"
            displayName: "${NR_DISPLAY_NAME}"
            hostname: "${NR_MYSQL_HOST}"
            port: "${NR_MYSQL_PORT}"
            db.instance: "${NR_MYSQL_DATABASE}"
            database.name: "${NR_MYSQL_DATABASE}"
          event_type: MysqlQueryExecutionSample

mariadb_query_execution.py

#!/usr/bin/env python3
"""
Generate fake MysqlQueryExecutionSample events for MariaDB by:
1. Reading recent SELECT/WITH statements from performance_schema
2. Running EXPLAIN FORMAT=JSON for each unique SQL text
3. Flattening MariaDB's JSON plan into step-based events that resemble
   New Relic's MysqlQueryExecutionSample shape

This is a compatibility workaround for environments where
MysqlIndividualQueriesSample and MysqlWaitEventsSample exist, but
MysqlQueryExecutionSample does not.
"""

import argparse
import binascii
from datetime import datetime
import json
import os
import re
import subprocess
import sys
import traceback
from typing import Any, Dict, List, Optional, Set, Tuple


DEBUG_ENABLED = os.getenv("MYSQL_QUERY_PLAN_DEBUG", "").lower() in ("1", "true", "yes", "on")


def debug(*parts: Any) -> None:
    if not DEBUG_ENABLED:
        return
    print("[mariadb_query_execution]", *parts, file=sys.stderr)


def mysql_command(
    *,
    host: str,
    port: str,
    user: str,
    password: str,
    database: Optional[str],
    sql: str,
) -> str:
    cmd = ["mysql", "--raw", "-N", "-B", "-h", host, "-P", str(port), "-u", user]
    if database:
        cmd.extend(["-D", database])
    cmd.extend(["-e", sql])

    env = os.environ.copy()
    env["MYSQL_PWD"] = password

    proc = subprocess.run(
        cmd,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        universal_newlines=True,
        env=env,
        check=False,
    )
    if proc.returncode != 0:
        raise RuntimeError(proc.stderr.strip() or proc.stdout.strip() or "mysql command failed")
    debug("mysql ok", "db=" + (database or ""), "sql=", " ".join(sql.split())[:240])
    return proc.stdout


def hexdecode_text(value: str) -> str:
    if not value:
        return ""
    return binascii.unhexlify(value.encode("ascii")).decode("utf-8", "replace")


def normalize_string(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, bool):
        return "true" if value else "false"
    return str(value)


def normalize_csv(value: Any) -> str:
    if value is None:
        return ""
    if isinstance(value, list):
        return ",".join(str(item) for item in value)
    return str(value)


def normalize_int(value: Any) -> int:
    if value in (None, ""):
        return 0
    try:
        return int(value)
    except Exception:
        try:
            return int(float(value))
        except Exception:
            return 0


def normalize_float_string(value: Any) -> str:
    if value in (None, ""):
        return ""
    try:
        number = float(value)
    except Exception:
        return normalize_string(value)

    formatted = "{0:.3f}".format(number).rstrip("0").rstrip(".")
    return formatted or "0"


def format_bytes_human(value: Any) -> str:
    try:
        size = float(value)
    except Exception:
        return ""

    if size <= 0:
        return ""

    units = (
        (1024 ** 3, "G"),
        (1024 ** 2, "M"),
        (1024, "K"),
    )
    for threshold, suffix in units:
        if size >= threshold:
            scaled = size / threshold
            if abs(scaled - round(scaled)) < 0.05:
                return "{0}{1}".format(int(round(scaled)), suffix)
            return "{0:.1f}{1}".format(scaled, suffix)
    return str(int(round(size)))


def utc_now_iso() -> str:
    return datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")


def clean_identifier(value: str) -> str:
    text = normalize_string(value).strip()
    if not text:
        return ""
    text = text.replace("`", "")
    if "." in text:
        text = text.split(".")[-1]
    return text.strip()


def build_table_alias_map(query_text: str) -> Dict[str, str]:
    text = " ".join((query_text or "").replace("\n", " ").replace("\r", " ").split())
    if not text:
        return {}

    alias_map: Dict[str, str] = {}
    pattern = re.compile(
        r"(?i)\b(?:from|join)\s+"
        r"((?:`[^`]+`|\w+)(?:\s*\.\s*(?:`[^`]+`|\w+))?)"
        r"(?:\s+(?:as\s+)?(`[^`]+`|\w+))?"
    )

    for match in pattern.finditer(text):
        raw_table_name = match.group(1) or ""
        raw_alias = match.group(2) or ""

        table_name = clean_identifier(raw_table_name)
        alias = clean_identifier(raw_alias)
        if not table_name:
            continue

        alias_map[table_name.lower()] = table_name
        if alias:
            alias_map[alias.lower()] = table_name

    return alias_map


def is_noise_query(query_text: str) -> bool:
    text = " ".join((query_text or "").strip().lower().split())
    if not text:
        return True

    prefixes = (
        "set ",
        "show ",
        "explain ",
    )
    if text.startswith(prefixes):
        return True

    contains_any = (
        "select version(",
        "select `version`",
        "@@version_comment",
        "select sleep(",
        "information_schema.",
        "information_schema`",
        "performance_schema.",
        "performance_schema`",
        "events_statements_summary_by_digest",
        "innodb_trx",
    )
    return any(fragment in text for fragment in contains_any)


def preserve_duplicate_keys(pairs: List[Tuple[str, Any]]) -> Dict[str, Any]:
    data: Dict[str, Any] = {}
    for key, value in pairs:
        if key in data:
            existing = data[key]
            if isinstance(existing, list):
                existing.append(value)
            else:
                data[key] = [existing, value]
        else:
            data[key] = value
    return data


def parse_explain_json(raw: str) -> Dict[str, Any]:
    raw = raw.strip()
    if not raw:
        raise ValueError("empty EXPLAIN output")

    try:
        return json.loads(raw, object_pairs_hook=preserve_duplicate_keys)
    except json.JSONDecodeError:
        if "\\n" in raw or "\\t" in raw:
            try:
                return json.loads(
                    raw.encode("utf-8").decode("unicode_escape"),
                    object_pairs_hook=preserve_duplicate_keys,
                )
            except Exception:
                pass
        start = raw.find("{")
        end = raw.rfind("}")
        if start == -1 or end == -1 or start >= end:
            raise
        return json.loads(raw[start : end + 1], object_pairs_hook=preserve_duplicate_keys)


def extract_plan_steps(plan: Dict[str, Any], event_id: int, thread_id: int) -> List[Dict[str, Any]]:
    steps: List[Dict[str, Any]] = []
    step_id = 0
    root_query_cost = ""

    root_query_block = plan.get("query_block") if isinstance(plan.get("query_block"), dict) else {}
    if root_query_block:
        root_cost_info = root_query_block.get("cost_info") if isinstance(root_query_block.get("cost_info"), dict) else {}
        root_query_cost = normalize_string(root_cost_info.get("query_cost"))
        if not root_query_cost:
            root_query_cost = normalize_float_string(root_query_block.get("r_total_time_ms"))

    def visit(node: Any, inherited_query_cost: str = "", inherited_prefix_cost: str = "") -> None:
        nonlocal step_id

        if isinstance(node, dict):
            cost_info = node.get("cost_info") if isinstance(node.get("cost_info"), dict) else {}
            runtime_engine_stats = node.get("r_engine_stats") if isinstance(node.get("r_engine_stats"), dict) else {}

            query_cost = normalize_string(cost_info.get("query_cost")) or inherited_query_cost or root_query_cost
            if not query_cost:
                query_cost = normalize_float_string(node.get("r_total_time_ms"))

            table_name = normalize_string(node.get("table_name"))
            access_type = normalize_string(node.get("access_type"))

            if table_name:
                rows_value = node.get("rows_examined_per_scan", node.get("rows"))
                rows_join_value = node.get("rows_produced_per_join", node.get("rows"))
                filtered_value = node.get("r_filtered", node.get("filtered"))
                read_cost = normalize_string(cost_info.get("read_cost"))
                eval_cost = normalize_string(cost_info.get("eval_cost"))
                prefix_cost = normalize_string(cost_info.get("prefix_cost")) or inherited_prefix_cost
                data_read_per_join = normalize_string(cost_info.get("data_read_per_join"))

                if not read_cost:
                    read_cost = normalize_float_string(node.get("r_table_time_ms"))
                if not eval_cost:
                    eval_cost = normalize_float_string(node.get("r_other_time_ms"))
                if not prefix_cost:
                    prefix_cost = normalize_float_string(node.get("r_total_time_ms")) or query_cost
                if not data_read_per_join:
                    pages_accessed = runtime_engine_stats.get("pages_accessed")
                    pages_read_count = runtime_engine_stats.get("pages_read_count")
                    if pages_accessed not in (None, ""):
                        data_read_per_join = format_bytes_human(float(pages_accessed) * 16384)
                    elif pages_read_count not in (None, ""):
                        data_read_per_join = format_bytes_human(float(pages_read_count) * 16384)

                steps.append(
                    {
                        "event_id": int(event_id),
                        "thread_id": int(thread_id),
                        "step_id": step_id,
                        "query_cost": query_cost,
                        "table_name": table_name,
                        "access_type": access_type or "UNKNOWN",
                        "rows_examined_per_scan": normalize_int(rows_value),
                        "rows_produced_per_join": normalize_int(rows_join_value),
                        "filtered": normalize_float_string(filtered_value) or normalize_string(filtered_value),
                        "read_cost": read_cost,
                        "eval_cost": eval_cost,
                        "possible_keys": normalize_csv(node.get("possible_keys")),
                        "key": normalize_string(node.get("key")),
                        "used_key_parts": normalize_csv(node.get("used_key_parts")),
                        "ref": normalize_csv(node.get("ref")),
                        "prefix_cost": prefix_cost,
                        "data_read_per_join": data_read_per_join,
                        "using_index": normalize_string(node.get("using_index", False)),
                        "key_length": normalize_string(node.get("key_length")),
                    }
                )
                step_id += 1

            for value in node.values():
                visit(value, query_cost, prefix_cost if table_name else inherited_prefix_cost)

        elif isinstance(node, list):
            for item in node:
                visit(item, inherited_query_cost, inherited_prefix_cost)

    visit(plan)
    return steps


def is_useful_execution_step(step: Dict[str, Any]) -> bool:
    if normalize_int(step.get("event_id")) <= 0:
        return False
    if normalize_int(step.get("thread_id")) <= 0:
        return False
    if normalize_int(step.get("step_id")) < 0:
        return False

    table_name = normalize_string(step.get("table_name")).strip()
    access_type = normalize_string(step.get("access_type")).strip()

    if not table_name:
        return False
    if table_name.lower() == "other":
        return False
    if not access_type or access_type.upper() == "UNKNOWN":
        return False

    has_rows = (
        normalize_int(step.get("rows_examined_per_scan")) > 0
        or normalize_int(step.get("rows_produced_per_join")) > 0
    )
    has_index_details = any(
        normalize_string(step.get(field)).strip()
        for field in ("possible_keys", "key", "used_key_parts", "ref")
    )
    has_cost_details = any(
        normalize_string(step.get(field)).strip()
        for field in ("query_cost", "read_cost", "eval_cost", "prefix_cost", "data_read_per_join")
    )
    has_filter = normalize_string(step.get("filtered")).strip() not in ("", "0", "0.0")

    return has_rows or has_index_details or has_cost_details or has_filter


def candidate_query_sql(
    table_name: str, limit: int, threshold_ms: float, database_filter: Optional[str]
) -> str:
    where_parts = [
        "CURRENT_SCHEMA IS NOT NULL",
        "SQL_TEXT IS NOT NULL",
        "SQL_TEXT <> ''",
        "SQL_TEXT NOT LIKE '%?%'",
        "(SQL_TEXT LIKE 'SELECT %' OR SQL_TEXT LIKE 'WITH %')",
        f"TIMER_WAIT / 1000000000 > {threshold_ms}",
        "COALESCE(MYSQL_ERRNO, 0) = 0",
        "CURRENT_SCHEMA NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')",
    ]
    if database_filter:
        escaped_db = database_filter.replace("'", "''")
        where_parts.append(f"CURRENT_SCHEMA = '{escaped_db}'")

    return f"""
SELECT
  COALESCE(DIGEST, '') AS query_id,
  HEX(
    COALESCE(
      CASE
        WHEN CHAR_LENGTH(DIGEST_TEXT) > 4000 THEN CONCAT(LEFT(DIGEST_TEXT, 3997), '...')
        ELSE DIGEST_TEXT
      END,
      ''
    )
  ) AS query_text_hex,
  HEX(COALESCE(SQL_TEXT, '')) AS query_sample_text_hex,
  EVENT_ID,
  THREAD_ID,
  ROUND(TIMER_WAIT / 1000000000, 3) AS execution_time_ms,
  COALESCE(ROWS_SENT, 0) AS rows_sent,
  COALESCE(ROWS_EXAMINED, 0) AS rows_examined,
  COALESCE(CURRENT_SCHEMA, '') AS database_name
FROM performance_schema.{table_name}
WHERE {" AND ".join(where_parts)}
ORDER BY EVENT_ID DESC
LIMIT {int(limit)};
""".strip()


def slow_queries_sql(fetch_interval_seconds: int, query_count_threshold: int, database_filter: Optional[str]) -> str:
    where_parts = [
        "CONVERT_TZ(LAST_SEEN, @@session.time_zone, '+00:00') >= UTC_TIMESTAMP() - INTERVAL {0} SECOND".format(
            int(fetch_interval_seconds)
        ),
        "SCHEMA_NAME IS NOT NULL",
        "SCHEMA_NAME NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')",
    ]
    if database_filter:
        escaped_db = database_filter.replace("'", "''")
        where_parts.append("SCHEMA_NAME = '{0}'".format(escaped_db))

    return """
SELECT
  COALESCE(DIGEST, '') AS query_id,
  HEX(
    COALESCE(
      CASE
        WHEN CHAR_LENGTH(DIGEST_TEXT) > 4000 THEN CONCAT(LEFT(DIGEST_TEXT, 3997), '...')
        ELSE DIGEST_TEXT
      END,
      ''
    )
  ) AS query_text_hex,
  COALESCE(SCHEMA_NAME, '') AS database_name,
  COALESCE(COUNT_STAR, 0) AS execution_count,
  0 AS avg_cpu_time_ms,
  ROUND((SUM_TIMER_WAIT / NULLIF(COUNT_STAR, 0)) / 1000000000, 3) AS avg_elapsed_time_ms,
  COALESCE(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 0) AS avg_disk_reads,
  COALESCE(SUM_ROWS_AFFECTED / NULLIF(COUNT_STAR, 0), 0) AS avg_disk_writes,
  CASE
    WHEN SUM_NO_INDEX_USED > 0 THEN 'Yes'
    ELSE 'No'
  END AS has_full_table_scan,
  CASE
    WHEN DIGEST_TEXT LIKE 'SELECT%' THEN 'SELECT'
    WHEN DIGEST_TEXT LIKE 'INSERT%' THEN 'INSERT'
    WHEN DIGEST_TEXT LIKE 'UPDATE%' THEN 'UPDATE'
    WHEN DIGEST_TEXT LIKE 'DELETE%' THEN 'DELETE'
    ELSE 'OTHER'
  END AS statement_type,
  DATE_FORMAT(CONVERT_TZ(LAST_SEEN, @@session.time_zone, '+00:00'), '%Y-%m-%dT%H:%i:%sZ') AS last_execution_timestamp,
  DATE_FORMAT(UTC_TIMESTAMP(), '%Y-%m-%dT%H:%i:%sZ') AS collection_timestamp
FROM performance_schema.events_statements_summary_by_digest
WHERE {0}
ORDER BY avg_elapsed_time_ms DESC
LIMIT {1};
""".format(" AND ".join(where_parts), int(query_count_threshold)).strip()


def fetch_slow_query_summaries(args: argparse.Namespace) -> List[Dict[str, Any]]:
    sql = slow_queries_sql(args.fetch_interval_seconds, args.query_count_threshold, args.database_filter)
    raw = mysql_command(
        host=args.host,
        port=args.port,
        user=args.user,
        password=args.password,
        database=None,
        sql=sql,
    )

    summaries: List[Dict[str, Any]] = []
    for line in raw.splitlines():
        if not line.strip():
            continue
        parts = line.split("\t")
        if len(parts) != 12:
            continue

        (
            query_id,
            query_text_hex,
            database_name,
            execution_count,
            avg_cpu_time_ms,
            avg_elapsed_time_ms,
            avg_disk_reads,
            avg_disk_writes,
            has_full_table_scan,
            statement_type,
            last_execution_timestamp,
            collection_timestamp,
        ) = parts

        summaries.append(
            {
                "query_id": query_id,
                "query_text": hexdecode_text(query_text_hex),
                "database_name": database_name,
                "schema_name": database_name,
                "execution_count": normalize_int(execution_count),
                "avg_cpu_time_ms": float(avg_cpu_time_ms or 0),
                "avg_elapsed_time_ms": float(avg_elapsed_time_ms or 0),
                "avg_disk_reads": float(avg_disk_reads or 0),
                "avg_disk_writes": float(avg_disk_writes or 0),
                "has_full_table_scan": has_full_table_scan,
                "statement_type": statement_type,
                "last_execution_timestamp": last_execution_timestamp,
                "collection_timestamp": collection_timestamp,
            }
        )
    return summaries


def fetch_candidates(args: argparse.Namespace, allowed_query_ids: Optional[Set[str]] = None) -> List[Dict[str, Any]]:
    candidates: List[Dict[str, Any]] = []
    seen: Set[Tuple[int, int]] = set()

    for table_name in (
        "events_statements_current",
        "events_statements_history",
        "events_statements_history_long",
    ):
        sql = candidate_query_sql(table_name, args.limit, args.threshold_ms, args.database_filter)
        raw = mysql_command(
            host=args.host,
            port=args.port,
            user=args.user,
            password=args.password,
            database=None,
            sql=sql,
        )
        debug("table", table_name, "rows", len([line for line in raw.splitlines() if line.strip()]))

        for line in raw.splitlines():
            if not line.strip():
                continue
            parts = line.split("\t")
            if len(parts) != 9:
                continue

            (
                query_id,
                query_text_hex,
                query_sample_text_hex,
                event_id,
                thread_id,
                execution_time_ms,
                rows_sent,
                rows_examined,
                database_name,
            ) = parts
            event_key = (normalize_int(event_id), normalize_int(thread_id))
            if event_key[0] <= 0 or event_key[1] <= 0:
                continue
            if event_key in seen:
                continue

            digest_text = hexdecode_text(query_text_hex).strip()
            query_sample_text = hexdecode_text(query_sample_text_hex).strip()
            if not query_sample_text:
                continue
            if is_noise_query(query_sample_text) or is_noise_query(digest_text):
                continue
            if allowed_query_ids is not None and query_id not in allowed_query_ids:
                continue

            seen.add(event_key)
            candidates.append(
                {
                    "query_id": query_id,
                    "query_text": digest_text,
                    "query_sample_text": query_sample_text,
                    "event_id": event_key[0],
                    "thread_id": event_key[1],
                    "execution_time_ms": float(execution_time_ms or 0),
                    "rows_sent": normalize_int(rows_sent),
                    "rows_examined": normalize_int(rows_examined),
                    "database_name": database_name,
                }
            )
            debug("candidate", table_name, event_key, query_sample_text[:180].replace("\n", "\\n"))

            if len(candidates) >= args.limit:
                return candidates[: args.limit]

    return candidates


def explain_query(args: argparse.Namespace, database_name: str, query_text: str) -> Dict[str, Any]:
    commands: List[str]
    if args.plan_command_mode == "auto":
        commands = ["ANALYZE FORMAT=JSON", "EXPLAIN FORMAT=JSON"]
    elif args.plan_command_mode == "analyze":
        commands = ["ANALYZE FORMAT=JSON"]
    else:
        commands = ["EXPLAIN FORMAT=JSON"]

    last_error: Optional[Exception] = None
    for command_prefix in commands:
        try:
            raw = mysql_command(
                host=args.host,
                port=args.port,
                user=args.user,
                password=args.password,
                database=database_name or None,
                sql=f"{command_prefix} {query_text}",
            )
            return parse_explain_json(raw)
        except Exception as exc:
            last_error = exc
            debug("plan command failed", command_prefix, str(exc))

    if last_error:
        raise last_error
    raise RuntimeError("unable to produce query plan")


def build_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    explain_cache: Dict[Tuple[str, str], List[Dict[str, Any]]] = {}
    events: List[Dict[str, Any]] = []

    for candidate in candidates:
        cache_key = (candidate["database_name"], candidate["query_sample_text"])
        alias_map = build_table_alias_map(candidate["query_sample_text"])

        if cache_key not in explain_cache:
            try:
                plan = explain_query(args, candidate["database_name"], candidate["query_sample_text"])
                explain_cache[cache_key] = extract_plan_steps(plan, 0, 0)
                debug(
                    "explain ok",
                    candidate["event_id"],
                    candidate["thread_id"],
                    "steps",
                    len(explain_cache[cache_key]),
                )
            except Exception:
                explain_cache[cache_key] = []
                debug(
                    "explain failed",
                    candidate["event_id"],
                    candidate["thread_id"],
                    candidate["query_sample_text"][:200].replace("\n", "\\n"),
                )
                debug(traceback.format_exc().strip())

        plan_steps = explain_cache[cache_key]
        if not plan_steps:
            continue

        for step in plan_steps:
            cloned = dict(step)
            cloned["event_id"] = candidate["event_id"]
            cloned["thread_id"] = candidate["thread_id"]
            cloned["query_id"] = candidate["query_id"]
            cloned["query_text"] = candidate["query_text"] or candidate["query_sample_text"]
            cloned["query_sample_text"] = candidate["query_sample_text"]
            cloned["database_name"] = candidate["database_name"]
            cloned["schema_name"] = candidate["database_name"]
            cloned["statement_type"] = (
                candidate["query_sample_text"].split(None, 1)[0].upper()
                if candidate["query_sample_text"].split(None, 1)
                else "UNKNOWN"
            )
            original_table_name = clean_identifier(cloned.get("table_name"))
            resolved_table_name = alias_map.get(original_table_name.lower(), "")
            if resolved_table_name and resolved_table_name != original_table_name:
                cloned["table_alias"] = original_table_name
                cloned["table_name"] = resolved_table_name
            if not is_useful_execution_step(cloned):
                debug(
                    "drop execution step",
                    cloned.get("event_id"),
                    cloned.get("thread_id"),
                    cloned.get("step_id"),
                    cloned.get("table_name"),
                    cloned.get("access_type"),
                )
                continue
            events.append(cloned)

    return events


def build_individual_query_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    events: List[Dict[str, Any]] = []
    for candidate in candidates:
        events.append(
            {
                "query_id": candidate["query_id"],
                "query_text": candidate["query_text"] or candidate["query_sample_text"],
                "event_id": candidate["event_id"],
                "thread_id": candidate["thread_id"],
                "execution_time_ms": candidate["execution_time_ms"],
                "rows_sent": candidate["rows_sent"],
                "rows_examined": candidate["rows_examined"],
                "database_name": candidate["database_name"],
            }
        )
    return events


def build_slow_query_events(args: argparse.Namespace) -> List[Dict[str, Any]]:
    candidates = fetch_candidates(args)
    if not candidates:
        return []

    grouped: Dict[str, Dict[str, Any]] = {}
    for candidate in candidates:
        query_id = candidate.get("query_id") or ""
        query_text = candidate.get("query_text") or candidate.get("query_sample_text") or ""
        group_key = query_id or query_text
        if not group_key:
            continue

        if group_key not in grouped:
            statement_type = (
                candidate["query_sample_text"].split(None, 1)[0].upper()
                if candidate.get("query_sample_text", "").split(None, 1)
                else "UNKNOWN"
            )
            grouped[group_key] = {
                "query_id": query_id,
                "query_text": query_text,
                "database_name": candidate["database_name"],
                "schema_name": candidate["database_name"],
                "execution_count": 0,
                "avg_cpu_time_ms": 0.0,
                "avg_elapsed_time_total_ms": 0.0,
                "avg_disk_reads_total": 0.0,
                "avg_disk_writes_total": 0.0,
                "has_full_table_scan": "Unknown",
                "statement_type": statement_type,
                "last_execution_timestamp": utc_now_iso(),
                "collection_timestamp": utc_now_iso(),
            }

        grouped[group_key]["execution_count"] += 1
        grouped[group_key]["avg_elapsed_time_total_ms"] += float(candidate.get("execution_time_ms", 0) or 0)
        grouped[group_key]["avg_disk_reads_total"] += float(candidate.get("rows_examined", 0) or 0)

    events: List[Dict[str, Any]] = []
    for summary in grouped.values():
        count = max(int(summary["execution_count"]), 1)
        events.append(
            {
                "query_id": summary["query_id"],
                "query_text": summary["query_text"],
                "database_name": summary["database_name"],
                "schema_name": summary["schema_name"],
                "execution_count": summary["execution_count"],
                "avg_cpu_time_ms": 0.0,
                "avg_elapsed_time_ms": round(summary["avg_elapsed_time_total_ms"] / count, 3),
                "avg_disk_reads": round(summary["avg_disk_reads_total"] / count, 3),
                "avg_disk_writes": 0.0,
                "has_full_table_scan": summary["has_full_table_scan"],
                "statement_type": summary["statement_type"],
                "last_execution_timestamp": summary["last_execution_timestamp"],
                "collection_timestamp": summary["collection_timestamp"],
            }
        )

    events.sort(key=lambda item: item.get("avg_elapsed_time_ms", 0), reverse=True)
    return events[: max(args.query_count_threshold, args.limit)]


def self_test() -> int:
    sample = {
        "query_block": {
            "select_id": 1,
            "nested_loop": [
                {
                    "table": {
                        "table_name": "tb_contratos",
                        "access_type": "ALL",
                        "possible_keys": ["PRIMARY"],
                        "key": "PRIMARY",
                        "key_length": "4",
                        "rows": 42,
                        "filtered": 100,
                        "using_index": True,
                        "cost_info": {
                            "query_cost": "12.40",
                            "read_cost": "11.10",
                            "eval_cost": "1.30",
                            "prefix_cost": "12.40",
                            "data_read_per_join": "16K"
                        }
                    }
                }
            ]
        }
    }
    events = extract_plan_steps(sample, 12345, 67890)
    print(json.dumps(events, indent=2))
    return 0 if events else 1


def parse_args(argv: List[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    parser.add_argument("--host", default=os.getenv("MYSQL_HOST", "127.0.0.1"))
    parser.add_argument("--port", default=os.getenv("MYSQL_PORT", "3306"))
    parser.add_argument("--user", default=os.getenv("MYSQL_USER", "newrelic"))
    parser.add_argument("--password", default=os.getenv("MYSQL_PASSWORD", ""))
    parser.add_argument("--database-filter", default=os.getenv("MYSQL_DATABASE_FILTER", ""))
    parser.add_argument("--limit", type=int, default=int(os.getenv("MYSQL_QUERY_PLAN_LIMIT", "20")))
    parser.add_argument("--threshold-ms", type=float, default=float(os.getenv("MYSQL_QUERY_PLAN_THRESHOLD_MS", "1")))
    parser.add_argument(
        "--fetch-interval-seconds",
        type=int,
        default=int(os.getenv("MYSQL_SLOW_QUERY_FETCH_INTERVAL_SECONDS", "300")),
    )
    parser.add_argument(
        "--query-count-threshold",
        type=int,
        default=int(os.getenv("MYSQL_QUERY_MONITORING_COUNT_THRESHOLD", "20")),
    )
    parser.add_argument(
        "--mode",
        default=os.getenv("MYSQL_QUERY_PLAN_MODE", "query_execution"),
        choices=("query_execution", "individual_queries", "slow_queries"),
    )
    parser.add_argument(
        "--plan-command-mode",
        default=os.getenv("MYSQL_QUERY_PLAN_COMMAND_MODE", "auto"),
        choices=("auto", "analyze", "explain"),
    )
    parser.add_argument("--self-test", action="store_true")
    return parser.parse_args(argv)


def main(argv: List[str]) -> int:
    args = parse_args(argv)
    if args.self_test:
        return self_test()

    if not args.password:
        print("[]")
        return 0

    try:
        if args.mode == "individual_queries":
            events = build_individual_query_events(args)
        elif args.mode == "slow_queries":
            events = build_slow_query_events(args)
        else:
            events = build_events(args)
    except Exception:
        debug("build_events failed")
        debug(traceback.format_exc().strip())
        print("[]")
        return 0

    print(json.dumps(events))
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))

Até aqui, a parte mecânica está resolvida. O que resta é mostrar como isso é implantado e validado sem expor nenhum dado sensível. Primeiro, eu sugiro definir as variáveis do ambiente de forma explícita:

export NR_MYSQL_HOST="127.0.0.1"
export NR_MYSQL_PORT="3307"
export NR_MYSQL_USER="seu_usuario"
export NR_MYSQL_PASSWORD="sua_senha"
export NR_MYSQL_DATABASE="seu_banco"
export NR_ENVIRONMENT="production"
export NR_ROLE="mariadb-3307"
export NR_APPLICATION_NAME="Sua Aplicacao"
export NR_ENTITY_GUID="SEU_ENTITY_GUID"
export NR_ENTITY_NAME="node:seu-host:3307"
export NR_DISPLAY_NAME="seu-host"
export NR_QUERY_PLAN_LIMIT="20"
export NR_QUERY_PLAN_THRESHOLD_MS="0"
export NR_SLOW_QUERY_FETCH_INTERVAL_SECONDS="300"
export NR_QUERY_MONITORING_COUNT_THRESHOLD="20"

Em seguida, copiar os dois arquivos para os caminhos corretos do servidor:

sudo cp mariadb_query_execution.py /usr/local/bin/mariadb_query_execution.py
sudo chmod 755 /usr/local/bin/mariadb_query_execution.py
sudo cp mariadb-config.yml /etc/newrelic-infra/integrations.d/mariadb-config.yml

Depois disso, eu validei o script localmente antes de reiniciar o agente. Esse passo foi importante porque eliminou a chance de eu estar depurando a interface enquanto ainda havia um problema básico no próprio gerador de eventos.

python3 -m py_compile /usr/local/bin/mariadb_query_execution.py

Em seguida, eu testei os três modos manualmente:

MYSQL_QUERY_PLAN_MODE=individual_queries python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool
MYSQL_QUERY_PLAN_MODE=slow_queries python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool
MYSQL_QUERY_PLAN_MODE=query_execution python3 /usr/local/bin/mariadb_query_execution.py | python3 -m json.tool

Só depois disso eu mandei o nri-flex carregar a configuração e reiniciei o agente:

sudo /usr/bin/nri-flex --config_path /etc/newrelic-infra/integrations.d/mariadb-config.yml --pretty --verbose
sudo systemctl restart newrelic-infra

A validação final no New Relic também deixou de ser visual apenas. Eu quis confirmar no NRQL se os três tipos de evento existiam, se estavam usando a mesma entidade e se o que a interface consumia realmente estava presente no banco de eventos.

FROM MysqlIndividualQueriesSample
SELECT count(*)
WHERE entityGuid = 'SEU_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

FROM MysqlQueryExecutionSample
SELECT count(*)
WHERE entityGuid = 'SEU_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

FROM MysqlSlowQueriesSample
SELECT count(*)
WHERE entityGuid = 'SEU_ENTITY_GUID'
AND error IS NULL
SINCE 5 minutes ago

No fim, a própria query que a interface usa foi o meu melhor critério de verdade. Quando ela começou a responder do jeito certo, o Query details deixou de ficar vazio. Quando o Execution plan começou a montar steps reais com event_id, thread_id e step_id, eu soube que a solução tinha deixado de ser um experimento e passado a ser funcional.

SELECT latest(execution_time_ms), latest(query_id), latest(query_text), latest(rows_examined), latest(rows_sent)
FROM MysqlIndividualQueriesSample
WHERE entityGuid = 'SEU_ENTITY_GUID'
FACET event_id, thread_id
SINCE 30 minutes ago UNTIL now

SELECT latest(query_cost), latest(table_name), latest(access_type), latest(rows_examined_per_scan), latest(rows_produced_per_join), latest(filtered), latest(read_cost), latest(eval_cost), latest(prefix_cost), latest(data_read_per_join), latest(possible_keys), latest(key), latest(key_length), latest(used_key_parts), latest(ref), latest(using_index)
FROM MysqlQueryExecutionSample
WHERE entityGuid = 'SEU_ENTITY_GUID'
FACET event_id, thread_id, step_id
SINCE 30 minutes ago UNTIL now

A grande lição dessa experiência foi simples, mas importante. No começo, eu achei que faltava uma flag. Depois, achei que faltava uma permissão. Depois, achei que faltava compatibilidade. No fim, o que faltava era coerência entre os eventos. Esse é o tipo de detalhe que não costuma aparecer no passo a passo oficial porque, no cenário suportado, ele já vem embutido no funcionamento da integração. Mas quando você precisa adaptar o fluxo para um banco fora da zona de conforto do fornecedor, entender a relação entre os dados deixa de ser um luxo. Vira a única forma de sair do escuro.

Observabilidade real não é instalar agente. Observabilidade real é conseguir confiar que a história que o painel está te contando corresponde ao que o sistema está fazendo. Sem isso, você não ganhou visibilidade. Só ganhou mais uma tela bonita.

When a company relies only on manual validation, every change becomes a risk, every deployment becomes a moment of tension, and growth starts compromising the evolution of the system itself.

There is a common belief in software development that systems start facing serious problems when they grow. At first, the explanation seems logical. More users generate more load. More features create more complexity. More integrations introduce more points of failure. At some point, if nothing is adjusted, something will break.

That interpretation is not wrong, but it is incomplete.

In practice, many systems start failing before they ever reach a high volume of users. They do not break first because of traffic, lack of servers, or infrastructure limitations. They begin to slow down for a different reason, one that is much quieter and much more dangerous: the lack of confidence to evolve.

This is something that does not always appear in technical reports, but it becomes clear in the behavior of the team. Developers start becoming afraid of touching certain parts of the codebase. Simple changes begin to require long manual validations. Deployments stop being a natural step in the process and start being treated as a risky event. Little by little, the company loses speed, not because the team is no longer capable, but because the system no longer feels safe.

This is one of the first signs that an application is not ready to scale.

When a system is small, almost everything can be handled through proximity. The developer knows the code, understands the business rules, knows which screens need to be tested, and often manages to validate everything manually before releasing a new version. There is a direct relationship between the person building, the person testing, and the person watching the result.

That model works for a while.

The problem is that systems do not remain small when the business starts to grow. New rules are added, exceptions appear, external integrations become part of the flow, different people start contributing to the codebase, and knowledge is no longer concentrated in one person’s head. What used to be simple to validate manually starts becoming unpredictable.

A change in a form can affect a calculation rule. A backend adjustment can break a screen that apparently had nothing to do with that part of the system. An API change can impact a mobile app, an admin dashboard, or an external integration. And when there is no automated validation layer, all of this depends on someone remembering to test it.

That is where risk starts to accumulate.

Automated tests exist precisely to reduce this dependence on human memory. They do not eliminate every problem, they do not replace critical thinking, and they do not magically turn a bad system into a good one. But they create a fundamental layer of safety so that software can evolve without every change feeling like a leap in the dark.

There is a very common phrase in development teams: “But I only changed one small thing.” Almost every production incident has started with some version of that sentence. The problem is that, in real systems, very few things are truly isolated. A seemingly small rule may be connected to several behaviors across the application. Without tests, this connection is usually discovered only after something breaks.

The role of automated tests is to anticipate part of that discovery.

On the frontend, for example, tools such as Jest, Vitest, and Testing Library help validate the behavior of components. In React, Vue, or Angular applications, it is possible to verify whether a screen still renders correctly, whether a button still triggers the expected action, whether an error message appears when the user fills in an invalid field, or whether a component reacts correctly to a state change.

This type of test does not exist only to verify whether the code “works.” It exists to protect the user experience.

Imagine a registration screen where the user needs to fill in name, email, and password. Visually, everything may look correct. But if a change in the component breaks email validation or prevents the form from being submitted, the problem can easily go unnoticed during a rushed manual validation. An automated test reduces that risk because it turns the expected behavior into something that can be verified.

A simple example in React could look like this:

import { render, screen, fireEvent } from '@testing-library/react';
import RegisterForm from './RegisterForm';

test('exibe mensagem de erro quando o e-mail é inválido', () => {
  render(<RegisterForm />);
  fireEvent.change(screen.getByLabelText('E-mail'), {
    target: { value: 'email-invalido' }
  });
  fireEvent.click(screen.getByText('Cadastrar'));
  expect(screen.getByText('Informe um e-mail válido')).toBeInTheDocument();
});

This test is not concerned with the internal implementation of the component. It is concerned with the behavior perceived by the user. The user entered an invalid email, clicked register, and expects to receive an appropriate message. If someone changes this form tomorrow and breaks that validation, the test exposes the problem before it reaches production.

That is the difference between testing code and testing behavior.

Tools such as Cypress and Playwright expand this view because they allow complete navigation flows to be tested. Instead of validating only an isolated component, you can simulate the real user journey inside the system. Login, order creation, payment, report generation, customer registration, form submission, or any other critical flow.

This kind of test is especially important in digital products that depend on a continuous experience. A system may have a backend working correctly, but if the user cannot complete the action in the interface, the problem is real. For the end customer, it does not matter whether the API responded correctly. What matters is whether they were able to use the product.

On the backend, the logic changes slightly. The focus moves away from visual interaction and toward the consistency of business rules. Tools such as xUnit and NUnit in the .NET ecosystem, PyTest in Python, Mocha or Jest in Node.js, PHPUnit in PHP, and JUnit in Java are used to validate internal application behavior.

Here, tests protect the heart of the system.

If a commission rule, tax calculation, credit approval, order creation, or permission validation is critical to the business, it should not depend only on manual testing. There should be an automated way to ensure that this rule continues to work after every change.

A simple backend example could be an order rule:

describe('OrderService', () => {
  it('deve criar um pedido com status pendente quando os dados forem válidos', async () => {
    const payload = {
      customerId: 10,
      items: [
        { productId: 1, quantity: 2, price: 100 }
      ]
    };
    const order = await OrderService.create(payload);
      expect(order.status).toBe('pending');
      expect(order.total).toBe(200);
    });
});

This test validates an essential rule: when an order is created with valid data, the system must calculate the total correctly and initialize the order with the expected status. It looks simple, but this is exactly the kind of behavior that sustains trust in a system.

When rules like this are not tested, the company starts depending on informal validation. Someone needs to remember to test the order, remember to check the total, remember to validate the status, and remember to verify indirect impacts. This model does not scale, because the larger the system becomes, the more things someone needs to remember.

And human memory is not architecture.

There is also an important difference between types of tests. Unit tests validate small units of behavior, such as functions, methods, or classes. Integration tests validate whether different parts of the system work correctly together, such as an API communicating with a database or one service calling another. End-to-end tests validate complete flows, simulating the real behavior of a user or a process from beginning to end.

Each layer has a purpose.

Unit tests are fast and help locate problems with precision. Integration tests increase confidence in the communication between components. End-to-end tests provide a view closer to the user’s reality. The common mistake is trying to solve everything with only one type of test.

A mature system usually combines these layers. Not because it looks beautiful from a technical standpoint, but because each one protects a different part of the risk.

When a company does not have this structure, growth starts producing side effects. The team spends more time validating than building. Small changes start generating fear. Old bugs reappear. Features that were working stop working after apparently unrelated changes. The customer begins to notice instability. The business starts losing confidence in the technical team.

And when the business loses confidence in the technical team, the entire evolution process becomes compromised.

This is where many companies confuse speed with haste. To deliver faster, they cut tests. To reduce deadlines, they remove validations. To meet a date, they push risk into production. The delivery may happen, but the bill comes later.

It comes as rework, incidents, emergency meetings, unhappy customers, and loss of predictability.

Automated tests do not prevent all errors from happening. That expectation is unrealistic. Their role is to reduce the chances of predictable errors reaching places where they should never arrive. They act as a safety net for the system, allowing the team to move with more confidence.

This point matters because there is still cultural resistance in many companies. Testing is often seen as a cost, as something that slows development down, as a step that can be left for later. The problem is that “later” almost never comes. And when it does, the system is already large, coupled, full of invisible rules, and too expensive to test easily.

The later a company starts building a testing culture, the harder it becomes.

Not because the tools are complex, but because the system was built without that concern. Code without clear separation of responsibilities is hard to test. Business rules mixed with interface logic are hard to validate. Overly coupled services require too much effort to isolate. Poorly organized external dependencies make tests unstable and unreliable.

That is why automated tests should not be seen only as a quality practice. They reflect the architecture of the system itself.

A testable system is usually a better organized system. To test well, you need to separate responsibilities, reduce coupling, make business rules clearer, and create consistent validation points. In other words, the search for better tests often leads to better code.

This is a benefit many people ignore.

When a team starts writing tests, it begins to notice design problems. Functions that are too large, classes that do too much, hidden dependencies, duplicated rules, implicit behaviors. Testing exposes the mess. And at first, this can be uncomfortable.

But it is a necessary discomfort.

In systems that need to scale, the discomfort of organizing now is smaller than the cost of fixing later. A company can survive for some time without automated tests, especially if the system is still small. But as the operation grows, the absence of this foundation becomes a real limitation.

There comes a moment when the company wants to evolve, but the system cannot keep up. It wants to launch features, but every change generates instability. It wants to hire more developers, but new people take too long to understand the impact of what they are changing. It wants to move faster, but the technical foundation itself pulls the brake.

At that point, the problem is no longer just technical. It starts affecting the company’s ability to execute.

A system without tests may look cheaper in the beginning, but it usually becomes more expensive in the long run. The cost does not appear only in the code. It appears in operations, support, customer service, customer trust, and the company’s ability to respond to the market.

When a competitor can release features safely while your company needs weeks of manual validation to change a rule, the difference is not only the size of the team. It is the maturity of the process.

Automated tests are part of that maturity.

They are not the only pillar, but they are one of the most important. Without them, CI/CD loses strength because the pipeline has no meaningful validations to execute. Without them, continuous deployment becomes just risk automation. Without them, refactoring becomes fear. Without them, maintenance becomes trial and error.

This connection is fundamental. Tests do not live in isolation. They support other modern engineering practices. A continuous delivery pipeline only makes sense when there is a reliable validation base. An evolvable architecture only holds when there is confidence to change. A culture of continuous improvement only works when the team can measure the impact of changes.

Without tests, all of this becomes fragile.

There is also a human aspect to this topic. Developers work better when they feel safe changing the system. When every change generates fear, the team becomes conservative. People avoid improvements, postpone refactorings, and learn to live with known problems because changing them feels too dangerous.

This slowly kills evolution.

A good automated test suite does not only protect the system. It protects the team’s ability to improve the system. It allows developers to change, refactor, reorganize, and evolve with more confidence. This changes the rhythm of work.

The difference is noticeable.

In an environment without tests, deployments are usually followed by tension. In an environment with good test coverage, deployment still requires responsibility, but it no longer depends exclusively on hope. The company starts having a more reliable process.

And a reliable process is one of the foundations of scale.

When we talk about scale, many people immediately think about infrastructure. Servers, Kubernetes, distributed databases, caching, queues, and load balancing. All of this can be important, but none of it solves a basic problem: if the company cannot safely change the system, it cannot scale sustainably.

Scale is not only about supporting more users. Scale is about supporting more users, more rules, more changes, and more people working on the same product without turning every delivery into a risk.

Automated tests help exactly at this point. They create a language of trust between code, team, and business. Expected behavior stops living only in people’s heads and becomes documented in executable form.

This is one of the strongest forms of documentation because it does not merely describe what the system should do. It verifies that the system still does it.

And that changes everything.

Because no one tests everything manually forever.

At some point, the volume becomes too large. The complexity becomes too high. The risk becomes too expensive.

And when that moment comes, the company discovers that the problem was not only a lack of tests. It was a lack of structure to grow.

Automated tests do not guarantee the success of a system, but their absence greatly increases the chances of operational failure. They do not replace good developers, but they amplify good teams. They do not eliminate bugs, but they reduce the surface of risk. They do not solve every architectural problem, but they expose many of them before they become too invisible.

That is why, when someone says automated tests “slow the project down,” perhaps the right question is different.

Slow it down compared to what?

Compared to a rushed delivery that will generate rework later? Compared to a deployment made with fear? Compared to a feature released without confidence? Compared to a system that grows without a foundation and later requires months of correction?

There is a huge difference between speed and haste.

Speed is delivering with consistency. Haste is pushing risk forward.

Mature companies understand this difference.

And companies that intend to scale need to understand it before the system itself teaches the lesson in the worst possible way.

Without automated tests, your company may still be able to deliver software for some time. It may even grow in number of users, features, and customers. But as complexity increases, the absence of this foundation starts charging its price.

First, in the team’s speed. Then, in product stability. Eventually, in the trust of the business.

And when trust disappears, the system stops being a growth engine and becomes a permanent source of risk.

Automated tests are not a luxury. They are not a detail. They are not a concern only for large companies.

They are one of the first signs that a company takes its product seriously.

Because software that grows without tests is not scaling.

It is only accumulating risk in silence.

The question that remains is simple: is your company using automated tests as part of its growth strategy, or is it still treating manual validation as a process? 🚀