Unidad 5.1: Observabilidad y depuración
Introducción
TaskBoard se ejecuta en Managed Kubernetes, se implementa mediante CI/CD y se comunica con PostgreSQL, In-Memory DB, Kafka y Object Storage. Luego, un usuario informa de que la lista de tareas es lenta y de que el worker dejó de enviar notificaciones. Necesita respuestas rápidas: qué servicio es lento, qué cambió y a dónde van los paquetes.
Los servicios de Monitoring, Logging y Tracing Service almacenan métricas, registros y trazas, todos visibles en un Grafana gestionado. Funcionan mediante push: usted crea un pipeline y luego dirige un agente o un SDK hacia él. La API de Activity Log registra quién cambió qué, y Flow Logs registran flujos de red. En esta unidad, usted construye esa configuración para TaskBoard como código, y en el Code Lab la utiliza para depurar una interrupción simulada.
1. Métricas con el Monitoring Service
1.1 Aprovisionamiento de una canalización
resource "ionoscloud_monitoring_pipeline" "taskboard" {
location = "de/txl"
name = "taskboard-metrics"
}
output "metrics_push_url" {
value = "${ionoscloud_monitoring_pipeline.taskboard.http_endpoint}/api/v1/push"
}
output "metrics_key" {
value = ionoscloud_monitoring_pipeline.taskboard.key
sensitive = true
}
output "grafana_url" {
value = ionoscloud_monitoring_pipeline.taskboard.grafana_endpoint
}
El recurso solo acepta tokens para la autorización, por lo que debe establecer IONOS_TOKEN. El mismo pipeline a través de la API REST es un POST al host regional:
curl --request POST "https://monitoring.de-txl.ionos.com/pipelines" \
--header "Authorization: Bearer $IONOS_TOKEN" \
--header "Content-Type: application/json" \
--data '{"metadata": {}, "properties": {"name": "taskboard-metrics"}}'
La clave de la canalización se devuelve únicamente en la respuesta de creación y mediante la rotación de claves (POST /pipelines/{pipelineID}/key), lo que invalida la clave anterior. Guárdela de inmediato en su almacén de secretos. Un contrato puede tener hasta 10 canalizaciones de forma predeterminada; IONOS CLOUD Support puede aumentar el límite. Realice consultas periódicas a GET /pipelines/{pipelineID} hasta que metadata.state sea AVAILABLE antes de configurar los agentes.
1.2 Envío de métricas de TaskBoard
El Monitoring Service es de tipo push: Prometheus, Grafana Agent, OpenTelemetry y Fluent Bit envían métricas en formato Prometheus a https://<HTTP_ENDPOINT>/api/v1/push a través del puerto saliente 443. Para un servidor Prometheus en el clúster, agregue un bloque remote_write a prometheus.yml:
remote_write:
- url: "https://<pipeline-id>-metrics.<tenant>.monitoring.de-txl.ionos.com/api/v1/push"
headers:
APIKEY: "<pipeline key>"
El agente envía la clave en la cabecera APIKEY. El intervalo de envío predeterminado es de un minuto, y puede modificarlo. Los colectores de OpenTelemetry también pueden enviar de forma nativa en formato OTLP a <httpEndpoint>/otlp/v1/metrics. Cada punto de datos enviado cuenta para la facturación, por lo que debe descartar las series que no necesite antes de que salgan del clúster.
1.3 Alertas
Las alertas personalizadas se encuentran en Grafana: allí define la condición de la alerta, el umbral y la configuración de notificación. Para la latencia de la API de TaskBoard, configure una alerta en el percentil 95 del histograma de duración de las solicitudes que exporta la API:
histogram_quantile(0.95,
sum by (le) (rate(http_request_duration_seconds_bucket{service="taskboard-api"}[5m]))
) > 0.5
Mantenga la expresión en Git junto al servicio. Para las comprobaciones a nivel de servidor sin ningún agente, consulte la API de Telemetry. Es compatible con Prometheus, de solo lectura, utiliza su token de Cloud API y se pone a disposición una vez que su contrato tenga al menos un canal de observabilidad:
curl --silent --get "https://api.ionos.com/telemetry/api/v1/query" \
--header "Authorization: Bearer $IONOS_TOKEN" \
--data-urlencode "query=instance_cpu_utilization_average > 90"
instance_cpu_utilization_average es un indicador; las otras ocho métricas de la Telemetry API son contadores, por lo que debe envolverlos en rate(). Las métricas llevan el uuid del servidor, no su nombre, por lo que debe resolver los nombres a través de la Cloud API.
2. Registros con Logging Service
2.1 Aprovisionamiento de un canal de datos
resource "ionoscloud_logging_pipeline" "taskboard" {
location = "de/txl"
name = "taskboard-logs"
log {
source = "kubernetes"
tag = "k8s"
protocol = "tcp"
destinations {
type = "loki"
retention_in_days = 14
}
}
}
output "logging_tcp_host" {
value = split(":", ionoscloud_logging_pipeline.taskboard.tcp_address)[0]
}
output "logging_key" {
value = ionoscloud_logging_pipeline.taskboard.key
sensitive = true
}
Cada bloque log es un flujo de registros con un tag único. La retención es de 7, 14 o 30 días por flujo, siendo 30 el valor predeterminado. La clave sigue una política de uso único: no puede recuperarse nuevamente, y generar una nueva con POST /pipelines/{pipelineID}/key revoca la clave anterior de forma inmediata.
La siguiente tabla enumera los límites de Logging Service:
| Aspecto | Descripción | Límite |
|---|---|---|
| Límite de velocidad HTTP | Límite de velocidad predeterminado para solicitudes HTTP por canalización durante la ingesta de registros. | 50 solicitudes/segundo |
| Ancho de banda TCP | Límite de ancho de banda TCP predeterminado por canalización, aproximado en términos de registros por segundo. | ~10.000 registros/segundo |
| Canalizaciones máximas | El número máximo de canalizaciones permitidas por contrato. | 10 canalizaciones |
| Flujos de registros por canalización | El número máximo de flujos de registros permitidos por canalización. | 5 flujos de registros/canalización |
Los registros descartados por el límite de velocidad no se almacenan.
2.2 Reenvío de registros de Cluster desde MKS
Los registros de auditoría de la API de Kubernetes se envían al bucket de Object Storage que configure en el cluster (Unidad 3.2). Para obtener los registros de los pods en Logging Service, ejecute un agente en el cluster, generalmente Fluent Bit como DaemonSet:
[OUTPUT]
Name forward
Match kube.*
Host ${LOGGING_TCP_HOST}
Port 9000
Tag k8s
tls on
Shared_Key ${LOGGING_KEY}
El flujo de TCP requiere el puerto 9000 con TLS, y Shared_Key transporta la clave de la canalización. Los flujos de HTTP solo aceptan JSON, con la clave en la cabecera APIKEY.
2.3 Búsqueda de registros
El Logging Service almacena los registros en Loki, y usted los busca con LogQL en Grafana Explore. Las consultas no se contabilizan para la facturación.
{tag_name="k8s"} |= "taskboard-api" | json | level="error"
{tag_name="k8s"} |= "taskboard-worker" |= "KafkaError"
La etiqueta del stream se convierte en la etiqueta tag_name. Las demás etiquetas dependen de la fuente de registros y de sus etiquetas personalizadas, por lo que revise el explorador de etiquetas en Explore antes de guardar una consulta en un panel.
3. Trazas con el Tracing Service
3.1 Creación de una canalización OTLP
curl --request POST "https://tracing.de-txl.ionos.com/pipelines" \
--header "Authorization: Bearer $IONOS_TOKEN" \
--header "Content-Type: application/json" \
--data '{"metadata": {}, "properties": {"name": "taskboard-traces", "protocol": "otlp-http"}}'
protocol es otlp-http o otlp-grpc. Una vez que la canalización está AVAILABLE, metadata.otlpEndpoint contiene el host de ingesta; se trata de un nombre de host único por canalización, no el host de gestión tracing.<region>.ionos.com. Los exportadores OTLP/HTTP agregan /v1/traces y envían la clave en la cabecera apikey; los exportadores OTLP/gRPC la envían como metadatos apikey en el puerto 443.
3.2 Instrumentación de la API de TaskBoard
El exportador lee OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces", OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" y OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>" del entorno:
import json
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider(resource=Resource.create({"service.name": "taskboard-api"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("taskboard")
def log_json(level, msg):
ctx = trace.get_current_span().get_span_context()
print(json.dumps({"level": level, "msg": msg, "trace_id": format(ctx.trace_id, "032x")}))
with tracer.start_as_current_span("list_tasks"):
log_json("info", "cache miss, reading tasks from PostgreSQL")
Guarde el valor de las cabeceras en un Secret de Kubernetes. El trace_id en cada línea de registro JSON permite la correlación entre trazas y registros: en el mismo espacio de trabajo de Grafana, puede navegar desde una span hasta los registros de Loki correspondientes y las métricas de Mimir relacionadas.
Una sola traza no puede superar los 5 MB de datos combinados de spans. La ingesta está limitada a 15 MB/s de forma sostenida, con un pico de 20 MB; el tráfico excesivo recibe HTTP 429 (OTLP/HTTP) o RESOURCE_EXHAUSTED (OTLP/gRPC). Las trazas se conservan durante 30 días. Configure el muestreo para reducir el volumen que envía.
4. Auditoría de cambios y flujos de red
4.1 La API de Activity Log
La API de Activity Log es de solo lectura (solo GET) en https://api.ionos.com/activitylog/v1, acepta autenticación Basic o un token Bearer, y devuelve JSON con las entradas bajo hits:
import os
import requests
BASE = "https://api.ionos.com/activitylog/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['IONOS_TOKEN']}",
"Content-Type": "application/json"}
def activity(contract, date_start, date_end, page=500):
offset = 0
while True:
params = {"dateStart": date_start, "dateEnd": date_end, "offset": offset, "limit": page}
r = requests.get(f"{BASE}/contracts/{contract}", headers=HEADERS, params=params, timeout=30)
r.raise_for_status()
hits = r.json()["hits"]["hits"]
for hit in hits:
yield hit["_source"]
if len(hits) < page:
return
offset += page
for e in activity(31721060, "2026-11-02T00:00:00Z", "2026-11-03T00:00:00Z"):
actions = [a for res in e["event"]["resources"] for a in res["action"]]
print(e["meta"]["time"], e["principal"]["identity"]["username"], e["event"]["type"], actions)
dateStart es inclusivo y dateEnd es exclusivo; limit acepta hasta 10000. GET /contracts lista los contratos a los que sus credenciales pueden acceder. De forma predeterminada, solo el propietario del contrato y los administradores pueden llamar a la API; otros usuarios necesitan un grupo con el privilegio Access Activity Log. Las entradas se conservan durante 35 días, por lo que debe exportarlas a Object Storage o a Logging Service si necesita un historial más largo. El Activity Log abarca los productos de IaaS, no los productos de PaaS.
4.2 Flow Logs para problemas de conectividad
resource "ionoscloud_nic" "worker" {
datacenter_id = ionoscloud_datacenter.taskboard.id
server_id = ionoscloud_vcpu_server.worker.id
lan = ionoscloud_lan.app.id
dhcp = true
flowlog {
name = "worker-rejected"
action = "REJECTED"
direction = "BIDIRECTIONAL"
bucket = "taskboard-flowlogs-7f3a"
}
}
Flow Logs se admiten en las interfaces de red de VM, en el Managed Network Load Balancer, en el Managed Application Load Balancer y en el Managed NAT Gateway, con un registro de flujos por recurso. El bucket debe existir previamente y ser de propiedad del usuario. action, direction y bucket son inmutables; eliminar el bloque flowlog obliga a recrear la NIC. Los registros llegan como objetos .log.gz cada 10 minutos, y no se escribe ningún archivo para un intervalo sin flujos:
2 12345678 7ffd6527-ce80-4e57-a949-f9a45824ebe2 172.17.1.100 172.17.1.101 59113 20756 6 17 1325 1587983051 1587983052 REJECT OK
Los campos son version account-id interface-id srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status. Un REJECT en el puerto de destino de PostgreSQL o Kafka apunta a una regla de firewall o NSG, no a la aplicación. Configure una política de ciclo de vida en el bucket, ya que los registros de flujo se conservan hasta que los elimine.
5. El flujo de trabajo de depuración de Kubernetes
5.1 De Pod a Plataforma
Trabaje desde la vista más estrecha hacia afuera:
kubectl -n taskboard get pods -o wide # 1. status, restarts, node
kubectl -n taskboard describe pod <pod> # 2. probe failures, pull errors
kubectl -n taskboard get events --sort-by=.lastTimestamp # 3. scheduling, evictions
kubectl -n taskboard logs deploy/taskboard-api --previous # 4. the crashed container's output
Luego, amplíe el alcance a la plataforma: (5) los paneles de latencia y tasa de errores de Monitoring Service, (6) una búsqueda LogQL en todos los pods y la VM de trabajo, (7) la traza de una solicitud lenta y (8) el Activity Log para los cambios en la misma ventana de tiempo. Kubernetes conserva los eventos solo durante un tiempo limitado, por lo que guarde la salida de kubectl get events durante el incidente.
5.2 Health Checks
livenessProbe:
httpGet: { path: /api/health/live, port: 8000 }
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet: { path: /api/health/ready, port: 8000 }
periodSeconds: 5
Liveness reinicia un contenedor atascado; readiness elimina un pod de su Service mientras dependencias como PostgreSQL no están accesibles. En el ALB, dirija el http_health_check del grupo de destinos de las Unidades 2.3 y 3.2 hacia la misma ruta de readiness. Su bloque health_check establece check_interval y check_timeout en milisegundos; el intervalo predeterminado es 2000.
Tarjeta rápida de referencia de la API
Endpoints principales de la API para el tema de esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
POST |
https://monitoring.<region>.ionos.com/pipelines |
Crear un pipeline de Monitoring Service |
POST |
https://logging.<region>.ionos.com/pipelines/{pipelineID}/key |
Rotar una clave de pipeline de Logging Service |
POST |
https://tracing.<region>.ionos.com/pipelines |
Crear un pipeline de Tracing Service |
GET |
https://api.ionos.com/telemetry/api/v1/query |
Consultar métricas del servidor con PromQL |
GET |
https://api.ionos.com/activitylog/v1/contracts/{contractNumber} |
Leer entradas del Activity Log |
URL base: regional por servicio, tal como se indica arriba
Autenticación: Authorization: Bearer <token>
Laboratorio de código
Objetivo: Aprovisionar pipelines de métricas y registros para TaskBoard, reenviar los registros de MKS con Fluent Bit y, a continuación, depurar una interrupción simulada con kubectl, LogQL y el Activity Log.
Requisitos previos:
- Cuenta de IONOS CLOUD con un token de API en
IONOS_TOKEN - El clúster de MKS y los Deployments de TaskBoard de la Unidad 3.2
- Terraform,
kubectl, Helm y Python 3 conrequests
Paso 1: Aprovisionar los pipelines
Agregue los recursos y las salidas de las Secciones 1.1 y 2.1.
terraform apply -target=ionoscloud_monitoring_pipeline.taskboard -target=ionoscloud_logging_pipeline.taskboard
terraform output grafana_url
Salida esperada:
ionoscloud_monitoring_pipeline.taskboard: Creation complete after ...
ionoscloud_logging_pipeline.taskboard: Creation complete after ...
"https://grafana.<...>.ionos.com"
Paso 2: Almacenar las credenciales de registro en el clúster
kubectl create namespace logging
kubectl -n logging create secret generic logging-pipeline \
--from-literal=LOGGING_TCP_HOST="$(terraform output -raw logging_tcp_host)" \
--from-literal=LOGGING_KEY="$(terraform output -raw logging_key)"
Salida esperada:
namespace/logging created
secret/logging-pipeline created
Paso 3: Desplegar Fluent Bit
Guarde fluent-bit-values.yaml con envFrom: [{secretRef: {name: logging-pipeline}}] y la sección [OUTPUT] de la sección 2.2 bajo config.outputs.
helm repo add fluent https://fluent.github.io/helm-charts
helm install fluent-bit fluent/fluent-bit -n logging -f fluent-bit-values.yaml
kubectl -n logging get pods
Salida esperada:
NAME READY STATUS RESTARTS AGE
fluent-bit-<id> 1/1 Running 0 30s
Paso 4: Buscar los registros de TaskBoard en Grafana
Abra la URL de Grafana, inicie sesión con sus credenciales de IONOS CLOUD, seleccione Explore y ejecute:
{tag_name="k8s"} |= "taskboard-api"
Salida esperada:
<timestamp> {"level": "info", "msg": "GET /api/health 200", ...}
Paso 5: Simular una interrupción y encontrar la causa
kubectl -n taskboard set env deploy/taskboard-api DATABASE_URL="postgresql://wrong-host:5432/taskboard"
kubectl -n taskboard describe pod <new-pod> | grep Readiness
Luego, busque en Grafana Explore con {tag_name="k8s"} |= "taskboard-api" |= "wrong-host".
Salida esperada:
Readiness probe failed: HTTP probe failed with statuscode: 503
{"level": "error", "msg": "could not translate host name \"wrong-host\" ..."}
Paso 6: Descartar cambios de infraestructura y recuperar
Ejecute el script de la sección 4.1 para hoy. Un cambio de kubectl no es una llamada a la API de Cloud, por lo que busque solo entradas de infraestructura inesperadas; luego, revierta los cambios.
python activity.py
kubectl -n taskboard rollout undo deploy/taskboard-api
kubectl -n taskboard rollout status deploy/taskboard-api
Salida esperada:
<time> <user> <event type> [<actions>]
deployment "taskboard-api" successfully rolled out
Lista de verificación:
- [ ] Ambas canalizaciones existen y sus claves solo se encuentran en el estado de Terraform y en el Secret de Kubernetes
- [ ] Los registros del pod de TaskBoard son buscables en Grafana con LogQL
- [ ] La implementación defectuosa muestra sondas de preparación fallidas y el error en los registros
- [ ]
rollout undorestaura una API lista
Limpieza:
helm uninstall fluent-bit -n logging
kubectl delete namespace logging
terraform destroy -target=ionoscloud_logging_pipeline.taskboard -target=ionoscloud_monitoring_pipeline.taskboard
Errores comunes
Errores de desarrollo que debe evitar con el tema de esta unidad:
-
Esperar registros del clúster que nunca llegan
- Problema: La canalización de Logging Service es
AVAILABLE, pero Grafana no muestra registros ni eventos de Kubernetes. - Por qué ocurre: Los eventos del control plane no fluyen a través de Logging Service, los registros de auditoría van al bucket de Object Storage del clúster, y los registros de los pods requieren un agente que usted debe desplegar.
- Solución: Ejecute Fluent Bit (o un exportador OTLP) en el clúster con el host TCP de la canalización, el puerto 9000,
tls onyShared_Key(sección 2.2).
- Problema: La canalización de Logging Service es
-
Perder la clave de la canalización
- Problema: Un agente nuevo necesita la clave, pero
GET /pipelines/{pipelineID}no la devuelve. - Por qué ocurre: Las claves de monitorización y de registros se muestran una sola vez; la rotación revoca la clave anterior de inmediato.
- Solución: Marque la salida de Terraform como
sensitive, almacene la clave en su almacén de secretos y actualice todos los agentes en el mismo cambio cuando realice la rotación.
- Problema: Un agente nuevo necesita la clave, pero
-
Cambios en registros de flujo que recrean una NIC
- Problema: Cambiar
actiono eliminar el bloqueflowlogplanifica la sustitución de la NIC del worker. - Por qué ocurre: La configuración de los registros de flujo es inmutable, y eliminar un registro de flujo fuerza la recreación de la NIC.
- Solución: Defina la configuración de captura una sola vez, cambie solo
namein situ, y planifique las eliminaciones de registros de flujo como una sustitución de NIC en una ventana de mantenimiento.
- Problema: Cambiar
Resumen
Ahora puede proporcionar observabilidad como código para TaskBoard: Terraform crea las canalizaciones, Prometheus y Fluent Bit envían datos a ellas, y las trazas de OpenTelemetry se vinculan a las líneas de registro a través del identificador de traza. Cuando algo falla, trabaja desde kubectl hacia afuera, hasta las métricas, los registros, las trazas, el Activity Log y Flow Logs.
Puntos clave:
- Cada servicio de observabilidad es de tipo push: cree una canalización y luego dirija un agente o SDK a su endpoint con la clave de la canalización
- Las claves de canalización se muestran una sola vez; al rotar una clave, se revoca la anterior
- Los registros de auditoría del API-server de MKS se envían a un bucket de Object Storage que usted nombre; envíe los registros de los pods con un agente que usted despliegue
- La API de Activity Log es de solo lectura, conserva los datos durante 35 días y cubre los productos de IaaS
- La configuración de los registros de flujo es inmutable; los registros se depositan en su propio bucket de Object Storage cada 10 minutos
Terminología importante:
- Canalización: Una instancia de Monitoring, Logging o Tracing Service con su propio endpoint de ingesta y su clave
- Escritura remota: El protocolo de Prometheus para enviar muestras a
/api/v1/push - LogQL: El lenguaje de consulta de Loki que utiliza en Grafana Explore para buscar registros
- OTLP: El protocolo de OpenTelemetry, utilizado sobre HTTP o gRPC para enviar trazas
- Registro de flujo: Una línea separada por espacios que describe un flujo de red, su recuento de bytes y su acción de
ACCEPToREJECT
Próximos pasos
Continuar aprendiendo: Unidad 5.2: Automatización de seguridad
Temas relacionados: