Export d'alarmes au format CSV (Pro)¶

L'utilitaire export-alarms permet d'exporter des alarmes Canopsis au format CSV via l'API.

Il est conçu pour être exécuté automatiquement (via un ordonnanceur de tâches) afin de produire des exports réguliers destinés à :

Du reporting
De l'archivage
Des traitements externes
L'alimentation d'outils de BI

Principe de fonctionnement¶

export-alarms utilise l'API Canopsis pour :

Créer une tâche d'export d'alarmes
Attendre la génération du fichier
Récupérer les données
Écrire le résultat dans un fichier CSV local

Chaque export est défini dans un fichier de configuration YAML.

Un fichier CSV est généré par export configuré.

Le nom du fichier suit le format :

<label>-<timestamp>.csv

Exemple :

opened-alarms-2026-03-01T12-00-00.csv

Lancement de la commande¶

L'utilitaire peut être lancé directement :

export-alarms --config /opt/canopsis/share/config/export-alarms/config.yml

Options disponibles :

Option	Description
`-c`, `--config`	Chemin du fichier de configuration
`-d`, `--debug`	Active le mode debug
`--logger`	Destination des logs (`stderr`, `journald`)
`-v`, `--version`	Affiche la version
`-h`, `--help`	Affiche l'aide

Configuration¶

La configuration de l'outil est définie dans un fichier YAML.

Section API¶

Cette section définit la connexion à l'API Canopsis.

api:
  host: http://localhost:8082
  http_timeout: 5s
  export_timeout: 1m
  username: ""
  password: ""
  insecure_skip_verify: false

Warning

Il est recommandé d'utiliser les variables d'environnement pour les identifiants.

Variables d'environnement supportées :

Variable	Description
`CPS_API_USERNAME`	Identifiant API
`CPS_API_PASSWORD`	Mot de passe API
`CPS_API_URL`	URL de l'API (surcharge `api.host`)
`CPS_API_HTTP_TIMEOUT`	Timeout HTTP (surcharge `api.http_timeout`)
`CPS_API_EXPORT_TIMEOUT`	Timeout export (surcharge `api.export_timeout`)
`CPS_API_INSECURE_SKIP_VERIFY`	Désactive la vérification TLS du certificat serveur

Section CSV¶

Cette section configure la génération des fichiers CSV.

csv:
  separator: comma
  dir: /tmp/cps/export
  time_format: "YYYY-MM-DDThh:mm:ss"

Paramètres disponibles :

Paramètre	Description
`separator`	Séparateur CSV (`comma`, `semicolon`, `tab`, `space`)
`dir`	Répertoire de sortie
`time_format`	Format des dates dans le CSV

Définition des exports¶

Les exports sont définis dans la clé exports, imbriquée dans la section csv.

Chaque export correspond à un fichier CSV généré.

Exemple :

csv:
  separator: comma
  dir: /tmp/cps/export
  time_format: "YYYY-MM-DDThh:mm:ss"

  exports:
    - label: newest
      open: true
      interval: 15m
      time_field: v.creation_date

      fields:
        - name: v.display_name
          label: Display name
        - name: v.state.val
          label: State
        - name: v.output
          label: Output
        - name: v.creation_date
          label: Creation

Paramètres disponibles :

Paramètre	Description
`label`	Préfixe du nom du fichier
`open`	`true` = alarmes ouvertes, `false` = alarmes résolues
`interval`	Fenêtre temporelle (`15m`, `1h`, `1d`, `1w`, `1M`, `6M`)
`time_field`	Champ utilisé pour le filtrage temporel
`fields`	Liste des colonnes exportées

Exemple : export des alarmes résolues¶

- label: last_resolved
  open: false
  interval: 15m
  time_field: v.resolved

  fields:
    - name: v.display_name
      label: Display name
    - name: v.state.val
      label: State
    - name: v.output
      label: Output
    - name: v.creation_date
      label: Creation
    - name: v.resolved
      label: Resolved
    - name: v.duration
      label: Duration

Filtres avancés¶

Les filtres avancés utilisent le langage de patterns Canopsis, qui permet de définir des règles de filtrage sur les alarmes, les entités ou les comportements périodiques.

Ce langage repose sur une structure de conditions combinées avec des opérateurs logiques (ET / OU) appliquées sur les différents attributs des objets Canopsis.

La description complète du langage, des champs disponibles et des types de conditions est disponible dans la page suivante :

Langage des filtres et patterns

Note

Les filtres (alarm_pattern, entity_pattern, pbehavior_pattern, search) sont définis par export. Ils ne s'appliquent pas à tous les exports du fichier de configuration.

Alarm pattern¶

