Telegraf : l'agent de collecte qui supporte tout

Telegraf est un agent de collecte de métriques qui récupère CPU, mémoire, Docker, PostgreSQL, Redis et des centaines d'autres sources, puis envoie le tout vers Prometheus, InfluxDB ou l'OpenTelemetry Collector. Un seul binaire, une configuration déclarative, aucun script maison à maintenir.

Ce guide s'adresse aux profils débutants et intermédiaires qui veulent centraliser leur collecte de métriques. Vous allez installer Telegraf (version 1.39.1, juin 2026), construire un premier pipeline, l'exposer à Prometheus et enrichir la collecte avec Docker et PostgreSQL. En production, pinez toujours la version, jamais :latest.

Ce que vous allez apprendre

Comprendre l'architecture en pipeline : inputs, processors, aggregators, outputs.
Installer Telegraf proprement (dépôt signé, image épinglée).
Construire un premier pipeline et le tester avec --test.
Exposer les métriques pour Prometheus ou les pousser en OTLP.
Sécuriser la collecte Docker et gérer les secrets.

À quoi sert Telegraf ?

Telegraf remplace une collection de scripts de collecte par une seule configuration. Chaque source (CPU, PostgreSQL, Docker, Nginx) est interrogée par un plugin dédié qui connaît son protocole ; Telegraf convertit ensuite tous les relevés dans un format interne unique, puis les transmet au backend de votre choix. Vous ne gérez plus que de la configuration déclarative, jamais de code de parsing.

Le problème sans agent de collecte

Vous gérez un serveur qui fait tourner PostgreSQL, Redis et une application Docker. Pour monitorer tout ça, vous devez :

# Métriques système ? Pas de format standard
cat /proc/meminfo | grep MemAvail  # → Valeur brute en Ko

# PostgreSQL ? Il faut écrire des requêtes SQL
psql -c "SELECT * FROM pg_stat_database;"  # → Résultat tabulaire

# Docker ? Encore une autre API
curl --unix-socket /var/run/docker.sock http://localhost/containers/json  # → JSON

Résultat : vous vous retrouvez avec 3 scripts, 3 formats, 3 façons de parser... et une dette technique qui s'accumule.

La solution : Telegraf comme agent universel

Avec Telegraf, une seule configuration collecte tout, normalise tout, et envoie tout :

Architecture Telegraf : Inputs → Processors → Aggregators → Outputs

Pourquoi c'est mieux :

Sans Telegraf	Avec Telegraf
Un script par source	Une config déclarative
Formats hétérogènes	Format unifié (InfluxDB line protocol)
Push ou pull selon la source	Telegraf s'en occupe
Maintenance des scripts	Plugins maintenus par la communauté
Une destination à la fois	Multi-destination native

Comprendre l'architecture

Telegraf traite les métriques en quatre étages successifs : les inputs collectent, les processors transforment métrique par métrique, les aggregators calculent sur une fenêtre de temps, les outputs expédient. Chaque métrique traverse ces étages dans cet ordre, ce qui explique pourquoi un filtre placé au niveau de l'input réduit la charge de tout le reste du pipeline.

Pipeline Telegraf : Inputs → Processors → Aggregators → Outputs

Pourquoi cette architecture ?

Prenons un besoin courant, qui combine quatre exigences sans rapport les unes avec les autres :

Collecter le CPU, la mémoire ET les métriques PostgreSQL
Renommer certains champs pour qu'ils correspondent à vos conventions
Filtrer les conteneurs de test pour ne garder que la prod
Envoyer le tout vers Prometheus ET InfluxDB simultanément

Avec Telegraf, vous configurez chaque étape indépendamment. Pas de code à écrire.

1. Inputs : collecter les données

Les inputs interrogent les sources et récupèrent les métriques. C'est le point d'entrée de votre pipeline.

Input	Ce qu'il collecte	Cas d'usage
`cpu`	Utilisation CPU par cœur	Monitoring système
`mem`	Mémoire utilisée/disponible	Monitoring système
`docker`	Métriques conteneurs	Environnements conteneurisés
`postgresql`	Stats BDD, locks, queries	Monitoring base de données
`prometheus`	Scrape endpoints /metrics	Récupérer des métriques existantes
`http`	Appel HTTP + parsing JSON	APIs custom

