监控与指标

OmniCRM API 提供全面的基于 Prometheus 的指标，用于监控应用程序性能、业务操作和外部集成。所有指标都在 /crm/metrics 端点以 Prometheus 展示格式公开。

概述

指标系统跟踪：

配置操作 - 作业执行、持续时间、成功/失败率
数据库性能 - 查询时间、连接池健康
外部集成 - OCS/CGRateS、Stripe、Mailjet API 调用
后台作业 - 异步任务执行和性能
HTTP 请求 - API 端点使用情况和响应时间（自动生成）

指标端点

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

格式: Prometheus 展示格式

认证: 指标端点可公开访问以供 Prometheus 抓取。在生产环境中，建议使用防火墙规则或反向代理认证来限制访问。

指标类别

1. 配置指标

配置指标跟踪执行 Ansible 剧本的情况，这些剧本用于配置服务、管理库存和配置外部系统。有关更多详细信息，请参见 Provisioning System 和 Ansible Playbooks。

omnicrm_provision_jobs_total

类型: 计数器

标签:

status - 作业完成状态: success, failed, running

描述: 创建的配置作业总数。当配置作业以其最终状态完成时递增。

omnicrm_provision_job_duration_seconds

类型: 直方图

标签:

playbook - 执行的 Ansible 剧本名称
status - 作业完成状态: success, failed

桶: [1, 5, 10, 30, 60, 120, 180, 300, 600] 秒（1秒到10分钟）

描述: 配置作业完成所需的时间。记录整个剧本执行的持续时间，从开始到结束。

omnicrm_provision_jobs_active

类型: 指标

描述: 当前正在运行的配置作业数量。当作业开始时递增，当作业完成时递减。

omnicrm_provision_tasks_total

类型: 计数器

标签:

playbook - Ansible 剧本名称
status - 任务结果: ok, failed, ignored

描述: 在剧本中执行的 Ansible 任务总数。每个完成的单独任务（成功或失败）递增。

omnicrm_provision_errors_total

类型: 计数器

标签:

error_type - 错误类型: fatal, task_failed, timeout
playbook - Ansible 剧本名称

描述: 按类型统计的配置错误总数。当配置任务失败或执行期间发生致命错误时递增。

2. 数据库指标

数据库指标监控查询性能和连接池健康。OmniCRM 使用 SQLAlchemy 进行自动仪表化。有关数据模型的详细信息，请参见 System Architecture。

omnicrm_db_query_duration_seconds

类型: 直方图

标签:

operation - SQL 操作类型: SELECT, INSERT, UPDATE, DELETE
table - 数据库表名称

桶: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0] 秒

描述: 数据库查询执行时间。通过 SQLAlchemy 事件监听器在每个查询上自动跟踪。

omnicrm_db_pool_size

类型: 指标

描述: 当前数据库连接池大小。池中连接的总数（包括已检查和可用的连接）。

omnicrm_db_pool_overflow

类型: 指标

描述: 当前数据库连接池溢出。超出正常池大小限制创建的连接数量。

omnicrm_db_pool_connections_checked_out

类型: 指标

描述: 当前从池中检查出的连接数量，并被应用程序代码使用。

omnicrm_db_errors_total

类型: 计数器

标签:

error_type - 数据库错误类型
operation - 导致错误的操作: connection_error, query_error, 等等。

描述: 数据库错误的总数。

状态: 已定义但��当前代码中未积极使用（保留供将来使用）

3. OCS/CGRateS 指标

OCS（在线计费系统）指标跟踪与 CGRateS 计费引擎的交互。有关更多详细信息，请参见 Billing Overview 和 CGRateS Integration。

omnicrm_ocs_api_calls_total

类型: 计数器

标签:

method - OCS API 方法: GetBalance, SetBalance, SetAccount, RemoveAccount, 等等。
status - 调用结果: success, failed

描述: OCS/CGRateS API 调用的总数。每次异步 API 调用到 OCS 系统时递增。

omnicrm_ocs_api_duration_seconds

类型: 直方图

标签:

method - OCS API 方法: GetBalance, SetBalance, GetAccount, 等等。

桶: [0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] 秒

描述: OCS/CGRateS API 调用持续时间。记录每个 API 调用所需的时间，包括网络延迟。

omnicrm_ocs_api_errors_total

类型: 计数器

标签:

method - 失败的 OCS API 方法
error_type - 错误类别: timeout, connection_error, json_error, http_error, 等等。

描述: OCS/CGRateS API 错误的总数。当 OCS API 调用因特定错误类型失败时递增。

omnicrm_ocs_balance_queries_total

类型: 计数��

标签:

query_type - 余额查询类型: single_account, multiple_accounts

描述: 对 OCS 的余额查询总数。用于跟踪余额查询操作的使用情况。

omnicrm_ocs_action_plan_operations_total

类型: 计数器

标签:

operation - 行动计划操作: create, remove, query

描述: 行动计划操作的总数。跟踪 CGRateS 行动计划的创建、删除和查询，以进行定期收费。

4. Stripe 支付指标

Stripe 指标跟踪支付处理操作。有关集成详细信息，请参见 Payment System Guide 和 Payment Methods。

omnicrm_stripe_api_calls_total

类型: 计数器

标签:

operation - Stripe 操作: create_customer, charge, refund, update_payment_method, 等等。
status - 操作结果: success, failed

描述: Stripe API 调用的总数。每次支付处理操作时递增。

omnicrm_stripe_api_duration_seconds

类型: 直方图

标签:

operation - Stripe 操作类型

桶: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] 秒

描述: Stripe API 调用持续时间，包括网络延迟。

omnicrm_stripe_api_errors_total

类型: 计数器

标签:

operation - 失败的 Stripe 操作
error_type - 错误类别: card_declined, network_error, api_error, 等等。

描述: Stripe API 错误的总数。当支付操作失败时递增。

omnicrm_stripe_payment_amount_cents

类型: 计数器

标签:

payment_type - 支付方向: charge, refund

描述: 通过 Stripe 处理的总支付金额（以美分为单位）。用于跟踪交易量和收入。

omnicrm_stripe_payment_failures_total

类型: 计数器

标签:

reason - 失败原因: card_declined, insufficient_funds, expired_card, 等等。

描述: 按拒绝代码分类的 Stripe 支付失败总数。

5. Mailjet 邮件指标

Mailjet 指标跟踪电子邮件投递操作。有关配置详细信息，请参见 Mailjet Integration。

omnicrm_mailjet_api_calls_total

类型: 计数器

标签:

email_type - 邮件模板类型: welcome, user_welcome, invoice, notification
status - 投递结果: success, failed

描述: Mailjet API 调用的总数。通过 @track_mailjet_call 装饰器跟踪。

omnicrm_mailjet_api_duration_seconds

类型: 直方图

标签:

email_type - 邮件模板类型

桶: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0] 秒

描述: Mailjet API 调用持续��间。通过 Mailjet API 提交电子邮件所需的时间（不是投递时间）。

omnicrm_mailjet_api_errors_total

类型: 计数器

标签:

email_type - 邮件模板类型
error_type - 错误类别

描述: Mailjet API 错误的总数。当电子邮件发送失败时递增。

omnicrm_mailjet_emails_sent_total

类型: 计数器

标签:

email_type - 邮件模板类型
template_id - Mailjet 模板 ID

描述: 通过 Mailjet 成功发送的电子邮件总数。与 API 调用不同，因为一次调用可以发送给多个收件人。

omnicrm_mailjet_email_recipients_total

类型: 计数器

标签:

email_type - 邮件模板类型

描述: 所有已发送电子邮件的总收件人数量。

6. 后台作业指标

后台作业指标跟踪异步操作，如剧本链和计划任务。有关后台作业的详细信息，请参见 Provisioning System。

omnicrm_background_jobs_total

类型: 计数器

标签:

job_type - 作业类别: playbook_single, playbook_chain, periodic_task

描述: 启动的后台作业总数。通过 BackgroundJobTimer 上下文管理器跟踪。

omnicrm_background_jobs_active