alarm_pattern:
  - - field: v.state.val
      cond:
        type: eq
        value: 3

Entity pattern¶

entity_pattern:
  - - field: type
      cond:
        type: eq
        value: resource

Pbehavior pattern¶

pbehavior_pattern:
  - - field: pbehavior_info.canonical_type
      cond:
        type: eq
        value: active

Recherche texte¶

search: "database"

Gestion des fichiers¶

L'utilitaire ne gère pas la rotation ni la suppression des fichiers générés.

La gestion de la rétention doit être assurée par :

Un script externe
Un cron dédié
Un outil de gestion de fichiers

Exécution¶

RPMDocker ComposeHelm

RPM¶

Si vous avez installé Canopsis via les paquets RPM, l'outil export-alarms est disponible directement sous forme de binaire.

Un fichier d'exemple de configuration est fourni dans le paquet (/opt/canopsis/share/config/export-alarms/config.yml.example).

Copiez-le en /opt/canopsis/share/config/export-alarms/config.yml et adaptez-le à vos besoins.

Important

Assurez-vous que le répertoire de destination existe (par défaut /tmp/export-alarms). Dans le cas contraire, le créer.

Exécution manuelle¶

Pour lancer l'export manuellement, utilisez la commande suivante :

/opt/canopsis/bin/export-alarms

Si l'exécution réussit, les fichiers CSV seront générés dans le répertoire configuré (par défaut /tmp/export-alarms).

Exécution automatique¶

Pour automatiser l'export, vous pouvez utiliser cron ou tout autre ordonnanceur de tâches afin d'exécuter la commande à intervalles réguliers.

Par exemple, pour planifier un export quotidien à 8h00 via un fichier crontab :

cat <<EOF > /etc/cron.d/export-alarms
0 8 * * * root /opt/canopsis/bin/export-alarms
EOF

Info

Les fichiers seront créés en root, pensez à adapter les permissions ou à exécuter la commande avec un utilisateur spécifique si nécessaire.

Docker¶

Dans votre fichier docker-compose.override.yml, une section export-alarms est normalement préconfigurée comme suit :

export-alarms:
  <<: *initial_config_base
  user: "${UID}:${GID}"
  profiles:
    - support
  image: ${DOCKER_REPOSITORY}${CPS_EDITION}/export-alarms:${CANOPSIS_IMAGE_TAG}
  volumes:
    - ./files-pro/export-alarms/csv:/tmp/export-alarms
    - ./files-pro/export-alarms/config.yml:/opt/canopsis/share/config/export-alarms/config.yml
  command: /export-alarms

Exécution manuelle¶

Pour lancer le conteneur manuellement, exécutez la commande suivante :

docker compose --profile support up export-alarms -d

Une fois le service démarré, les fichiers CSV seront générés dans le répertoire hôte configuré, ici ./files-pro/export-alarms/csv.

Exécution automatique¶

Pour automatiser cette tâche, vous pouvez configurer un cron sur l'hôte pour piloter le conteneur Docker.

Exemple pour un export quotidien à 8h00 (pensez à adapter le chemin vers votre projet Canopsis) :

cat <<EOF > /etc/cron.d/export-alarms
0 8 * * * root cd /opt/canopsis && docker compose --profile support up export-alarms --force-recreate
EOF

Helm¶

Lors d'une installation via Helm, le service export-alarms est géré nativement via un CronJob Kubernetes. Il n'y a pas d'exécution manuelle directe ; l'outil est conçu pour fonctionner de manière planifiée.

Configuration de l'automatisation¶

Pour activer et planifier l'export, modifiez ou surchargez votre fichier values.yaml :

exportAlarms:
  enabled: true
  schedule: "0 8 * * *" # à adapter selon la fréquence souhaitée
  storageClassName: "" # à renseigner pour persister et récupérer les CSV sur un volume partagé

Important

Avant le déploiement, assurez-vous que la configuration de l'outil est correctement définie dans votre config.yml ou via un ConfigMap dédié.

Dépannage¶

Problème	Cause probable	Solution
`job status=failed` avec un intervalle long (`1M`, `6M`) sur un volume élevé d'alarmes	Timeout MongoDB dépassé lors de la génération de l'export	Augmenter `export_timeout` dans la section `api` du fichier de configuration (ex. `3m` ou plus). Si insuffisant, augmenter également `ExportMongoClientTimeout` dans la configuration de l'API Canopsis (`[Canopsis.api]` du fichier TOML).
Erreur d'accès en écriture sur le répertoire de sortie (Docker)	Le répertoire monté appartient à `root`	Ajouter `user: "${UID}:${GID}"` dans le service Docker Compose