Aller au contenu principal

Surveillance & Métriques

L'API OmniCRM fournit des métriques complètes basées sur Prometheus pour surveiller la performance des applications, les opérations commerciales et les intégrations externes. Toutes les métriques sont exposées à l'endpoint /crm/metrics au format d'exposition Prometheus.

Vue d'ensemble​

Le système de métriques suit :

  • Opérations de Provisionnement - Exécution des tâches, durée, taux de succès/échec
  • Performance de la Base de Données - Temps de requête, santé du pool de connexions
  • Intégrations Externes - Appels API OCS/CGRateS, Stripe, Mailjet
  • Tâches en Arrière-plan - Exécution et performance des tâches asynchrones
  • Requêtes HTTP - Utilisation des endpoints API et temps de réponse (généré automatiquement)

Endpoint de Métriques​

URL : http://your-omnicrm-api:5000/crm/metrics

Format : Format d'exposition Prometheus

Authentification : Prometheus peut extraire les métriques de l'endpoint, qui est accessible publiquement. En production, restreignez l'accès avec des règles de pare-feu ou une authentification par proxy inverse.

Catégories de Métriques​

1. Métriques de Provisionnement​

Les métriques de provisionnement suivent l'exécution des playbooks Ansible qui provisionnent des services, gèrent l'inventaire et configurent des systèmes externes. Voir Système de Provisionnement et Playbooks Ansible pour plus de détails.

omnicrm_provision_jobs_total​

Type : Compteur

Étiquettes :

  • status - Statut d'achèvement de la tâche : success, failed, running

Description : Nombre total de tâches de provisionnement créées. Incrémenté lorsque les tâches de provisionnement se terminent avec leur statut final.

omnicrm_provision_job_duration_seconds​

Type : Histogramme

Étiquettes :

  • playbook - Nom du playbook Ansible exécuté
  • status - Statut d'achèvement de la tâche : success, failed

Seaux : [1, 5, 10, 30, 60, 120, 180, 300, 600] secondes (1s à 10min)

Description : Temps pris pour que les tâches de provisionnement se terminent. Enregistre la durée de l'exécution complète du playbook du début à la fin.

omnicrm_provision_jobs_active​

Type : Jauge

Description : Nombre de t��ches de provisionnement actuellement en cours d'exécution. Incrémenté lorsqu'une tâche commence, décrémenté lorsqu'elle se termine.

omnicrm_provision_tasks_total​

Type : Compteur

Étiquettes :

  • playbook - Nom du playbook Ansible
  • status - Résultat de la tâche : ok, failed, ignored

Description : Nombre total de tâches Ansible exécutées dans les playbooks. Incrémenté pour chaque tâche individuelle qui se termine (succès ou échec).

omnicrm_provision_errors_total​

Type : Compteur

Étiquettes :

  • error_type - Type d'erreur : fatal, task_failed, timeout
  • playbook - Nom du playbook Ansible

Description : Nombre total d'erreurs de provisionnement par type. Incrémenté lorsque les tâches de provisionnement échouent ou que des erreurs fatales se produisent pendant l'exécution.

2. Métriques de Base de Données​

Les métriques de base de données surveillent la performance des requêtes et la santé du pool de connexions. OmniCRM utilise SQLAlchemy avec instrumentation automatique. Voir Architecture du Système pour les détails du modèle de données.

omnicrm_db_query_duration_seconds​

Type : Histogramme

Étiquettes :

  • operation - Type d'opération SQL : SELECT, INSERT, UPDATE, DELETE
  • table - Nom de la table de base de données

Seaux : [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0] secondes

Description : Temps d'exécution des requêtes de base de données. Suivi automatiquement via des écouteurs d'événements SQLAlchemy sur chaque requête.

omnicrm_db_pool_size​

Type : Jauge

Description : Taille actuelle du pool de connexions de la base de données. Le nombre total de connexions dans le pool (à la fois vérifiées et disponibles).

omnicrm_db_pool_overflow​

Type : Jauge

Description : Débordement actuel du pool de connexions de la base de données. Le nombre de connexions créées au-delà de la limite normale de taille du pool.

omnicrm_db_pool_connections_checked_out​

Type : Jauge

Description : Nombre de connexions actuellement vérifiées et utilisées par le code de l'application.

omnicrm_db_errors_total​

Type : Compteur

Étiquettes :

  • error_type - Type d'erreur de base de données
  • operation - Opération qui a causé l'erreur : connection_error, query_error, etc.

Description : Nombre total d'erreurs de base de données.

Statut : Défini mais pas activement utilisé dans le code actuel (réservé pour une utilisation future)

3. Métriques OCS/CGRateS​

