Unité 5.1 : Observabilité et débogage
Introduction
TaskBoard fonctionne sur Managed Kubernetes, est déployé via CI/CD et communique avec PostgreSQL, In-Memory DB, Kafka et Object Storage. Un utilisateur signale ensuite que la liste des tâches est lente et que le worker a cessé d'envoyer des notifications. Vous avez besoin de réponses rapides : quel service est lent, qu'est-ce qui a changé et où vont les paquets.
Les services de surveillance, de journalisation et de Tracing Service stockent les métriques, les journaux et les traces, le tout visible dans un Grafana managé. Ils fonctionnent en mode push : vous créez un pipeline, puis vous y pointez un agent ou un SDK. L'API Activity Log enregistre qui a modifié quoi, et les Flow Logs enregistrent les flux réseau. Dans cette unité, vous construisez cette configuration pour TaskBoard sous forme de code, et dans le Code Lab, vous l'utilisez pour déboguer une panne simulée.
1. Métriques avec le Monitoring Service
1.1 Provisionnement d'un pipeline
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
}
La ressource n'accepte que des jetons pour l'autorisation, il est donc nécessaire de définir IONOS_TOKEN. Le même pipeline via l'API REST est un POST vers l'hôte régional :
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 clé du pipeline n'est renvoyée que dans la réponse de création et lors de la rotation des clés (POST /pipelines/{pipelineID}/key), ce qui invalide l'ancienne clé. Stockez-la immédiatement dans votre coffre de secrets. Un contrat peut avoir jusqu'à 10 pipelines par défaut ; le support IONOS CLOUD peut augmenter cette limite. Interrogez GET /pipelines/{pipelineID} jusqu'à ce que metadata.state soit AVAILABLE avant de configurer les agents.
1.2 Envoi des métriques TaskBoard
Le Monitoring Service est basé sur l'envoi actif : Prometheus, Grafana Agent, OpenTelemetry et Fluent Bit envoient des métriques au format Prometheus vers https://<HTTP_ENDPOINT>/api/v1/push via le port sortant 443. Pour un serveur Prometheus dans le cluster, ajoutez un bloc remote_write à prometheus.yml :
remote_write:
- url: "https://<pipeline-id>-metrics.<tenant>.monitoring.de-txl.ionos.com/api/v1/push"
headers:
APIKEY: "<pipeline key>"
L'agent envoie la clé dans l'en-tête APIKEY. L'intervalle de poussée par défaut est d'une minute, et vous pouvez le modifier. Les collecteurs OpenTelemetry peuvent également pousser nativement au format OTLP vers <httpEndpoint>/otlp/v1/metrics. Chaque point de données poussé est compté pour la facturation, donc supprimez les séries dont vous n'avez pas besoin avant qu'elles ne quittent le cluster.
1.3 Alertes
Les alertes personnalisées sont gérées dans Grafana : vous y définissez la condition d'alerte, le seuil et les paramètres de notification. Pour la latence de l'API de TaskBoard, déclenchez une alerte sur le 95e percentile de l'histogramme de durée des requêtes exporté par l'API :
histogram_quantile(0.95,
sum by (le) (rate(http_request_duration_seconds_bucket{service="taskboard-api"}[5m]))
) > 0.5
Conservez l'expression dans Git à côté du service. Pour les vérifications au niveau du serveur sans aucun agent, interrogez l'API Telemetry. Elle est compatible avec Prometheus, en lecture seule, utilise votre jeton Cloud API et devient disponible dès que votre contrat comporte au moins un pipeline d'observabilité :
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 est un jauge ; les huit autres métriques de l'API Telemetry sont des compteurs, il faut donc les encapsuler dans rate(). Les métriques portent le uuid du serveur, et non son nom ; il convient donc de résoudre les noms via l'API Cloud.
2. Journaux avec le Logging Service
2.1 Provisionnement d'un pipeline
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
}
Chaque bloc log est un flux de journaux disposant d'un tag unique. La rétention est de 7, 14 ou 30 jours par flux, avec 30 jours par défaut. La clé suit une politique de partage unique : elle ne peut plus être récupérée, et la génération d'une nouvelle clé avec POST /pipelines/{pipelineID}/key révoque instantanément la clé précédente.
Le tableau suivant répertorie les limites du Logging Service :
| Aspect | Description | Limite |
|---|---|---|
| Limite de débit HTTP | Limite de débit par défaut pour les requêtes HTTP par pipeline pendant l'ingestion des journaux. | 50 requêtes/seconde |
| Bande passante TCP | Limite de bande passante TCP par défaut par pipeline, approximativement en termes de journaux par seconde. | ~10 000 journaux/seconde |
| Pipelines maximum | Nombre maximal de pipelines autorisés par contrat. | 10 pipelines |
| Flux de journaux par pipeline | Nombre maximal de flux de journaux autorisés par pipeline. | 5 flux de journaux/pipeline |
Les enregistrements rejetés en raison de la limitation de débit ne sont pas stockés.
2.2 Transfert des journaux du Cluster depuis MKS
Les journaux d'audit de l'API Kubernetes sont envoyés vers le bucket Object Storage que vous configurez sur le cluster (Unité 3.2). Pour acheminer les journaux des pods vers le Logging Service, exécutez un agent dans le cluster, généralement Fluent Bit en tant que DaemonSet :
[OUTPUT]
Name forward
Match kube.*
Host ${LOGGING_TCP_HOST}
Port 9000
Tag k8s
tls on
Shared_Key ${LOGGING_KEY}
Le flux TCP nécessite le port 9000 avec TLS, et Shared_Key transporte la clé du pipeline. Les flux HTTP n'acceptent que le JSON, avec la clé dans l'en-tête APIKEY.
2.3 Recherche dans les journaux
Le Logging Service stocke les journaux dans Loki, et vous les recherchez à l'aide de LogQL dans Grafana Explore. Les requêtes ne sont pas comptabilisées dans la facturation.
{tag_name="k8s"} |= "taskboard-api" | json | level="error"
{tag_name="k8s"} |= "taskboard-worker" |= "KafkaError"
L'étiquette du flux devient l'étiquette tag_name. Les autres étiquettes dépendent de la source des journaux et de vos étiquettes personnalisées. Vérifiez donc le navigateur d'étiquettes dans Explore avant d'enregistrer une requête dans un tableau de bord.
3. Traces avec le Tracing Service
3.1 Création d'un pipeline 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 est otlp-http ou otlp-grpc. Une fois le pipeline AVAILABLE, metadata.otlpEndpoint contient l'hôte d'ingestion ; il s'agit d'un nom d'hôte unique par pipeline, et non de l'hôte de gestion tracing.<region>.ionos.com. Les exportateurs OTLP/HTTP ajoutent /v1/traces et envoient la clé dans l'en-tête apikey ; les exportateurs OTLP/gRPC l'envoient comme métadonnée apikey sur le port 443.
3.2 Instrumentation de l'API TaskBoard
L'exportateur lit OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<tracing-ingestion-endpoint>/v1/traces", OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" et OTEL_EXPORTER_OTLP_HEADERS="apikey=<API_KEY>" depuis l'environnement :
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")
Placez la valeur des en-têtes dans un Secret Kubernetes. Le trace_id présent dans chaque ligne de journal JSON permet la corrélation traçe-journal : dans le même espace de travail Grafana, vous pouvez naviguer depuis une trace vers les journaux Loki correspondants et les métriques Mimir associées.
Une trace unique ne peut pas dépasser 5 Mo de données combinées de traces. L'ingestion est limitée à 15 Mo/s en régime permanent avec une pointe de 20 Mo ; le trafic excédentaire reçoit une réponse HTTP 429 (OTLP/HTTP) ou RESOURCE_EXHAUSTED (OTLP/gRPC). Les traces sont conservées pendant 30 jours. Configurez l'échantillonnage pour réduire le volume que vous envoyez.
4. Audit des modifications et des flux réseau
4.1 L'API Activity Log
L'API Activity Log est en lecture seule (GET uniquement) sur https://api.ionos.com/activitylog/v1, accepte l'authentification de base ou un jeton Bearer, et renvoie du JSON avec les entrées sous 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 est inclusif et dateEnd est exclusif ; limit accepte jusqu'à 10000. GET /contracts répertorie les contrats auxquels vos identifiants d'accès peuvent accéder. Par défaut, seul le propriétaire du contrat et les administrateurs peuvent appeler l'API ; les autres utilisateurs ont besoin d'un groupe disposant du privilège Access Activity Log. Les entrées sont conservées pendant 35 jours ; exportez-les vers Object Storage ou vers le Logging Service si vous avez besoin d'un historique plus long. Le Journal d'activité couvre les produits IaaS, mais pas les produits PaaS.
4.2 Flow Logs pour les problèmes de connectivité
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 sont pris en charge sur les interfaces réseau des VM, le Managed Network Load Balancer, le Managed Application Load Balancer et le Managed NAT Gateway, avec un flux de logs par ressource. Le bucket doit déjà exister et appartenir à l'utilisateur. action, direction et bucket sont immuables ; la suppression du bloc flowlog force la recréation de la NIC. Les enregistrements arrivent sous forme d'objets .log.gz toutes les 10 minutes, et aucun fichier n'est écrit pour un intervalle sans flux :
2 12345678 7ffd6527-ce80-4e57-a949-f9a45824ebe2 172.17.1.100 172.17.1.101 59113 20756 6 17 1325 1587983051 1587983052 REJECT OK
Les champs sont version account-id interface-id srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status. Un REJECT sur le port de destination de PostgreSQL ou de Kafka renvoie vers une règle de pare-feu ou de NSG, et non vers l'application. Configurez une politique de cycle de vie sur le bucket, car les journaux de flux sont conservés jusqu'à leur suppression.
5. Le flux de travail de débogage Kubernetes
5.1 De la Pod à la plateforme
Travaillez depuis la vue la plus restreinte vers l'extérieur :
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
Élargissez ensuite le périmètre à la plateforme : (5) les panneaux de latence et de taux d'erreur du Monitoring Service, (6) une recherche LogQL sur tous les pods et la VM worker, (7) la trace d'une requête lente, et (8) le journal d'activité pour les modifications survenant dans la même fenêtre temporelle. Kubernetes conserve les événements pendant une durée limitée uniquement, il est donc recommandé de conserver la sortie de kubectl get events pendant l'incident.
5.2 Vérifications d'état
livenessProbe:
httpGet: { path: /api/health/live, port: 8000 }
periodSeconds: 10
failureThreshold: 3
readinessProbe:
httpGet: { path: /api/health/ready, port: 8000 }
periodSeconds: 5
Liveness redémarre un conteneur bloqué ; readiness retire un pod de son Service lorsque des dépendances, telles que PostgreSQL, sont inaccessibles. Au niveau de l'ALB, orientez le http_health_check du groupe de cibles des Unités 2.3 et 3.2 vers le même chemin de readiness. Son bloc health_check définit check_interval et check_timeout en millisecondes ; l'intervalle par défaut est de 2000.
Fiche de référence rapide de l'API
Principales terminaisons d'API pour le sujet de cette unité :
| Méthode | Terminaison | Description |
|---|---|---|
POST |
https://monitoring.<region>.ionos.com/pipelines |
Créer un pipeline de Monitoring Service |
POST |
https://logging.<region>.ionos.com/pipelines/{pipelineID}/key |
Faire pivoter une clé de pipeline de Logging Service |
POST |
https://tracing.<region>.ionos.com/pipelines |
Créer un pipeline de Tracing Service |
GET |
https://api.ionos.com/telemetry/api/v1/query |
Interroger les métriques du serveur avec PromQL |
GET |
https://api.ionos.com/activitylog/v1/contracts/{contractNumber} |
Lire les entrées du journal d'activité |
URL de base : régionale selon le service, comme indiqué ci-dessus
Authentification : Authorization: Bearer <token>
Atelier de code
Objectif : Provisionner les pipelines de métriques et de journaux pour TaskBoard, transférer les journaux MKS avec Fluent Bit, puis diagnostiquer une panne simulée à l'aide de kubectl, LogQL et du Journal d'activité.
Prérequis :
- Un compte IONOS CLOUD avec un jeton API dans
IONOS_TOKEN - Le cluster MKS et les déploiements TaskBoard de l'unité 3.2
- Terraform,
kubectl, Helm et Python 3 avecrequests
Étape 1 : Provisionner les pipelines
Ajoutez les ressources et les sorties des sections 1.1 et 2.1.
terraform apply -target=ionoscloud_monitoring_pipeline.taskboard -target=ionoscloud_logging_pipeline.taskboard
terraform output grafana_url
Sortie attendue :
ionoscloud_monitoring_pipeline.taskboard: Creation complete after ...
ionoscloud_logging_pipeline.taskboard: Creation complete after ...
"https://grafana.<...>.ionos.com"
Étape 2 : Stocker les identifiants de journalisation dans le cluster
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)"
Sortie attendue :
namespace/logging created
secret/logging-pipeline created
Étape 3 : Déployer Fluent Bit
Enregistrez fluent-bit-values.yaml avec envFrom: [{secretRef: {name: logging-pipeline}}] et la section [OUTPUT] de la section 2.2 sous 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
Sortie attendue :
NAME READY STATUS RESTARTS AGE
fluent-bit-<id> 1/1 Running 0 30s
Étape 4 : Rechercher les journaux de TaskBoard dans Grafana
Ouvrez l'URL de Grafana, connectez-vous avec vos identifiants IONOS CLOUD, sélectionnez Explore et exécutez :
{tag_name="k8s"} |= "taskboard-api"
Sortie attendue :
<timestamp> {"level": "info", "msg": "GET /api/health 200", ...}
Étape 5 : Simuler une panne et en identifier la cause
kubectl -n taskboard set env deploy/taskboard-api DATABASE_URL="postgresql://wrong-host:5432/taskboard"
kubectl -n taskboard describe pod <new-pod> | grep Readiness
Recherchez ensuite dans Grafana Explore avec {tag_name="k8s"} |= "taskboard-api" |= "wrong-host".
Sortie attendue :
Readiness probe failed: HTTP probe failed with statuscode: 503
{"level": "error", "msg": "could not translate host name \"wrong-host\" ..."}
Étape 6 : Écarter les modifications d'infrastructure et procéder à la récupération
Exécutez le script de la section 4.1 pour aujourd'hui. Une modification kubectl n'est pas un appel à l'API Cloud, il faut donc rechercher uniquement les entrées d'infrastructure inattendues, puis effectuer un retour arrière.
python activity.py
kubectl -n taskboard rollout undo deploy/taskboard-api
kubectl -n taskboard rollout status deploy/taskboard-api
Sortie attendue :
<time> <user> <event type> [<actions>]
deployment "taskboard-api" successfully rolled out
Liste de contrôle de validation :
- [ ] Les deux pipelines existent et leurs clés ne sont présentes que dans l'état Terraform et dans le Secret Kubernetes
- [ ] Les journaux du pod TaskBoard sont consultables dans Grafana à l'aide de LogQL
- [ ] Le déploiement défaillant affiche des sondes de préparation en échec et l'erreur dans les journaux
- [ ]
rollout undorestaure une API prête
Nettoyage :
helm uninstall fluent-bit -n logging
kubectl delete namespace logging
terraform destroy -target=ionoscloud_logging_pipeline.taskboard -target=ionoscloud_monitoring_pipeline.taskboard
Erreurs courantes
Erreurs de développement à éviter concernant le sujet de cette unité :
-
Attendre des journaux de cluster qui n'arrivent jamais
- Problème : Le pipeline du Logging Service est
AVAILABLE, mais Grafana n'affiche aucun journal ou événement Kubernetes. - Pourquoi cela se produit : Les événements du plan de contrôle ne transitent pas par le Logging Service, les journaux d'audit sont envoyés vers le bucket Object Storage du cluster, et les journaux des pods nécessitent un agent que vous devez déployer.
- Correction : Exécutez Fluent Bit (ou un exporteur OTLP) dans le cluster avec l'hôte TCP du pipeline, le port 9000,
tls onetShared_Key(section 2.2).
- Problème : Le pipeline du Logging Service est
-
Perte de la clé du pipeline
- Problème : Un nouvel agent a besoin de la clé, mais
GET /pipelines/{pipelineID}ne la renvoie pas. - Pourquoi cela se produit : Les clés de surveillance et de journalisation sont affichées une seule fois ; la rotation révoque immédiatement l'ancienne clé.
- Correction : Marquez la sortie Terraform
sensitive, stockez la clé dans votre coffre-fort de secrets et mettez à jour tous les agents dans la même modification lors de la rotation.
- Problème : Un nouvel agent a besoin de la clé, mais
-
Modifications des journaux de flux qui recréent une carte réseau
- Problème : Modifier
actionou supprimer le blocflowlogplanifie le remplacement de la carte réseau du nœud de travail. - Pourquoi cela se produit : Les paramètres des journaux de flux sont immuables, et la suppression d'un journal de flux force la recréation de la carte réseau.
- Correction : Définissez les paramètres de capture une seule fois, modifiez uniquement
namesur place, et planifiez les suppressions de journaux de flux comme un remplacement de carte réseau lors d'une fenêtre de maintenance.
- Problème : Modifier
Résumé
Vous pouvez désormais fournir l'observabilité de TaskBoard sous forme de code : Terraform crée les pipelines, Prometheus et Fluent Bit y poussent les données, et les traces OpenTelemetry sont liées aux lignes de journal par l'identifiant de trace. Lorsqu'un problème survient, vous travaillez à partir de kubectl vers l'extérieur, en direction des métriques, des journaux, des traces, du journal d'activité et des Flow Logs.
Points clés :
- Chaque service d'observabilité est basé sur la poussée : créez un pipeline, puis pointez un agent ou un SDK vers son point de terminaison à l'aide de la clé du pipeline
- Les clés de pipeline ne sont affichées qu'une seule fois ; la rotation d'une clé révoque l'ancienne
- Les journaux d'audit du serveur API MKS sont envoyés vers un bucket Object Storage que vous nommez ; expédiez les journaux des pods à l'aide d'un agent que vous déployez
- L'API du journal d'activité est en lecture seule, conserve les données pendant 35 jours et couvre les produits IaaS
- Les paramètres des journaux de flux sont immuables ; les enregistrements sont déposés dans votre propre bucket Object Storage toutes les 10 minutes
Terminologie importante :
- Pipeline : Une instance de service de surveillance, de journalisation ou de Tracing Service avec son propre point de terminaison d'ingestion et sa clé
- Écriture distante : Le protocole Prometheus pour pousser des échantillons vers
/api/v1/push - LogQL : Le langage de requête Loki que vous utilisez dans Grafana Explore pour rechercher dans les journaux
- OTLP : Le protocole OpenTelemetry, utilisé via HTTP ou gRPC pour envoyer des traces
- Enregistrement de journal de flux : Une ligne séparée par des espaces décrivant un flux réseau, son nombre d'octets et son action
ACCEPTouREJECT
Prochaines étapes
Continuer l'apprentissage : Unité 5.2 : Sécurité automatisée
Sujets connexes :