> ## 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. # Acerca de la observabilidad > Entiende cómo la telemetría — métricas, logs y trazas — fluye por Midaz para monitorear el rendimiento y resolver incidentes. La observabilidad es cómo entendemos lo que está sucediendo dentro de un sistema mediante el análisis de sus salidas: métricas, logs y trazas. Esta página explica cómo fluye la telemetría a través de **Midaz**, las herramientas que lo impulsan y cómo puedes conectar tus propios sistemas para monitorear el rendimiento, solucionar problemas y garantizar la excelencia operativa. ## ¿Quién configura qué? *** Para evitar confusiones, aquí hay una división rápida de responsabilidades: ### Lado del cliente En tu infraestructura, la configuración principal para la observabilidad se encuentra en el archivo `components/infra/grafana/otelcol-config.yaml`. En este archivo, defines el comportamiento del recolector: * **Procesadores**: agrupamiento, límites de memoria, filtrado, ofuscación, muestreo, etc. * **Exportadores**: por ejemplo, enrutamiento dual a Prometheus * **Secretos de autenticación de clave API** Después de editar este archivo, **debes** reiniciar el stack con `make down && make up` para que los cambios surtan efecto. Esta configuración garantiza que la telemetría se procese de manera eficiente, se asegure adecuadamente y se enrute a los destinos correctos. ### Lado de Lerian En la infraestructura administrada de Lerian, el stack de observabilidad está configurado y operado centralmente. Esto incluye: * **Recolector Central** * **Prometheus** * **Loki** * **Tempo** * **Grafana** Estos componentes están preconfigurados y mantenidos por Lerian. No los editas directamente. Esto garantiza consistencia en todos los entornos y elimina la necesidad de mantenimiento local de tu parte. ## Cómo fluyen los datos *** Los datos de telemetría se originan en tu aplicación y fluyen a través de un **Recolector del Cliente**, impulsado por [OpenTelemetry](https://opentelemetry.io/). Ejecutándose en tu entorno, este recolector enriquece los datos y los reenvía de manera segura a un **Recolector Central** administrado por Lerian. Desde allí, se enruta a tres 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 trazas Grafana se sitúa sobre todo, brindándote una vista unificada de todas las señales de telemetría. Este flujo garantiza observabilidad a escala, basada en estándares de OpenTelemetry para portabilidad y consistencia. ## Componentes del stack *** Juntos, estos componentes forman un pipeline completo de observabilidad: flexible de tu lado, consistente y seguro del lado de Lerian, y totalmente basado en **estándares de OpenTelemetry**. #### Recolector del Cliente El Recolector del Cliente es un [Recolector OpenTelemetry](https://opentelemetry.io/docs/collector/) ligero que se ejecuta cerca de tu aplicación, ya sea como un DaemonSet o un Deployment. Enriquece la telemetría con metadatos de Kubernetes y tu identificador de tenant (`client_id`), luego enruta los datos al Recolector Central. Es importante porque reduce la carga en el pipeline central, habilita el filtrado a nivel de fuente y adjunta metadatos cruciales como `k8s.pod.name`. La instalación se gestiona mediante Helm y Terraform, facilitando la integración en tu infraestructura. #### Recolector Central El Recolector Central es un despliegue centralizado del [Recolector OpenTelemetry](https://opentelemetry.io/docs/collector/) que recibe telemetría de todos los clientes. Realiza procesamiento global, aplica multi-tenancy y exporta señales a los backends de almacenamiento apropiados. El Recolector Central está completamente administrado por Lerian. No lo configuras ni modificas directamente. Esta configuración garantiza consistencia entre tenants y asegura que los datos de telemetría se enruten de manera segura y eficiente a sus destinos finales. #### Prometheus Prometheus está optimizado para almacenar y consultar datos de series temporales numéricas. El Recolector Central envía métricas usando `remote_write`. #### Loki Loki almacena logs utilizando indexación basada en etiquetas, haciéndolo rápido y rentable. Los logs se envían desde el Recolector Central al servicio `loki-write`. #### Tempo Tempo almacena trazas distribuidas completas y se integra estrechamente con Prometheus y Loki a través de Grafana. #### Grafana Grafana es tu panel único de control. Se conecta a Prometheus, Loki y Tempo, permitiéndote correlacionar métricas, logs y trazas en un solo lugar. Puedes pivotar entre métricas, logs y trazas directamente dentro de Grafana para acelerar la resolución de problemas. ## Recolector Integrado *** Puedes habilitar el Recolector del Cliente como una dependencia de tu aplicación Midaz con un solo flag de configuración: ``` otel-collector-lerian: enabled:true ``` Esto instala automáticamente un DaemonSet y configura tu aplicación para exportar telemetría a él. Las variables de entorno y secretos requeridos se inyectan mediante Helm, por lo que no necesitas gestionarlos manualmente. ## Editando el Recolector del Cliente *** Cuando necesites personalizar el comportamiento (ofuscación, filtrado, muestreo, etc.), deberás: 1. Editar `components/infra/grafana/otelcol-config.yaml`. 2. Agregar o ajustar los bloques `processors` o `exporters`. 3. Reiniciar el stack: ``` make down make up ``` ## Procesadores del Recolector del Cliente *** En el Recolector OpenTelemetry, los **procesadores** son el núcleo de la manipulación de datos. Se ejecutan secuencialmente para enriquecer, filtrar, muestrear y transformar datos de telemetría antes de exportarlos a los backends. A continuación se muestra la lista de procesadores configurados en el **Recolector del Cliente de Lerian**, su propósito y cómo configurarlos. **Dónde configurar**: agrega cada bloque bajo `processors:` en `otelcol-config.yaml`. **1. batch** * **Qué es:** Agrupa múltiples señales de telemetría (métricas, logs o trazas) en lotes antes de enviarlas a la siguiente etapa. * **Por qué importa:** Mejora la eficiencia de compresión, reduce las solicitudes de red y mejora el rendimiento general del pipeline. * **Configuración:** ``` processors: batch: {} ``` **2. memory\_limiter** * **Qué es:** Monitorea el uso de memoria del recolector y descarta datos si se acerca a un umbral definido. * **Por qué importa:** Previene que el recolector sea terminado por OOMKilled por Kubernetes. * **Configuración:** ``` processors: memory_limiter: check_interval: 1s limit_percentage: 75 spike_limit_percentage: 15 ``` **3. spanmetrics** * **Qué es:** Genera métricas directamente de los datos de traza. * **Por qué importa:** Produce métricas "RED" (Rate, Errors, Duration) automáticamente. * **Configuración:** ``` processors: spanmetrics: metrics_exporter: prometheus dimensions: - name: http.method - name: http.status_code - name: service.name - name: client.id ``` **4. transform/remove\_sensitive\_attributes** * **Qué es:** Elimina atributos de span sensibles usando regex. * **Por qué importa:** Mantiene identificadores, pero elimina encabezados, cuerpos u otros datos sensibles de solicitud. * **Configuración:** ``` processors: transform/remove_sensitive_attributes: trace_statements: - context: span statements: - delete_matching_keys(attributes, "^app\\.request\\.(?!request_id$).*") ``` **5. tail\_sampling** * **Qué es:** Una estrategia de muestreo aplicada después de que se reciben los spans. * **Por qué importa:** Mantiene solo trazas de alto valor (errores, clientes específicos) y reduce los costos de almacenamiento. * **Configuración:** ``` 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** * **Qué es:** Filtra métricas a nivel de nodo. * **Por qué importa:** Reduce el ruido y se enfoca en la telemetría a nivel de aplicación. * **Configuración:** ``` processors: filter/drop_node_metrics: metrics: exclude: match_type: regexp metric_names: - ^k8s\\.node\\..*$ ``` **7. filter/include\_midaz\_namespaces** * **Qué es:** Mantiene solo métricas de `midaz` y `midaz-plugins`. * **Por qué importa:** Elimina cargas de trabajo irrelevantes de Kubernetes. * **Configuración:** ``` processors: filter/include_midaz_namespaces: metrics: include: match_type: regexp resource_attributes: - key: k8s.namespace.name value: '^(midaz|midaz-plugins)$' ``` **8. k8sattributes** * **Qué es:** Agrega metadatos de Kubernetes a la telemetría. * **Por qué importa:** Habilita un contexto más rico en las consultas de Grafana. * **Configuración:** ``` 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** * **Qué es:** Inserta o actualiza `client.id` en la telemetría. * **Por qué importa:** Crítico para multi-tenancy. * **Configuración:** ``` processors: resource/add_client_id: attributes: - key: client.id value: "example-client" action: upsert ``` **10. transform/remove\_log\_body** * **Qué es:** Elimina el contenido del cuerpo del log. * **Por qué importa:** Previene que datos sensibles o PII persistan en los logs. * **Configuración:** ``` processors: transform/remove_log_body: log_statements: - context: log statements: - set(body, "") ``` **11. transform/obfuscate\_attributes** * **Qué es:** Ofusca atributos seleccionados. * **Por qué importa:** Protege valores sensibles (como `legalDocument` o `accountAlias`) antes de que los datos salgan de tu clúster. * **Configuración (**`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 los campos:** * Por defecto: `legalDocument`, `accountAlias` * Agrega o elimina campos según sea necesario * Reinicio requerido: `make down && make up` ### En resumen | Procesador | Tipo de datos | Función | Beneficio | | :------------------------------------------ | :--------------------- | :---------------------------------------------------- | :------------------------------------------------- | | **batch** | Métricas, Logs, Trazas | Agrupa telemetría antes de exportar | Mejora compresión y uso de red | | **memory\_limiter** | Métricas, Logs, Trazas | Descarta datos cuando el límite de memoria está cerca | Previene OOMKilled | | **spanmetrics** | Trazas → Métricas | Crea métricas RED | Insights inmediatos de rendimiento | | **transform/remove\_sensitive\_attributes** | Trazas | Elimina atributos de span sensibles | Mantiene IDs, elimina secretos | | **tail\_sampling** | Trazas | Muestreo inteligente de trazas | Menor almacenamiento, enfoque en errores/objetivos | | **filter/drop\_node\_metrics** | Métricas | Excluye datos ruidosos a nivel de nodo | Dataset más limpio | | **filter/include\_midaz\_namespaces** | Métricas | Mantiene solo namespaces de Midaz | Elimina métricas irrelevantes | | **k8sattributes** | Métricas, Logs, Trazas | Agrega metadatos de K8s | Contexto más rico en Grafana | | **resource/add\_client\_id** | Todas las señales | Etiqueta telemetría con ID de cliente | Habilita multi-tenancy | | **transform/remove\_log\_body** | Logs | Limpia el cuerpo del log | Evita almacenar PII | | **transform/obfuscate\_attributes** | Todas las señales | Enmascara campos elegidos | Asegura que datos sensibles nunca salgan | ## Protegiendo datos sensibles *** Midaz trata al **Recolector del Cliente como un firewall de telemetría**. Todas las reglas de filtrado, muestreo y transformación están definidas en tu archivo de configuración (`components/infra/grafana/otelcol-config.yaml`). Observability Client Leria Jp Este archivo se ejecuta dentro de **tu infraestructura**, asegurando que los atributos sensibles se eliminen u ofusquen *antes* de que los datos salgan de tu clúster. Valores sensibles como cuerpos de solicitud, documentos legales o alias de cuenta nunca llegan al Recolector Central de Lerian. Nuestra arquitectura aplica esta separación: * **Recolector del Cliente (tú configuras):** Se ejecuta en tu clúster. Aplica procesadores como `transform/remove_sensitive_attributes`, `transform/remove_log_body` y `transform/obfuscate_attributes`. * **Recolector Central (administrado por Lerian):** Recibe solo los flujos de telemetría filtrados y sanitizados y los enruta a Prometheus, Loki y Tempo. Las configuraciones están completamente empaquetadas y administradas mediante Helm, manteniendo los despliegues consistentes, rastreables y alineados con las mejores prácticas. Tú decides qué es sensible en `otelcol-config.yaml`. Lerian solo ve telemetría sanitizada. ## Flujo de telemetría *** Esto es lo que sucede cuando la telemetría está habilitada: 1. **La aplicación inicia** y detecta la configuración de OpenTelemetry. 2. **La telemetría se exporta** al recolector del cliente local. 3. **El Recolector del Cliente enriquece los datos** con metadatos de Kubernetes y tu `client_id`. 4. **Los procesadores enriquecen**, filtran y transforman los datos. 5. **Los datos se reenvían** al recolector central. 6. **El Recolector Central procesa y enruta los datos**: * Métricas → Prometheus * Logs → Loki * Trazas → Tempo 7. **Grafana te permite consultarlo todo**, correlacionando entre señales. Puedes, por ejemplo, ejecutar: ``` sum(rate(http_server_duration_seconds_count{ k8s_pod_name=~"checkout-.*", client_id="client-name" }[5m])) ``` Y luego saltar directamente a los logs o trazas relacionados. ## Autenticando solicitudes del recolector *** Para garantizar la seguridad e integridad de los datos, toda la telemetría enviada desde tu clúster a la plataforma de Lerian debe autenticarse utilizando una clave API segura. ### Cómo configurarlo 1. **Crea el Secret de Kubernetes** para almacenar tu token API: ``` kubectl create secret generic otel-api-key \ --from-literal=OTEL_API_KEY='YOUR_TOKEN_HERE' \ -n midaz ``` 2. **Referencia el secret en tu archivo de valores de Helm** para inyectarlo como una variable de entorno: ``` extraEnvs: - name: OTEL_API_KEY valueFrom: secretKeyRef: name: otel-api-key key: OTEL_API_KEY ``` 3. **La telemetría se envía de forma segura** al endpoint de telemetría de Lerian sobre HTTPS, con la clave API incluida en los encabezados. ``` ``` Esta clave debe permanecer privada. Si se ve comprometida, contacta al soporte de Lerian inmediatamente para rotar el token. ## Cifrado de datos en tránsito *** Todos los datos de telemetría, incluidas métricas, logs y trazas, se transmiten desde tu entorno a la plataforma de observabilidad de Lerian usando **HTTPS con cifrado TLS**. Esto significa: * La comunicación entre el Recolector del Cliente y el Recolector Central está completamente cifrada. * Los datos en tránsito están protegidos contra interceptación, manipulación o acceso no autorizado. * Incluso si se inspecciona el tráfico de red, el contenido permanece ilegible sin las claves criptográficas apropiadas. Combinado con la autenticación por clave API, esto garantiza que tu telemetría sea tanto **segura como verificable** desde el origen hasta el destino. Aplicamos transporte cifrado por defecto. No se aceptan datos por canales inseguros. ## Enrutamiento dual *** ¿Necesitas mantener una copia de tus métricas internamente? Puedes configurar el Recolector del Cliente para enviar telemetría a múltiples destinos. ### Ejemplo ``` exporters: otlphttp/server: endpoint: "" headers: x-api-key: "${OTEL_API_KEY}" prometheus/local: endpoint: prometheus-server-example:8889 ``` Agrega ambos exportadores a tu pipeline de métricas, y las mismas métricas se enviarán a nuestra plataforma y a tu Prometheus interno. Esta configuración es ideal para el monitoreo local sin interrumpir el flujo estándar al stack de observabilidad de Lerian. ## Glosario *** Un tipo de carga de trabajo de Kubernetes que garantiza que un Pod se ejecute en cada nodo (o nodos seleccionados) en un clúster. Se usa para desplegar el **Recolector del Cliente**, para que pueda recopilar datos a nivel de nodo como métricas de Kubelet. Una carga de trabajo de Kubernetes que gestiona réplicas de un Pod. Se usa para el **Recolector Central** y otros servicios de la plataforma. Envía datos de telemetría desde el recolector a uno o más backends (p. ej., Prometheus para métricas, Loki para logs, Tempo para trazas). Una capa de visualización de código abierto. Grafana se conecta a Prometheus, Loki y Tempo para proporcionar una interfaz unificada para consultar y explorar métricas, logs y trazas. Nuestro backend para **logs**. Loki indexa etiquetas de metadatos en lugar del contenido completo del log, haciéndolo rápido y rentable para casos de uso de alto volumen. Un enfoque arquitectónico donde una sola plataforma sirve a múltiples clientes (tenants). En Midaz, los datos de telemetría se etiquetan con un `client_id` para garantizar aislamiento y trazabilidad entre tenants. La capacidad de comprender el estado interno de un sistema mediante el análisis de sus salidas externas. En la práctica, significa recopilar y analizar **métricas**, **logs** y **trazas** para monitorear el rendimiento y solucionar problemas. Un framework de código abierto con herramientas, APIs y SDKs para instrumentar, generar, recopilar y exportar datos de telemetría: métricas, logs y trazas. Un servicio independiente que recibe, procesa y exporta datos de telemetría. Actúa como un puente entre aplicaciones instrumentadas y backends como Prometheus o Grafana. El protocolo predeterminado utilizado por OpenTelemetry para transportar datos de telemetría entre aplicaciones, recolectores y backends mediante gRPC o HTTP. Define cómo fluye la telemetría a través del Recolector. Un pipeline típicamente encadena **receivers**, **processors** y **exporters** para un tipo de señal dado (métricas, logs o trazas). Maneja la transformación de datos dentro del Recolector, como enriquecer señales con metadatos, filtrar datos no deseados, agrupar mensajes o aplicar políticas de muestreo. Nuestro backend para almacenar y consultar **métricas**. Admite poderosas consultas de series temporales (PromQL) y se integra con el Recolector OpenTelemetry mediante escritura remota. El componente del Recolector que ingiere datos de telemetría entrantes. Admite formatos como OTLP, Jaeger, Prometheus y otros. Un conjunto de bibliotecas que incorporas en el código de tu aplicación para producir señales de telemetría como spans, contadores o logs. Nuestro backend para **trazas**. Almacena trazas distribuidas completas y se integra estrechamente con Prometheus y Loki para una correlación fluida en Grafana. Una herramienta de Infraestructura como Código (IaC) que usamos para aprovisionar y gestionar infraestructura en la nube, incluida la instalación de componentes de observabilidad mediante Helm.