Les métriques OCS (Système de Facturation en Ligne) suivent les interactions avec le moteur de facturation CGRateS. Voir Vue d'ensemble de la Facturation et Intégration CGRateS pour plus de détails.

omnicrm_ocs_api_calls_total​

Type : Compteur

Étiquettes :

  • method - Méthode API OCS : GetBalance, SetBalance, SetAccount, RemoveAccount, etc.
  • status - Résultat de l'appel : success, failed

Description : Nombre total d'appels API OCS/CGRateS. Incrémenté pour chaque appel API asynchrone au système OCS.

omnicrm_ocs_api_duration_seconds​

Type : Histogramme

Étiquettes :

  • method - Méthode API OCS : GetBalance, SetBalance, GetAccount, etc.

Seaux : [0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] secondes

Description : Durée des appels API OCS/CGRateS. Enregistre le temps pris pour chaque appel API, y compris la latence réseau.

omnicrm_ocs_api_errors_total​

Type : Compteur

Étiquettes :

  • method - Méthode API OCS qui a échoué
  • error_type - Catégorie d'erreur : timeout, connection_error, json_error, http_error, etc.

Description : Nombre total d'erreurs API OCS/CGRateS. Incrémenté lorsque les appels API OCS échouent avec des types d'erreurs spécifiques.

omnicrm_ocs_balance_queries_total​

Type : Compteur

Étiquettes :

  • query_type - Type de requête de solde : single_account, multiple_accounts

Description : Nombre total de requêtes de solde vers OCS. Utilisé pour suivre l'utilisation des opérations de demande de solde.

omnicrm_ocs_action_plan_operations_total​

Type : Compteur

Étiquettes :

  • operation - Opération de plan d'action : create, remove, query

Description : Nombre total d'opérations de plan d'action. Suit la création, la suppression et la requête des plans d'action CGRateS pour les frais récurrents.

4. Métriques de Paiement Stripe​

Les métriques Stripe suivent les opérations de traitement des paiements. Voir Guide du Système de Paiement et Méthodes de Paiement pour les détails d'intégration.

omnicrm_stripe_api_calls_total​

Type : Compteur

Étiquettes :

  • operation - Opération Stripe : create_customer, charge, refund, update_payment_method, etc.
  • status - Résultat de l'opération : success, failed

Description : Nombre total d'appels API Stripe. Incrémenté pour chaque opération de traitement de paiement.

omnicrm_stripe_api_duration_seconds​

Type : Histogramme

Étiquettes :

  • operation - Type d'opération Stripe

Seaux : [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] secondes

Description : Durée des appels API Stripe, y compris la latence réseau.

omnicrm_stripe_api_errors_total​

Type : Compteur

Étiquettes :

  • operation - Opération Stripe qui a échoué
  • error_type - Catégorie d'erreur : card_declined, network_error, api_error, etc.

Description : Nombre total d'erreurs API Stripe. Incrémenté lorsque les opérations de paiement échouent.

omnicrm_stripe_payment_amount_cents​

Type : Compteur

Étiquettes :

  • payment_type - Direction du paiement : charge, refund

Description : Montant total des paiements traités via Stripe en cents. Utile pour suivre le volume des transactions et les revenus.

omnicrm_stripe_payment_failures_total​

Type : Compteur

Étiquettes :

  • reason - Raison de l'échec : card_declined, insufficient_funds, expired_card, etc.

Description : Nombre total d'échecs de paiement Stripe classés par code de refus.

5. Métriques d'Email Mailjet​

Les métriques Mailjet suivent les opérations de livraison d'emails. Voir Intégration Mailjet pour les détails de configuration.

omnicrm_mailjet_api_calls_total​

Type : Compteur

Étiquettes :

  • email_type - Type de modèle d'email : welcome, user_welcome, invoice, notification
  • status - Résultat de la livraison : success, failed

Description : Nombre total d'appels API Mailjet. Suivi via le décorateur @track_mailjet_call.

omnicrm_mailjet_api_duration_seconds​

Type : Histogramme

Étiquettes :

  • email_type - Type de modèle d'email

Seaux : [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] secondes

Description : Durée des appels API Mailjet. Temps pris pour soumettre un email via l'API Mailjet (pas le temps de livraison).

omnicrm_mailjet_api_errors_total​

Type : Compteur

Étiquettes :

  • email_type - Type de modèle d'email
  • error_type - Catégorie d'erreur

Description : Nombre total d'erreurs API Mailjet. Incrémenté lorsque l'envoi d'emails échoue.

omnicrm_mailjet_emails_sent_total​

Type : Compteur

Étiquettes :

  • email_type - Type de modèle d'email
  • template_id - ID du modèle Mailjet