2. Processors : transformer les données

Les processors modifient les métriques après collecte. C'est ici que vous normalisez, enrichissez ou filtrez.

Processor	Ce qu'il fait	Exemple concret
`rename`	Renomme champs/tags	`cpu_usage_idle` → `cpu_idle`
`regex`	Extrait avec des regex	Extraire `dc=paris` du hostname `srv-paris-01`
`filter`	Supprime des métriques	Exclure les conteneurs dont le nom contient `test`
`converter`	Change les types	String → Integer pour les calculs

3. Aggregators : agréger dans le temps

Les aggregators calculent des statistiques sur une fenêtre temporelle. Utile pour réduire le volume ou obtenir des vues synthétiques.

Aggregator	Ce qu'il calcule	Quand l'utiliser
`basicstats`	min, max, mean, stdev	Vue d'ensemble statistique
`histogram`	Distribution en buckets	Analyser la distribution des latences
`merge`	Fusionne plusieurs métriques	Consolider des sources similaires

4. Outputs : envoyer les données

Les outputs transmettent les métriques aux backends. Vous pouvez en avoir plusieurs, les mêmes données partent vers tous les outputs.

Output	Destination	Mode
`prometheus_client`	Prometheus	Pull (exposition endpoint)
`influxdb_v2`	InfluxDB 2.x	Push
`kafka`	Kafka	Push
`file`	Fichier local	Debug

Installer Telegraf

Telegraf est un binaire Go unique, sans dépendance à installer. Quatre chemins mènent au même résultat : le dépôt signé InfluxData pour un service systemd géré par le gestionnaire de paquets, l'image conteneur pour Docker et Kubernetes, ou l'archive binaire pour un déploiement contrôlé. Vérifiez toujours la provenance de ce que vous installez : empreinte de la clé GPG pour le dépôt, somme de contrôle pour l'archive.

# Télécharger et vérifier la clé GPG (fingerprint officiel)
curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key

# Vérifier l'empreinte avant import
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \
  | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \
  && echo "Fingerprint OK" || echo "ERREUR: fingerprint invalide"

# Installer la clé dans le keyring dédié
cat influxdata-archive.key \
  | gpg --dearmor \
  | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null

# Ajouter le repo avec signature
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
  | sudo tee /etc/apt/sources.list.d/influxdata.list

# Installer
sudo apt-get update && sudo apt-get install telegraf

# Vérifier l'installation
telegraf version

Résultat attendu :

Telegraf 1.39.1

# Ajouter le repo
cat <<'EOF' | sudo tee /etc/yum.repos.d/influxdb.repo
[influxdb]
name = InfluxDB Repository
baseurl = https://repos.influxdata.com/rhel/$releasever/$basearch/stable
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive.key
EOF

# Installer
sudo yum install telegraf -y

# Vérifier
telegraf --version

# Créer un fichier de config minimal
cat > telegraf.conf << 'EOF'
[agent]
  interval = "10s"
  hostname = "demo"

[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[outputs.file]]
  files = ["stdout"]
EOF

# Lancer Telegraf (version pinnée, jamais :latest)
docker run --rm \
  -v $(pwd)/telegraf.conf:/etc/telegraf/telegraf.conf:ro \
  telegraf:1.39.1

Résultat : les métriques CPU s'affichent toutes les 10 secondes.

Téléchargez l'archive et sa somme de contrôle, publiée à côté d'elle sur dl.influxdata.com. La vérification doit précéder l'extraction : une archive corrompue ou substituée ne doit jamais être ouverte.

# Télécharger l'archive et sa somme de contrôle officielle (version 1.39.1)
wget https://dl.influxdata.com/telegraf/releases/telegraf-1.39.1_linux_amd64.tar.gz
wget https://dl.influxdata.com/telegraf/releases/telegraf-1.39.1_linux_amd64.tar.gz.sha256

