> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Sobre Observabilidade > Entenda como a telemetria — métricas, logs e traces — flui pelo Midaz para monitorar performance e resolver incidentes. Observabilidade é como entendemos o que está acontecendo dentro de um sistema analisando suas saídas: métricas, logs e traces. Esta página explica como a telemetria flui através do **Midaz**, as ferramentas que a alimentam e como você pode conectar seus próprios sistemas para monitorar performance, solucionar problemas e garantir excelência operacional. ## Quem configura o quê? *** Para evitar confusão, aqui está uma divisão rápida de responsabilidades: ### Lado do cliente Na sua infraestrutura, a configuração principal para observabilidade está no arquivo `components/infra/grafana/otelcol-config.yaml`. Neste arquivo, você define o comportamento do collector: * **Processors**: batching, limites de memória, filtragem, ofuscação, sampling, etc. * **Exporters**: por exemplo, roteamento duplo para Prometheus * **Secrets de autenticação de API key** Após editar este arquivo, você **deve** reiniciar o stack com `make down && make up` para que as alterações tenham efeito. Esta configuração garante que a telemetria seja processada de forma eficiente, protegida adequadamente e roteada para os destinos corretos. ### Lado da Lerian Na infraestrutura gerenciada pela Lerian, o stack de observabilidade é configurado e operado centralmente. Isso inclui: * **Central Collector** * **Prometheus** * **Loki** * **Tempo** * **Grafana** Esses componentes são pré-configurados e mantidos pela Lerian. Você não os edita diretamente. Isso garante consistência entre ambientes e remove a necessidade de manutenção local do seu lado. ## Como os dados fluem *** Os dados de telemetria originam-se na sua aplicação e fluem através de um **Client Collector**, alimentado pelo [OpenTelemetry](https://opentelemetry.io/). Rodando no seu ambiente, este collector enriquece os dados e os encaminha com segurança para um **Central Collector** gerenciado pela Lerian. De lá, são roteados para três backends especializados: * [**Prometheus**](https://grafana.com/oss/prometheus/) para métricas * [**Loki**](https://grafana.com/oss/loki) para logs * [**Tempo**](https://grafana.com/oss/tempo) para traces O Grafana fica no topo de tudo, dando a você uma visão unificada de todos os sinais de telemetria. Este fluxo garante observabilidade em escala, construído sobre padrões OpenTelemetry para portabilidade e consistência. ## Componentes do stack *** Juntos, esses componentes formam um pipeline de observabilidade completo: flexível do seu lado, consistente e seguro do lado da Lerian, e totalmente baseado em **padrões OpenTelemetry**. #### Client Collector O Client Collector é um [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) leve que roda próximo à sua aplicação, seja como DaemonSet ou Deployment. Ele enriquece a telemetria com metadados do Kubernetes e seu identificador de tenant (`client_id`), então roteia os dados para o Central Collector. É importante porque reduz a carga no pipeline central, permite filtragem na origem e anexa metadados cruciais como `k8s.pod.name`. A instalação é gerenciada via Helm e Terraform, facilitando a integração na sua infraestrutura. #### Central Collector O Central Collector é um deployment centralizado do [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) que recebe telemetria de todos os clientes. Ele realiza processamento global, aplica multi-tenancy e exporta sinais para os backends de armazenamento apropriados. O Central Collector é totalmente gerenciado pela Lerian. Você não o configura ou modifica diretamente. Esta configuração garante consistência entre tenants e garante que os dados de telemetria sejam roteados de forma segura e eficiente para seus destinos finais. #### Prometheus O Prometheus é otimizado para armazenar e consultar dados numéricos de séries temporais. O Central Collector envia métricas usando `remote_write`. #### Loki O Loki armazena logs usando indexação baseada em labels, tornando-o rápido e econômico. Os logs são enviados do Central Collector para o serviço `loki-write`. #### Tempo O Tempo armazena traces distribuídos completos e se integra fortemente com Prometheus e Loki através do Grafana. #### Grafana O Grafana é seu painel único de visualização. Ele se conecta ao Prometheus, Loki e Tempo, permitindo que você correlacione métricas, logs e traces em um só lugar. Você pode alternar entre métricas, logs e traces diretamente no Grafana para acelerar a solução de problemas. ## Embedded Collector *** Você pode habilitar o Client Collector como uma dependência da sua aplicação Midaz com uma única flag de configuração: ``` otel-collector-lerian: enabled:true ``` Isso instala automaticamente um DaemonSet e configura sua aplicação para exportar telemetria para ele. As variáveis de ambiente e secrets necessários são injetados via Helm, então você não precisa gerenciá-los manualmente. ## Editando o Client Collector *** Quando você precisa personalizar o comportamento (ofuscação, filtragem, sampling, etc.), você irá: 1. Editar `components/infra/grafana/otelcol-config.yaml`. 2. Adicionar ou ajustar os blocos de `processors` ou `exporters`. 3. Reiniciar o stack: ``` make down make up ``` ## Processors do Client Collector *** No OpenTelemetry Collector, os **processors** são o núcleo da manipulação de dados. Eles rodam sequencialmente para enriquecer, filtrar, amostrar e transformar dados de telemetria antes de exportá-los para os backends. Abaixo está a lista de processors configurados no **Lerian Client Collector**, seu propósito e como configurá-los. **Onde configurar**: adicione cada bloco em `processors:` no `otelcol-config.yaml`. **1. batch** * **O que é:** Agrupa múltiplos sinais de telemetria (métricas, logs ou traces) em lotes antes de enviá-los para a próxima etapa. * **Por que é importante:** Melhora a eficiência de compressão, reduz requisições de rede e melhora a performance geral do pipeline. * **Configuração:** ``` processors: batch: {} ``` **2. memory\_limiter** * **O que é:** Monitora o uso de memória do collector e descarta dados se ele se aproximar de um limite definido. * **Por que é importante:** Previne que o collector seja OOMKilled pelo Kubernetes. * **Configuração:** ``` processors: memory_limiter: check_interval: 1s limit_percentage: 75 spike_limit_percentage: 15 ``` **3. spanmetrics** * **O que é:** Gera métricas diretamente dos dados de trace. * **Por que é importante:** Produz métricas "RED" (Rate, Errors, Duration) automaticamente. * **Configuração:** ``` processors: spanmetrics: metrics_exporter: prometheus dimensions: - name: http.method - name: http.status_code - name: service.name - name: client.id ``` **4. transform/remove\_sensitive\_attributes** * **O que é:** Remove atributos sensíveis de span usando regex. * **Por que é importante:** Mantém identificadores mas remove headers, bodies ou outros dados sensíveis da requisição. * **Configuração:** ``` processors: transform/remove_sensitive_attributes: trace_statements: - context: span statements: - delete_matching_keys(attributes, "^app\\.request\\.(?!request_id$).*") ``` **5. tail\_sampling** * **O que é:** Uma estratégia de sampling aplicada após os spans serem recebidos. * **Por que é importante:** Mantém apenas traces de alto valor (erros, clientes específicos) e reduz custos de armazenamento. * **Configuração:** ``` processors: tail_sampling: policies: - name: keep_client_traces_policy - name: http_server_errors_policy - name: drop_all_other_traces_policy ``` **6. filter/drop\_node\_metrics** * **O que é:** Filtra métricas de nível de node. * **Por que é importante:** Reduz ruído e foca em telemetria de nível de aplicação. * **Configuração:** ``` processors: filter/drop_node_metrics: metrics: exclude: match_type: regexp metric_names: - ^k8s\\.node\\..*$ ``` **7. filter/include\_midaz\_namespaces** * **O que é:** Mantém apenas métricas de `midaz` e `midaz-plugins`. * **Por que é importante:** Elimina workloads Kubernetes irrelevantes. * **Configuração:** ``` processors: filter/include_midaz_namespaces: metrics: include: match_type: regexp resource_attributes: - key: k8s.namespace.name value: '^(midaz|midaz-plugins)$' ``` **8. k8sattributes** * **O que é:** Adiciona metadados do Kubernetes à telemetria. * **Por que é importante:** Permite contexto mais rico nas consultas do Grafana. * **Configuração:** ``` processors: k8sattributes: auth_type: "serviceAccount" passthrough: false extract: metadata: - k8s.pod.name - k8s.deployment.name - k8s.namespace.name - k8s.node.name ``` **9. resource/add\_client\_id** * **O que é:** Insere ou atualiza `client.id` na telemetria. * **Por que é importante:** Crítico para multi-tenancy. * **Configuração:** ``` processors: resource/add_client_id: attributes: - key: client.id value: "example-client" action: upsert ``` **10. transform/remove\_log\_body** * **O que é:** Remove o conteúdo do body do log. * **Por que é importante:** Previne que dados sensíveis ou PII persistam nos logs. * **Configuração:** ``` processors: transform/remove_log_body: log_statements: - context: log statements: - set(body, "") ``` **11. transform/obfuscate\_attributes** * **O que é:** Ofusca atributos selecionados. * **Por que é importante:** Protege valores sensíveis (como `legalDocument` ou `accountAlias`) antes que os dados deixem seu cluster. * **Configuração (**`otelcol-config.yaml`**):** ``` processors: transform/obfuscate_attributes: trace_statements: - context: span statements: - replace_pattern(attributes["legalDocument"], ".*", "***") - replace_pattern(attributes["accountAlias"], ".*", "***") log_statements: - context: log statements: - replace_pattern(attributes["legalDocument"], ".*", "***") - replace_pattern(attributes["accountAlias"], ".*", "***") ``` * **Personalizando os campos:** * Padrões: `legalDocument`, `accountAlias` * Adicione ou remova campos conforme necessário * Reinicialização necessária: `make down && make up` ### Resumo | Processor | Tipo de dado | Função | Benefício | | :------------------------------------------ | :--------------------- | :--------------------------------------------------- | :-------------------------------------- | | **batch** | Métricas, Logs, Traces | Agrupa telemetria antes de exportar | Melhora compressão e uso de rede | | **memory\_limiter** | Métricas, Logs, Traces | Descarta dados quando limite de memória está próximo | Previne OOMKilled | | **spanmetrics** | Traces → Métricas | Cria métricas RED | Insights imediatos de performance | | **transform/remove\_sensitive\_attributes** | Traces | Remove attrs sensíveis de span | Mantém IDs, remove secrets | | **tail\_sampling** | Traces | Sampling inteligente de traces | Menor armazenamento, foco em erros | | **filter/drop\_node\_metrics** | Métricas | Exclui dados ruidosos de nível de node | Dataset mais limpo | | **filter/include\_midaz\_namespaces** | Métricas | Mantém apenas namespaces Midaz | Remove métricas irrelevantes | | **k8sattributes** | Métricas, Logs, Traces | Adiciona metadados K8s | Contexto mais rico no Grafana | | **resource/add\_client\_id** | Todos os sinais | Marca telemetria com client ID | Habilita multi-tenancy | | **transform/remove\_log\_body** | Logs | Limpa body do log | Evita armazenar PII | | **transform/obfuscate\_attributes** | Todos os sinais | Mascara campos escolhidos | Garante que dados sensíveis nunca saiam | ## Protegendo dados sensíveis *** O Midaz trata o **Client Collector como um firewall de telemetria**. Todas as regras de filtragem, sampling e transformação são definidas no seu arquivo de configuração (`components/infra/grafana/otelcol-config.yaml`). Observability Client Leria Jp Este arquivo roda dentro da **sua infraestrutura**, garantindo que atributos sensíveis sejam removidos ou ofuscados *antes* que os dados deixem seu cluster. Valores sensíveis como bodies de requisição, documentos legais ou aliases de conta nunca chegam ao Central Collector da Lerian. Nossa arquitetura aplica essa separação: * **Client Collector (você configura):** Roda no seu cluster. Aplique processors como `transform/remove_sensitive_attributes`, `transform/remove_log_body` e `transform/obfuscate_attributes`. * **Central Collector (gerenciado pela Lerian):** Recebe apenas os streams de telemetria filtrados e sanitizados e os roteia para Prometheus, Loki e Tempo. As configurações são totalmente empacotadas e gerenciadas via Helm, mantendo os deploys consistentes, rastreáveis e alinhados com as melhores práticas. Você decide o que é sensível no `otelcol-config.yaml`. A Lerian só vê a telemetria sanitizada. ## Fluxo de telemetria *** Aqui está o que acontece quando a telemetria está habilitada: 1. **A aplicação inicia** e detecta a configuração do OpenTelemetry. 2. **A telemetria é exportada** para o Client Collector local. 3. **O Client Collector enriquece os dados** com metadados do Kubernetes e seu `client_id`. 4. **Os processors enriquecem**, filtram e transformam os dados. 5. **Os dados são encaminhados** para o Central Collector. 6. **O Central Collector processa e roteia os dados**: * Métricas → Prometheus * Logs → Loki * Traces → Tempo 7. **O Grafana permite que você consulte tudo**, correlacionando entre sinais. Você pode, por exemplo, executar: ``` sum(rate(http_server_duration_seconds_count{ k8s_pod_name=~"checkout-.*", client_id="client-name" }[5m])) ``` E então pular direto para os logs ou traces relacionados. ## Autenticando requisições do collector *** Para garantir segurança e integridade dos dados, toda telemetria enviada do seu cluster para a plataforma da Lerian deve ser autenticada usando uma API key segura. ### Como configurar 1. **Crie o Kubernetes Secret** para armazenar seu token de API: ``` kubectl create secret generic otel-api-key \ --from-literal=OTEL_API_KEY='YOUR_TOKEN_HERE' \ -n midaz ``` 2. **Referencie o secret no seu arquivo de values do Helm** para injetá-lo como variável de ambiente: ``` extraEnvs: - name: OTEL_API_KEY valueFrom: secretKeyRef: name: otel-api-key key: OTEL_API_KEY ``` 3. **A telemetria é enviada com segurança** para o endpoint de telemetria da Lerian via HTTPS, com a API key incluída nos headers. ``` ``` Esta chave deve permanecer privada. Se comprometida, entre em contato com o suporte da Lerian imediatamente para rotacionar o token. ## Criptografia de dados em trânsito *** Todos os dados de telemetria, incluindo métricas, logs e traces, são transmitidos do seu ambiente para a plataforma de observabilidade da Lerian usando **HTTPS com criptografia TLS**. Isso significa: * A comunicação entre o Client Collector e o Central Collector é totalmente criptografada. * Os dados em trânsito são protegidos contra interceptação, adulteração ou acesso não autorizado. * Mesmo se o tráfego de rede for inspecionado, o conteúdo permanece ilegível sem as chaves criptográficas adequadas. Combinado com a autenticação por API key, isso garante que sua telemetria seja **segura e verificável** da origem ao destino. Aplicamos transporte criptografado por padrão. Nenhum dado é aceito por canais inseguros. ## Roteamento duplo *** Precisa manter uma cópia das suas métricas internamente? Você pode configurar o Client Collector para enviar telemetria para múltiplos destinos. ### Exemplo ``` exporters: otlphttp/server: endpoint: "" headers: x-api-key: "${OTEL_API_KEY}" prometheus/local: endpoint: prometheus-server-example:8889 ``` Adicione ambos os exporters ao seu pipeline de métricas, e as mesmas métricas serão enviadas para nossa plataforma e para seu Prometheus interno. Esta configuração é ideal para monitoramento local sem interromper o fluxo padrão para o stack de observabilidade da Lerian. ## Glossário *** Um tipo de workload Kubernetes que garante que um Pod rode em cada (ou em nodes selecionados) node do cluster. Usado para fazer deploy do **Client Collector**, para que ele possa coletar dados de nível de node como métricas do Kubelet. Um workload Kubernetes que gerencia réplicas de um Pod. Usado para o **Central Collector** e outros serviços da plataforma. Envia dados de telemetria do Collector para um ou mais backends (ex.: Prometheus para métricas, Loki para logs, Tempo para traces). Uma camada de visualização de código aberto. O Grafana se conecta ao Prometheus, Loki e Tempo para fornecer uma interface unificada para consultar e explorar métricas, logs e traces. Nosso backend para **logs**. O Loki indexa labels de metadados em vez do conteúdo completo do log, tornando-o rápido e econômico para casos de uso de alto volume. Uma abordagem arquitetural onde uma única plataforma atende múltiplos clientes (tenants). No Midaz, os dados de telemetria são marcados com um `client_id` para garantir isolamento e rastreabilidade entre tenants. A capacidade de entender o estado interno de um sistema analisando suas saídas externas. Na prática, significa coletar e analisar **métricas**, **logs** e **traces** para monitorar performance e solucionar problemas. Um framework de código aberto com ferramentas, APIs e SDKs para instrumentar, gerar, coletar e exportar dados de telemetria — métricas, logs e traces. Um serviço standalone que recebe, processa e exporta dados de telemetria. Ele atua como uma ponte entre aplicações instrumentadas e backends como Prometheus ou Grafana. O protocolo padrão usado pelo OpenTelemetry para transportar dados de telemetria entre aplicações, collectors e backends via gRPC ou HTTP. Define como a telemetria flui através do Collector. Um pipeline tipicamente encadeia **receivers**, **processors** e **exporters** para um determinado tipo de sinal (métricas, logs ou traces). Lida com a transformação de dados dentro do Collector, como enriquecer sinais com metadados, filtrar dados indesejados, agrupar mensagens em lotes ou aplicar políticas de sampling. Nosso backend para armazenar e consultar **métricas**. Ele suporta consultas poderosas de séries temporais (PromQL) e se integra com o OpenTelemetry Collector via remote write. O componente do Collector que ingere dados de telemetria recebidos. Suporta formatos como OTLP, Jaeger, Prometheus e outros. Um conjunto de bibliotecas que você embute no código da sua aplicação para produzir sinais de telemetria como spans, contadores ou logs. Nosso backend para **traces**. Ele armazena traces distribuídos completos e se integra estreitamente com Prometheus e Loki para correlação perfeita no Grafana. Uma ferramenta de Infrastructure as Code (IaC) que usamos para provisionar e gerenciar infraestrutura em nuvem, incluindo a instalação de componentes de observabilidade via Helm.