Description : Nombre total d'emails envoyés avec succès via Mailjet. Distinct des appels API car un appel peut envoyer à plusieurs destinataires.

omnicrm_mailjet_email_recipients_total​

Type : Compteur

Étiquettes :

  • email_type - Type de modèle d'email

Description : Nombre total de destinataires d'emails à travers tous les emails envoyés.

6. Métriques de Tâches en Arrière-plan​

Les métriques de tâches en arrière-plan suivent les opérations asynchrones comme les chaînes de playbooks et les tâches planifiées. Voir Système de Provisionnement pour les détails des tâches en arrière-plan.

omnicrm_background_jobs_total​

Type : Compteur

Étiquettes :

  • job_type - Catégorie de tâche : playbook_single, playbook_chain, periodic_task

Description : Nombre total de tâches en arrière-plan démarrées. Suivi via le gestionnaire de contexte BackgroundJobTimer.

omnicrm_background_jobs_active​

Type : Jauge

Étiquettes :

  • job_type - Catégorie de tâche

Description : Nombre de tâches en arrière-plan actuellement en cours d'exécution. Incrémenté au démarrage de la tâche, décrémenté à l'achèvement de la tâche.

omnicrm_background_job_duration_seconds​

Type : Histogramme

Étiquettes :

  • job_type - Catégorie de tâche
  • status - Résultat de la tâche : success, failed

Seaux : [1, 5, 10, 30, 60, 120, 180, 300, 600, 1800, 3600] secondes (1s à 1h)

Description : Temps d'exécution des tâches en arrière-plan. Inclut la durée complète des opérations multi-étapes.

omnicrm_background_job_errors_total​

Type : Compteur

Étiquettes :

  • job_type - Catégorie de tâche
  • error_type - Catégorie d'erreur

Description : Nombre total d'erreurs de tâches en arrière-plan. Incrémenté lorsque les tâches en arrière-plan échouent avec des exceptions.

7. Métriques HTTP Flask (Générées automatiquement)​

Ces métriques sont générées automatiquement par la bibliothèque prometheus-flask-exporter et suivent toutes les requêtes HTTP à l'API.

flask_http_request_duration_seconds​

Type : Histogramme

Étiquettes :

  • method - Méthode HTTP : GET, POST, PUT, DELETE, etc.
  • endpoint - Nom de la route Flask
  • status - Code de statut HTTP

Description : Durée des requêtes HTTP pour tous les endpoints API. Instrumenté automatiquement.

flask_http_request_total​

Type : Compteur

Étiquettes :

  • method - Méthode HTTP
  • endpoint - Nom de la route Flask
  • status - Code de statut HTTP

Description : Nombre total de requêtes HTTP par endpoint, méthode et code de statut.

flask_http_request_exceptions_total​

Type : Compteur

Étiquettes :

  • method - Méthode HTTP
  • endpoint - Nom de la route Flask

Description : Nombre total d'exceptions non gérées dans les requêtes HTTP. Indique des bogues ou des erreurs inattendues.

8. Métriques d'Erreur API (Réservées)​

Ces métriques sont définies mais pas actuellement instrumentées. Elles sont réservées pour une utilisation future.

omnicrm_api_errors_total​

Type : Compteur

Étiquettes :

  • endpoint - Endpoint API
  • error_type - Catégorie d'erreur
  • status_code - Code de statut HTTP

Statut : Défini mais pas activement utilisé

omnicrm_api_auth_failures_total​

Type : Compteur

Étiquettes :

  • auth_method - Méthode d'authentification : jwt, api_key, ip_whitelist
  • reason - Raison de l'échec

Statut : Défini mais pas activement utilisé

9. Métrique d'Info de l'Application​

omnicrm_api​

Type : Info

Étiquettes :

  • version - Chaîne de version de l'API
  • environment - Nom de l'environnement : production, staging, development

Description : Métrique d'information de l'API OmniCRM. Définie une fois au démarrage de l'application avec des informations sur la version et l'environnement.

Mises à Jour Périodiques​

update_db_pool_metrics(engine)

Appelée automatiquement toutes les 30 secondes pour mettre à jour les jauges du pool de connexions de la base de données.

Configuration de Prometheus​

Configuration de Scraping​

Ajoutez OmniCRM à votre prometheus.yml :

scrape_configs:
  - job_name: 'omnicrm-api'
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets: ['omnicrm-api:5000']
    metrics_path: '/crm/metrics'

Exemples d'Alerte​

Taux d'Échec de Provisionnement Élevé