# Vérifier l'empreinte AVANT d'extraire (doit afficher "OK")
echo "$(awk '{print $1}' telegraf-1.39.1_linux_amd64.tar.gz.sha256)  telegraf-1.39.1_linux_amd64.tar.gz" \
  | sha256sum --check -

# Extraire seulement si la vérification a réussi
tar xzf telegraf-1.39.1_linux_amd64.tar.gz

# Installer
sudo mv telegraf-1.39.1/usr/bin/telegraf /usr/local/bin/
telegraf version

Résultat attendu :

Telegraf 1.39.1

Votre premier pipeline

Créons un pipeline qui collecte les métriques système et les affiche.

L'interval définit la fréquence de collecte. Quand vous déployez plusieurs agents, ajoutez un jitter (ex: "5s") pour éviter le thundering herd, tous les agents qui interrogent simultanément.

[agent]
  interval = "10s"
  collection_jitter = "2s"  # ±2s de décalage aléatoire

Générer une configuration de base

telegraf config \
  --input-filter cpu:mem:disk \
  --output-filter file \
  > telegraf.conf

Simplifier la configuration

Éditez telegraf.conf pour ne garder que l'essentiel :

[agent]
  interval = "10s"
  round_interval = true
  hostname = "mon-serveur"

# Collecter CPU
[[inputs.cpu]]
  percpu = false
  totalcpu = true

# Collecter mémoire
[[inputs.mem]]

# Collecter espace disque
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

# Afficher dans le terminal
[[outputs.file]]
  files = ["stdout"]

Tester le pipeline

telegraf --config telegraf.conf --test

Résultat attendu :

> cpu,cpu=cpu-total,host=mon-serveur usage_idle=95.2,usage_system=2.1,usage_user=2.7 1707465600000000000
> mem,host=mon-serveur available=6442450944i,total=8589934592i,used=2147483648i 1707465600000000000
> disk,device=sda1,host=mon-serveur,path=/ free=42949672960i,total=107374182400i,used=64424509440i 1707465600000000000

Lancer en continu

# Mode debug pour voir ce qui se passe
telegraf --config telegraf.conf --debug

Appuyez sur Ctrl+C pour arrêter.

Exposer les métriques pour Prometheus

Modifiez la configuration pour exposer un endpoint /metrics :

[agent]
  interval = "10s"
  hostname = "mon-serveur"

[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[inputs.mem]]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

# Exposer pour Prometheus sur le port 9273
[[outputs.prometheus_client]]
  listen = ":9273"
  metric_version = 2
  path = "/metrics"

Lancer Telegraf
Fenêtre de terminal
```
telegraf --config telegraf.conf
```

Vérifier l'endpoint

curl http://localhost:9273/metrics

Résultat :

# HELP cpu_usage_idle Telegraf collected metric
# TYPE cpu_usage_idle gauge
cpu_usage_idle{cpu="cpu-total",host="mon-serveur"} 94.5
# HELP mem_available Telegraf collected metric
# TYPE mem_available gauge
mem_available{host="mon-serveur"} 6.442450944e+09

Configurer Prometheus pour scraper Telegraf

Ajoutez dans prometheus.yml :

scrape_configs:
  - job_name: 'telegraf'
    static_configs:
      - targets: ['localhost:9273']

Collecter Docker et PostgreSQL

Enrichissons le pipeline avec des métriques applicatives.

[agent]
  interval = "10s"
  hostname = "mon-serveur"

[global_tags]
  environment = "production"

# === SYSTÈME ===
[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[inputs.mem]]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