类型: 指标

标签:

job_type - 作业类别

描述: 当前正在运行的后台作业数量。在作业开始时递增，在作业完成时递减。

omnicrm_background_job_duration_seconds

类型: 直方图

标签:

job_type - 作业类别
status - 作业结果: success, failed

桶: [1, 5, 10, 30, 60, 120, 180, 300, 600, 1800, 3600] 秒（1秒到1小时）

描述: 后台作业执行时间。包括多步骤操作的完整持续时间。

omnicrm_background_job_errors_total

类型: 计数器

标签:

job_type - 作业类别
error_type - 错误类别

描述: 后台作业错误的总数。当后台作业因异常失败时递增。

7. Flask HTTP 指标（自动生成）

这些指标由 prometheus-flask-exporter 库自动生成，跟踪所有对 API 的 HTTP 请求。

flask_http_request_duration_seconds

类型: 直方图

标签:

method - HTTP 方法: GET, POST, PUT, DELETE, 等等。
endpoint - Flask 路由名称
status - HTTP 状态码

描述: 所有 API 端点的 HTTP 请求持续时间。自动仪表化。

flask_http_request_total

类型: 计数器

标签:

method - HTTP 方法
endpoint - Flask 路由名称
status - HTTP 状态码

描述: 按端点、方法和状态码统计的总 HTTP 请求数。

flask_http_request_exceptions_total

类型: 计数器

标签:

method - HTTP 方法
endpoint - Flask 路由名称

描述: HTTP 请求中的总未处理异常。指示错误或意外错误。

8. API 错误指标（保留）

这些指标已定义但当前未仪表化。它们保留供将来使用。

omnicrm_api_errors_total

类型: 计数器

标签:

endpoint - API 端点
error_type - 错误类别
status_code - HTTP 状态码

状态: 已定义但未积极使用

omnicrm_api_auth_failures_total

类型: 计数器

标签:

auth_method - 认证方法: jwt, api_key, ip_whitelist
reason - 失败原因

状态: 已定义但未积极使用

9. 应用程序信息指标

omnicrm_api

类型: 信息

标签:

version - API 版本字符串
environment - 环境名称: production, staging, development

描述: OmniCRM API 信息指标。在应用程序启动时设置一次，包含版本和环境信息。

定期更新

update_db_pool_metrics(engine)

每 30 秒自动调用一次以更新数据库连接池指标。

Prometheus 配置

抓取配置

将 OmniCRM 添加到您的 prometheus.yml：

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

示例警报

高配置失败率

- 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: "高配置作业失败率"
    description: "{{ $value | humanizePercentage }} 的配置作业失败"

数据库连接池耗尽

- alert: DatabasePoolExhausted
  expr: omnicrm_db_pool_overflow > 0
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "检测到数据库连接池溢出"
    description: "连接池正在使用溢出连接，可能表示池大小过小"

慢数据库查询

- alert: SlowDatabaseQueries
  expr: |
    histogram_quantile(0.99,
      rate(omnicrm_db_query_duration_seconds_bucket[5m])
    ) > 1.0
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "检测到慢数据库查询"
    description: "第 99 百分位查询时间为 {{ $value }}s"

OCS API 不可用

- 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: "OCS API 失败率严重"
    description: "{{ $value | humanizePercentage }} 的 OCS API 调用失败"

Stripe 支付问题

- alert: StripePaymentFailures
  expr: rate(omnicrm_stripe_payment_failures_total[5m]) > 5
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Stripe 支付失败率上升"
    description: "{{ $value }} 每秒支付失败"

最佳实践

监控策略

设置核心警报 - 配置关键指标的警报：
- 配置失败率 > 10%
- 数据库连接池耗尽
- OCS/CGRateS API 失败
- Stripe 支付处理错误
跟踪业务指标 - 监控操作 KPI：
- 通过 Stripe 处理的收入
- 配置吞吐量
- 客户电子邮件投递率
性能监控 - 关注性能下降：
- API 响应时间百分位
- 数据库查询性能
- 外部 API 延迟
容量规划 - 使用指标进行预测：
- 数据库连接池大小
- 后台作业工作者扩展
- API 服务器容量