- alert: HighProvisionFailureRate
  expr: |
    (
      rate(omnicrm_provision_jobs_total{status="failed"}[5m]) /
      rate(omnicrm_provision_jobs_total[5m])
    ) > 0.1
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Taux d'échec des tâches de provisionnement élevé"
    description: "{{ $value | humanizePercentage }} des tâches de provisionnement échouent"

Pool de Connexion de Base de Données Épuisé

- alert: DatabasePoolExhausted
  expr: omnicrm_db_pool_overflow > 0
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "Débordement du pool de connexions de la base de données détecté"
    description: "Le pool de connexions utilise des connexions de débordement, ce qui peut indiquer que la taille du pool est trop petite"

Requêtes de Base de Données Lentes

- alert: SlowDatabaseQueries
  expr: |
    histogram_quantile(0.99,
      rate(omnicrm_db_query_duration_seconds_bucket[5m])
    ) > 1.0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Requêtes de base de données lentes détectées"
    description: "Le temps de requête au 99e percentile est {{ $value }}s"

API OCS Hors Service

- alert: OCSAPIDown
  expr: |
    (
      rate(omnicrm_ocs_api_calls_total{status="failed"}[5m]) /
      rate(omnicrm_ocs_api_calls_total[5m])
    ) > 0.5
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "Taux d'échec de l'API OCS critique"
    description: "{{ $value | humanizePercentage }} des appels API OCS échouent"

Problèmes de Paiement Stripe

- alert: StripePaymentFailures
  expr: rate(omnicrm_stripe_payment_failures_total[5m]) > 5
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Échecs de paiement Stripe élevés"
    description: "{{ $value }} échecs de paiement par seconde"

Meilleures Pratiques​

Stratégie de Surveillance​

  1. Configurer des Alertes de Base - Configurer des alertes pour des métriques critiques :

    • Taux d'échec de provisionnement > 10%
    • Épuisement du pool de connexions de la base de données
    • Échecs de l'API OCS/CGRateS
    • Erreurs de traitement de paiement Stripe

  2. Suivre les Métriques Commerciales - Surveiller les KPI opérationnels :

    • Revenus traités via Stripe
    • Débit de provisionnement
    • Taux de livraison d'emails aux clients

  3. Surveillance de la Performance - Surveiller la dégradation :

    • Percentiles de temps de réponse API
    • Performance des requêtes de base de données
    • Latence des API externes

  4. Planification de Capacité - Utiliser les métriques pour prévoir :

    • Dimensionnement du pool de connexions de la base de données
    • Mise à l'échelle des travailleurs de tâches en arrière-plan
    • Capacité du serveur API

Conservation des Métriques​

Recommandations de Conservation de Prometheus :

  • 15 jours - Métriques haute résolution (intervalle de scraping de 15s)
  • 90 jours - Métriques sous-échantillonnées (agrégation de 5m)
  • 1 an - Métriques agrégées à long terme (agrégation de 1h)

Utilisez Thanos, Cortex ou VictoriaMetrics pour le stockage à long terme et les requêtes globales.

Dépannage​

Métriques Non Apparentes​

Par défaut, l'endpoint /metrics est uniquement exposé aux sources internes (non publiques). Vous pouvez modifier cela dans votre configuration nginx si nécessaire.

Vérifiez l'endpoint de métriques :

curl http://localhost:5000/crm/metrics

Vérifiez que Prometheus peut extraire :

# Vérifiez la page des cibles de Prometheus
http://prometheus:9090/targets

Métriques Spécifiques Manquantes​

Certaines métriques ne sont créées qu'après leur première utilisation :

  • Les métriques de provisionnement apparaissent après la première tâche de provisionnement
  • Les métriques Stripe apparaissent après le premier paiement
  • Les métriques OCS apparaissent après la première opération de facturation

Problèmes de Haute Cardinalité​

Si Prometheus est lent ou consomme une mémoire excessive, vérifiez les étiquettes de haute cardinalité :

# Comptez les séries temporelles uniques par métrique
count by (__name__) ({__name__=~".+"})

Les métriques avec >10 000 séries peuvent indiquer un problème de cardinalité.

Résumé des Métriques​

Total des Métriques : 34 (31 personnalisées + 3 métriques Flask générées automatiquement)

Par Type :

  • Compteurs : 20
  • Jauges : 5
  • Histogrammes : 8
  • Info : 1

Par Catégorie :

  • Provisionnement : 5 métriques
  • Base de Données : 5 métriques
  • OCS/CGRateS : 5 métriques
  • Stripe : 5 métriques
  • Mailjet : 5 métriques
  • Tâches en Arrière-plan : 4 métriques
  • HTTP/Flask : 3 métriques
  • Info de l'Application : 1 métrique
  • Réservé (utilisation future) : 2 métriques

Documentation Connexe​

Dernière mise à jour le