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.

Aperçu

Le système de métriques suit :

Opérations de Provisionnement - Exécution de 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 - OCS/CGRateS, appels API Stripe, Mailjet
Tâches en Arrière-plan - Exécution de tâches asynchrones et performance
Requêtes HTTP - Utilisation des endpoints API et temps de réponse (généré automatiquement)

Endpoint des Métriques

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

Format : Format d'exposition Prometheus

Authentification : L'endpoint des métriques est accessible publiquement pour le scraping par Prometheus. En production, il est recommandé de restreindre l'accès �� l'aide de règles de pare-feu ou d'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 la 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 emprunté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 empruntées au pool 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 ayant 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 Aperçu 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 à 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 de plans d'action CGRateS pour des charges récurrentes.

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 de 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 en plusieurs é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 vers 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 d'état 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 d'état HTTP

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

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 d'état 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 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

Configurer des Alertes de Base - Configurer des alertes pour les 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 des paiements Stripe
Suivre les Métriques Commerciales - Surveiller les KPI opérationnels :
- Revenus traités via Stripe
- Débit de provisionnement
- Taux de livraison des emails aux clients
Surveillance de la Performance - Surveiller la dégradation :
- Percentiles du temps de réponse de l'API
- Performance des requêtes de base de données
- Latence des API externes
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

Rétention des Métriques

Recommandations de Rétention 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 des métriques :

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

Vérifiez que Prometheus peut scraper :

# 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 Cardinalité Élevée

Si Prometheus est lent ou consomme une mémoire excessive, vérifiez les étiquettes à 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

Architecture du Système - Conception globale du système et relations entre les composants
Système de Provisionnement - Flux de travail de provisionnement et exécution des tâches
Playbooks Ansible - Structure et exécution des playbooks
Documentation API - Endpoints API et authentification
Aperçu de la Facturation - Système de facturation et de tarification
Guide du Système de Paiement - Intégration Stripe et traitement des paiements
Intégration Mailjet - Configuration du service email
Configuration d'Administration - Options de configuration du système

Aperçu​

Endpoint des Métriques​

Catégories de Métriques​

1. Métriques de Provisionnement​

omnicrm_provision_jobs_total​

omnicrm_provision_job_duration_seconds​

omnicrm_provision_jobs_active​

omnicrm_provision_tasks_total​

omnicrm_provision_errors_total​

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

omnicrm_db_query_duration_seconds​

omnicrm_db_pool_size​

omnicrm_db_pool_overflow​

omnicrm_db_pool_connections_checked_out​

omnicrm_db_errors_total​

3. Métriques OCS/CGRateS​

omnicrm_ocs_api_calls_total​

omnicrm_ocs_api_duration_seconds​

omnicrm_ocs_api_errors_total​

omnicrm_ocs_balance_queries_total​

omnicrm_ocs_action_plan_operations_total​

4. Métriques de Paiement Stripe​

omnicrm_stripe_api_calls_total​

omnicrm_stripe_api_duration_seconds​

omnicrm_stripe_api_errors_total​

omnicrm_stripe_payment_amount_cents​

omnicrm_stripe_payment_failures_total​

5. Métriques d'Email Mailjet​

omnicrm_mailjet_api_calls_total​

omnicrm_mailjet_api_duration_seconds​

omnicrm_mailjet_api_errors_total​

omnicrm_mailjet_emails_sent_total​

omnicrm_mailjet_email_recipients_total​

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

omnicrm_background_jobs_total​

omnicrm_background_jobs_active​

omnicrm_background_job_duration_seconds​

omnicrm_background_job_errors_total​

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

flask_http_request_duration_seconds​

flask_http_request_total​

flask_http_request_exceptions_total​

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

omnicrm_api_errors_total​

omnicrm_api_auth_failures_total​

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

omnicrm_api​

Mises à Jour Périodiques​

Configuration Prometheus​

Configuration de Scraping​

Exemples d'Alerte​

Meilleures Pratiques​

Stratégie de Surveillance​

Rétention des Métriques​

Dépannage​

Métriques Non Apparentes​

Métriques Spécifiques Manquantes​

Problèmes de Cardinalité Élevée​

Résumé des Métriques​

Documentation Connexe​

Aperçu

Endpoint des Métriques

Catégories de Métriques

1. Métriques de Provisionnement

omnicrm_provision_jobs_total

omnicrm_provision_job_duration_seconds

omnicrm_provision_jobs_active

omnicrm_provision_tasks_total

omnicrm_provision_errors_total

2. Métriques de Base de Données

omnicrm_db_query_duration_seconds

omnicrm_db_pool_size

omnicrm_db_pool_overflow

omnicrm_db_pool_connections_checked_out

omnicrm_db_errors_total

3. Métriques OCS/CGRateS

omnicrm_ocs_api_calls_total

omnicrm_ocs_api_duration_seconds

omnicrm_ocs_api_errors_total

omnicrm_ocs_balance_queries_total

omnicrm_ocs_action_plan_operations_total

4. Métriques de Paiement Stripe

omnicrm_stripe_api_calls_total

omnicrm_stripe_api_duration_seconds

omnicrm_stripe_api_errors_total

omnicrm_stripe_payment_amount_cents

omnicrm_stripe_payment_failures_total

5. Métriques d'Email Mailjet

omnicrm_mailjet_api_calls_total

omnicrm_mailjet_api_duration_seconds

omnicrm_mailjet_api_errors_total

omnicrm_mailjet_emails_sent_total

omnicrm_mailjet_email_recipients_total

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

omnicrm_background_jobs_total

omnicrm_background_jobs_active

omnicrm_background_job_duration_seconds

omnicrm_background_job_errors_total

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

flask_http_request_duration_seconds

flask_http_request_total

flask_http_request_exceptions_total

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

omnicrm_api_errors_total

omnicrm_api_auth_failures_total

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

omnicrm_api

Mises à Jour Périodiques

Configuration Prometheus

Configuration de Scraping

Exemples d'Alerte

Meilleures Pratiques

Stratégie de Surveillance

Rétention des Métriques

Dépannage

Métriques Non Apparentes

Métriques Spécifiques Manquantes

Problèmes de Cardinalité Élevée

Résumé des Métriques

Documentation Connexe