指标保留

Prometheus 保留建议:

15 天 - 高分辨率指标（15 秒抓取间隔）
90 天 - 降采样指标（5 分钟聚合）
1 年 - 长期聚合指标（1 小时聚合）

使用 Thanos、Cortex 或 VictoriaMetrics 进行长期��储和全局查询。

故障排除

指标未出现

默认情况下，/metrics 端点仅对内部（非公共地址空间）源公开。如果需要，您可以在 nginx 配置中更改此设置。

检查指标端点:

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

验证 Prometheus 是否可以抓取:

# 检查 Prometheus 目标页面
http://prometheus:9090/targets

缺少特定指标

某些指标仅在首次使用后创建：

配置指标在首次配置作业后出现
Stripe 指标在首次支付后出现
OCS 指标在首次计费操作后出现

高基数问题

如果 Prometheus 运行缓慢或消耗过多内存，请检查高基数标签：

# 计算每个指标的唯一时间序列
count by (__name__) ({__name__=~".+"})

具有 >10,000 个系列的指标可能表示基数问题。

指标摘要

总指标: 34（31 个自定义 + 3 个自动生成的 Flask 指标）

按类型:

计数器: 20
指标: 5
直方图: 8
信息: 1

按类别:

配置: 5 个指标
数据库: 5 个指标
OCS/CGRateS: 5 个指标
Stripe: 5 个指标
Mailjet: 5 个指标
后台作业: 4 个指标
HTTP/Flask: 3 个指标
应用程序信息: 1 个指标
保留（将来使用）: 2 个��标

概述​

指标端点​

指标类别​

1. 配置指标​

omnicrm_provision_jobs_total​

omnicrm_provision_job_duration_seconds​

omnicrm_provision_jobs_active​

omnicrm_provision_tasks_total​

omnicrm_provision_errors_total​

2. 数据库指标​

omnicrm_db_query_duration_seconds​

omnicrm_db_pool_size​

omnicrm_db_pool_overflow​

omnicrm_db_pool_connections_checked_out​

omnicrm_db_errors_total​

3. 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. 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. 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. 后台作业指标​

omnicrm_background_jobs_total​

omnicrm_background_jobs_active​

omnicrm_background_job_duration_seconds​

omnicrm_background_job_errors_total​

7. Flask HTTP 指标（自动生成）​

flask_http_request_duration_seconds​

flask_http_request_total​

flask_http_request_exceptions_total​

8. API 错误指标（保留）​

omnicrm_api_errors_total​

omnicrm_api_auth_failures_total​

9. 应用程序信息指标​

omnicrm_api​

定期更新​

Prometheus 配置​

抓取配置​

示例警报​

最佳实践​

监控策略​

指标保留​

故障排除​

指标未出现​

缺少特定指标​

高基数问题​

指标摘要​

相关文档​

概述

指标端点

指标类别

1. 配置指标

omnicrm_provision_jobs_total

omnicrm_provision_job_duration_seconds

omnicrm_provision_jobs_active

omnicrm_provision_tasks_total

omnicrm_provision_errors_total

2. 数据库指标

omnicrm_db_query_duration_seconds

omnicrm_db_pool_size

omnicrm_db_pool_overflow

omnicrm_db_pool_connections_checked_out

omnicrm_db_errors_total

3. 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. 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. 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. 后台作业指标

omnicrm_background_jobs_total

omnicrm_background_jobs_active

omnicrm_background_job_duration_seconds

omnicrm_background_job_errors_total

7. Flask HTTP 指标（自动生成）

flask_http_request_duration_seconds

flask_http_request_total

flask_http_request_exceptions_total

8. API 错误指标（保留）

omnicrm_api_errors_total

omnicrm_api_auth_failures_total

9. 应用程序信息指标

omnicrm_api

定期更新

Prometheus 配置

抓取配置

示例警报

最佳实践

监控策略

指标保留

故障排除

指标未出现

缺少特定指标

高基数问题

指标摘要

相关文档