# === DOCKER ===
[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"
  gather_services = false
  container_name_exclude = ["telegraf*"]
  timeout = "5s"
  perdevice = true

# === POSTGRESQL ===
[[inputs.postgresql]]
  address = "postgres://telegraf:password@localhost/postgres?sslmode=disable"

# === OUTPUT ===
[[outputs.prometheus_client]]
  listen = ":9273"
  metric_version = 2

Monter /var/run/docker.sock dans Telegraf augmente fortement le risque : accéder au daemon Docker équivaut quasiment à un accès root sur l'hôte. Ajouter Telegraf au groupe docker a le même effet, à proscrire.

La bonne pratique est de ne jamais exposer le socket brut. Placez devant lui un socket-proxy, qui filtre les appels, puis pointez Telegraf vers le proxy plutôt que vers le socket :

[[inputs.docker]]
  endpoint = "tcp://docker-socket-proxy:2375"

Le plugin inputs.docker interroge deux endpoints : /info et /containers. Le proxy doit donc autoriser exactement ces deux permissions, INFO=1 et CONTAINERS=1, et rien d'autre. Complétez avec une configuration en lecture seule (telegraf.conf:ro) et un compte dédié sans privilège.

Métriques Docker disponibles

Le plugin docker produit une métrique par conteneur, avec le nom du conteneur et son image en tags. Voici les quatre familles les plus utiles pour un tableau de bord de départ.

Métrique	Description
`docker_container_cpu_usage_percent`	Utilisation CPU par conteneur
`docker_container_mem_usage`	Mémoire utilisée par conteneur
`docker_container_net_rx_bytes`	Trafic réseau reçu
`docker_container_blkio_io_service_bytes_read`	I/O disque lecture

Métriques PostgreSQL disponibles

Le plugin postgresql interroge les vues statistiques du serveur, il n'a donc besoin que d'un compte en lecture seule. Les compteurs remontés sont cumulatifs depuis le démarrage de l'instance : c'est leur variation dans le temps qui vous intéresse, pas leur valeur absolue.

Métrique	Description
`postgresql_numbackends`	Connexions actives
`postgresql_xact_commit`	Transactions commitées
`postgresql_blks_hit`	Cache hits
`postgresql_deadlocks`	Nombre de deadlocks

Déploiement Kubernetes

Dans un cluster, Telegraf se déploie en DaemonSet pour collecter les métriques de chaque nœud, avec sa configuration montée depuis une ConfigMap. Deux points demandent votre attention avant de copier les manifestes : le runtime de conteneurs réellement utilisé par vos nœuds, et les secrets injectés dans le Pod, qui ne doivent jamais figurer dans la ConfigMap.

DaemonSet

Un DaemonSet garantit un Pod Telegraf par nœud, y compris sur les nœuds ajoutés plus tard. Le nom du nœud est injecté dans la variable HOSTNAME via fieldRef, ce qui permet d'étiqueter les métriques sans dupliquer la configuration. Les montages de /proc et /sys sont en lecture seule, et les limits mémoire évitent qu'un agent sature un nœud si la cardinalité explose.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: telegraf
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: telegraf
  template:
    metadata:
      labels:
        app: telegraf
    spec:
      serviceAccountName: telegraf
      containers:
        - name: telegraf
          image: telegraf:1.39.1  # Toujours pinner la version
          env:
            - name: HOSTNAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: INFLUXDB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: telegraf-secrets
                  key: token
          volumeMounts:
            - name: config
              mountPath: /etc/telegraf
            - name: docker-socket
              mountPath: /var/run/docker.sock
              readOnly: true
            - name: proc
              mountPath: /host/proc
              readOnly: true
            - name: sys
              mountPath: /host/sys
              readOnly: true
          resources:
            limits:
              memory: 256Mi
              cpu: 200m
            requests:
              memory: 128Mi
              cpu: 100m
      volumes:
        - name: config
          configMap:
            name: telegraf-config
        - name: docker-socket
          hostPath:
            path: /var/run/docker.sock
        - name: proc
          hostPath:
            path: /proc
        - name: sys
          hostPath:
            path: /sys

ConfigMap

La ConfigMap porte le fichier telegraf.conf complet. Elle ne doit contenir aucun secret : les jetons passent par un objet Secret référencé en variable d'environnement, comme dans le DaemonSet ci-dessus. Modifier une ConfigMap ne redémarre pas les Pods, il faut relancer le DaemonSet pour que la nouvelle configuration soit prise en compte.

apiVersion: v1
kind: ConfigMap
metadata:
  name: telegraf-config
  namespace: monitoring
data:
  telegraf.conf: |
    [global_tags]
      cluster = "production"

    [agent]
      interval = "10s"
      round_interval = true
      hostname = "$HOSTNAME"

    [[inputs.cpu]]
      percpu = true
      totalcpu = true

    [[inputs.mem]]

    [[inputs.kubernetes]]
      url = "https://kubernetes.default.svc"
      bearer_token = "/var/run/secrets/kubernetes.io/serviceaccount/token"
      insecure_skip_verify = true

    [[outputs.prometheus_client]]
      listen = ":9273"

Monitoring de Telegraf

Un agent de collecte tombé en panne ne déclenche aucune alerte par lui-même : les courbes s'arrêtent, tout simplement. Telegraf sait donc se mesurer lui-même et publier ces relevés dans le même pipeline que le reste. Surveillez en priorité les erreurs d'écriture vers le backend et les métriques perdues, deux signes que le buffer sature.

Métriques internes

Le plugin internal ajoute les compteurs propres à l'agent au flux de sortie. L'option collect_memstats y joint la consommation mémoire du processus Go, utile pour repérer une fuite liée à une cardinalité excessive.

[[inputs.internal]]
  collect_memstats = true

Métriques disponibles :

internal_agent : état de l'agent
internal_gather : temps de collecte
internal_write : temps d'écriture

Healthcheck

Ces deux commandes constituent le contrôle minimal avant un déploiement. L'option --test exécute un seul cycle de collecte et affiche le résultat sur la sortie standard sans rien envoyer aux outputs : c'est une validation de bout en bout, pas un simple contrôle de syntaxe.

# Vérifier la config (dry-run)
telegraf --config telegraf.conf --test

# Afficher la version
telegraf version

Alertes recommandées sur l'agent

Avec inputs.internal, surveillez ces métriques :

Métrique	Seuil d'alerte	Signification
`internal_write.errors`	> 0 sur 5 min	Échecs d'écriture vers le backend
`internal_gather.errors`	> 0 sur 5 min	Échecs de collecte (input down)
`internal_agent.metrics_dropped`	> 0	Buffer saturé, métriques perdues
Scrape absent	2× interval	Agent down ou réseau coupé

Bonnes pratiques

Ces cinq réflexes règlent les problèmes qui apparaissent en production, pas en lab : secrets exposés dans un fichier de configuration versionné, volume de métriques inutiles, et surtout cardinalité (le nombre de combinaisons de tags distinctes), qui fait exploser la mémoire de l'agent comme celle du backend.

Utilisez des variables d'environnement
```
token = "${INFLUXDB_TOKEN}"
```
Filtrez au niveau de l'input

Évitez de collecter des métriques inutiles.
```
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]
```
Limitez la cardinalité

Évitez les tags à haute cardinalité (IDs uniques).
Testez avant de déployer
Fenêtre de terminal
```
telegraf --config telegraf.conf --test
```
Monitorez Telegraf lui-même

Activez inputs.internal pour surveiller les performances.

Dépannage

Face à un pipeline muet, testez toujours input par input avec --input-filter avant de suspecter l'output : la panne vient presque toujours d'une source injoignable ou d'un droit manquant. Le tableau ci-dessous relie les messages d'erreur les plus fréquents à leur cause réelle.

Symptôme	Cause probable	Solution
Plugin non trouvé	Version Telegraf trop ancienne	`telegraf --version` puis mettre à jour
`Error in plugin: permission denied`	Accès socket/fichier refusé	Passer par un socket-proxy, jamais le groupe `docker`
Timeout input	Source lente ou inaccessible	Augmenter `timeout` dans la config input
`metric buffer limit reached`	Trop de métriques en attente	Augmenter `metric_buffer_limit` ou réduire les inputs
Métriques dupliquées	Plusieurs instances scrapent la même source	Vérifier qu'un seul Telegraf collecte chaque source
Pas de métriques Docker	Socket inaccessible	Vérifier `/var/run/docker.sock` et permissions
Erreur PostgreSQL	Credentials invalides	Tester avec `psql` la chaîne de connexion

Commandes de diagnostic

Ces commandes isolent un morceau du pipeline sans toucher au fichier de configuration. Les filtres --input-filter et --output-filter acceptent le nom du plugin sans son préfixe (cpu, pas inputs.cpu).

# Mode debug complet
telegraf --config telegraf.conf --debug

# Tester uniquement l'input CPU
telegraf --config telegraf.conf --input-filter cpu --test

# Tester uniquement l'output Prometheus
telegraf --config telegraf.conf --output-filter prometheus_client --test

# Générer une config complète (utile pour explorer les options)
telegraf config > telegraf.full.conf

# Lister les plugins disponibles
telegraf --input-list
telegraf --output-list

Vérifier que les métriques remontent

Une fois l'agent lancé, interrogez directement l'endpoint exposé plutôt que d'attendre le prochain passage de Prometheus. Un compte de lignes proche de zéro indique que la collecte échoue en amont, même si le processus tourne.

# Endpoint Prometheus exposé ?
curl -s http://localhost:9273/metrics | head -20

# Combien de métriques ?
curl -s http://localhost:9273/metrics | grep -v "^#" | wc -l

# Métriques d'un input spécifique
curl -s http://localhost:9273/metrics | grep "docker_"

Telegraf vs autres agents

Telegraf n'est pas le seul agent de collecte, et le choix dépend surtout de ce que vous collectez. Pour des métriques d'infrastructure et de services, ses plugins sont difficiles à battre. Pour des logs ou un pipeline mêlant logs, métriques et traces, d'autres outils sont mieux placés.

Agent	Points forts	Quand l'utiliser
Telegraf	Des centaines de plugins, très bon pour métriques infra + services	Stack InfluxDB, ou besoin de collecter PostgreSQL/Redis/Docker
OTel Collector	Standard OTLP, normalisation, routing multi-backends	Pipeline unifié logs + metrics + traces, vendor-agnostic
Vector	Transformations puissantes, très performant	Pipelines logs complexes, enrichissement avancé
Fluent Bit	Ultra léger, CNCF	K8s/edge, logs principalement

Envoyer vers OpenTelemetry Collector

Telegraf peut exporter ses métriques en OTLP vers un Collector :

[[outputs.opentelemetry]]
  ## Endpoint OTLP gRPC du Collector
  service_address = "otel-collector:4317"

  ## Attributs OpenTelemetry ajoutés à toutes les métriques
  [outputs.opentelemetry.attributes]
    "service.name" = "telegraf"
    "deployment.environment" = "production"

Cela vous permet de :

Centraliser toutes les métriques dans un pipeline OTLP
Changer de backend (Prometheus → Mimir → Datadog) sans toucher à Telegraf
Ajouter du sampling, filtering, enrichissement côté Collector

Prometheus : pull vs push

Deux modes d'expédition coexistent et le choix n'est pas cosmétique. En pull, Telegraf expose un endpoint /metrics et attend que Prometheus vienne le lire : simple, mais il faut que Prometheus puisse joindre l'agent. En push, Telegraf envoie lui-même vers un point d'entrée remote_write, ce qui traverse un NAT ou un pare-feu sortant sans ouverture de port entrant.

Mode	Output	Usage
Pull	`prometheus_client`	Prometheus scrape `/metrics` sur le port exposé
Push	`http` vers remote_write	Envoyer vers Mimir, Cortex, Thanos

[[outputs.prometheus_client]]
  listen = ":9273"
  path = "/metrics"

[[outputs.http]]
  url = "http://mimir:9009/api/v1/push"
  data_format = "prometheusremotewrite"
  [outputs.http.headers]
    Content-Type = "application/x-protobuf"
    X-Prometheus-Remote-Write-Version = "0.1.0"

Gestion des secrets en production

Ne stockez jamais les tokens en clair dans telegraf.conf.

Variables d'environnement

Telegraf substitue les ${VARIABLE} du fichier de configuration au démarrage. Le secret reste donc hors du fichier versionné, mais il est visible dans l'environnement du processus : réservez cette méthode aux cas où un magasin de secrets n'est pas disponible.

[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"]
  token = "${INFLUXDB_TOKEN}"  # Injecté par systemd/K8s
  organization = "myorg"
  bucket = "metrics"

Secret stores (Telegraf 1.30+)

Telegraf supporte des secret stores externes :

[[secretstores.os]]
  id = "system"

[[outputs.influxdb_v2]]
  token = "@{system:influxdb_token}"

Checklist production

Passez ces sept points en revue avant tout déploiement hors de votre poste. Les trois premiers concernent l'intégrité de ce que vous exécutez, les quatre suivants la stabilité de la collecte dans la durée.

Pinner la version : telegraf:1.39.1 (jamais :latest)
Secrets externalisés : env vars ou secret store
Config read-only : -v telegraf.conf:/etc/telegraf/telegraf.conf:ro
Jitter configuré : éviter le thundering herd
Monitoring de l'agent : inputs.internal + alertes
Limiter la cardinalité : filtrer les tags à haute cardinalité
RBAC K8s : ServiceAccount avec permissions minimales

Scénario complet : monitoring d'une application web

Mettons tout ensemble avec un cas réaliste. Vous avez :

Un serveur Ubuntu avec Nginx en reverse proxy
Une application Node.js qui expose des métriques Prometheus
Une base PostgreSQL
Le tout monitoré dans Grafana via Prometheus

Configuration complète

Cette configuration réunit tout ce qui précède dans un seul fichier : quatre inputs système, deux inputs applicatifs, un processor et un output. Notez l'usage systématique de fieldpass, qui ne conserve que les champs réellement exploités : c'est le levier le plus efficace pour contenir le volume de métriques.

# === AGENT ===
[agent]
  interval = "15s"
  round_interval = true
  collection_jitter = "3s"
  flush_interval = "15s"
  flush_jitter = "3s"
  hostname = "${HOSTNAME}"

[global_tags]
  environment = "production"
  team = "backend"

# === SYSTÈME ===
[[inputs.cpu]]
  percpu = false
  totalcpu = true
  fieldpass = ["usage_idle", "usage_system", "usage_user"]

[[inputs.mem]]
  fieldpass = ["available_percent", "used_percent"]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "overlay"]
  fieldpass = ["used_percent", "free"]

[[inputs.net]]
  interfaces = ["eth0"]
  fieldpass = ["bytes_recv", "bytes_sent", "err_in", "err_out"]

# === NGINX ===
[[inputs.nginx]]
  urls = ["http://localhost:8080/nginx_status"]
  response_timeout = "5s"

# === APPLICATION NODE.JS ===
# L'app expose /metrics au format Prometheus
[[inputs.prometheus]]
  urls = ["http://localhost:3000/metrics"]
  metric_version = 2

# === POSTGRESQL ===
[[inputs.postgresql]]
  address = "postgres://telegraf:${PG_PASSWORD}@localhost:5432/myapp?sslmode=disable"

# === PROCESSORS ===
# Ajouter le datacenter comme tag
[[processors.regex]]
  [[processors.regex.tags]]
    key = "host"
    pattern = "^srv-(?P<datacenter>[a-z]+)-.*$"
    replacement = "${datacenter}"
    result_key = "dc"

# === OUTPUT ===
# Exposer pour Prometheus (Grafana le scrape)
[[outputs.prometheus_client]]
  listen = ":9273"
  metric_version = 2
  path = "/metrics"
  expiration_interval = "60s"

Points clés de cette configuration

Cinq choix de cette configuration méritent d'être repris tels quels dans vos propres déploiements, quel que soit le contexte.

collection_jitter : évite que tous les serveurs interrogent en même temps
fieldpass : ne garde que les champs utiles (réduit le volume)
global_tags : ajoute environment et team à toutes les métriques
Processors : extrait le datacenter du hostname automatiquement
Secrets : ${PG_PASSWORD} injecté via variable d'environnement

Validation

Validez la chaîne dans cet ordre : d'abord la configuration complète, puis chaque source sensible isolément, enfin l'endpoint exposé. Une source injoignable ne bloque pas le démarrage de Telegraf, elle se contente de journaliser une erreur à chaque cycle, d'où l'intérêt de la tester séparément.

# 1. Tester la configuration
telegraf --config telegraf.conf --test

# 2. Vérifier que toutes les sources répondent
telegraf --config telegraf.conf --input-filter nginx --test
telegraf --config telegraf.conf --input-filter postgresql --test

# 3. Lancer en mode debug
telegraf --config telegraf.conf --debug

# 4. Vérifier l'endpoint Prometheus
curl -s http://localhost:9273/metrics | grep -E "cpu_usage|mem_available|nginx"

FAQ : questions fréquentes

Les questions ci-dessous portent sur les points qui reviennent le plus souvent au moment de choisir et de configurer l'agent.

Qu'est-ce que Telegraf ?

Telegraf est un agent de collecte de métriques open source d'InfluxData. Il récupère des métriques via des plugins, les normalise et les envoie vers des backends comme Prometheus ou InfluxDB, par simple configuration.

Telegraf ou node_exporter, lequel choisir ?

node_exporter expose uniquement les métriques système pour Prometheus. Telegraf collecte bien plus (bases de données, Docker, applications) et envoie vers plusieurs backends. On choisit Telegraf dès qu'on dépasse le monitoring système.

Telegraf fonctionne-t-il avec Prometheus ?

Oui, dans les deux sens. Le plugin outputs.prometheus_client expose un endpoint /metrics que Prometheus scrape, et inputs.prometheus permet à Telegraf de récupérer des métriques déjà exposées au format Prometheus.

Telegraf est-il gratuit ?

Oui, Telegraf est open source sous licence MIT et gratuit. InfluxData propose des offres commerciales autour d'InfluxDB, mais l'agent Telegraf s'utilise librement avec n'importe quel backend.

Comment donner à Telegraf l'accès à Docker sans risque ?

Ne montez jamais le socket Docker brut ni n'ajoutez Telegraf au groupe docker (équivaut à root). Placez un socket-proxy devant le socket, activez les permissions INFO=1 et CONTAINERS=1, et pointez inputs.docker vers le proxy en TCP.

À retenir

Un seul agent pour tout collecter : système, Docker, BDD, applications
Pipeline : Input → Processor → Aggregator → Output
Des centaines de plugins prêts à l'emploi, sans code à écrire
Multi-destination : Prometheus, InfluxDB, OTel Collector simultanément
Test avant déploiement : telegraf --config telegraf.conf --test
Empreinte variable : dépend des plugins, de la cardinalité et des outputs
Pin de version : toujours en production

Prochaines étapes

Visualiser avec Grafana Créez des dashboards pour vos métriques Telegraf.

Prometheus Scraper et stocker les métriques exposées par Telegraf.

Pipeline complet avec OTel Combinez Telegraf et OpenTelemetry Collector.

Telegraf : l'agent de collecte qui supporte tout

Ce que vous allez apprendre

À quoi sert Telegraf ?

Le problème sans agent de collecte

La solution : Telegraf comme agent universel

Comprendre l'architecture

Pourquoi cette architecture ?

1. Inputs : collecter les données

2. Processors : transformer les données

3. Aggregators : agréger dans le temps

4. Outputs : envoyer les données

Installer Telegraf

Votre premier pipeline

Exposer les métriques pour Prometheus

Collecter Docker et PostgreSQL

Métriques Docker disponibles

Métriques PostgreSQL disponibles

Déploiement Kubernetes

DaemonSet

ConfigMap

Monitoring de Telegraf

Métriques internes

Healthcheck

Alertes recommandées sur l'agent

Bonnes pratiques

Dépannage

Commandes de diagnostic

Vérifier que les métriques remontent

Telegraf vs autres agents

Envoyer vers OpenTelemetry Collector

Prometheus : pull vs push

Gestion des secrets en production

Variables d'environnement

Secret stores (Telegraf 1.30+)

Checklist production

Scénario complet : monitoring d'une application web

Configuration complète

Points clés de cette configuration

Validation

FAQ : questions fréquentes

À retenir

Prochaines étapes

Ressources