cw-datadog 2.23.0.2

data/lib/datadog/core/cloudwise/IMPLEMENTATION_V2.md

@@ -0,0 +1,517 @@
+# Cloudwise 实现方案 V2
+
+## 📋 需求变更总结
+
+根据最新需求，重新实现了 Cloudwise 集成的初始化和数据采集控制逻辑。
+
+### 核心变更
+
+1. **初始化顺序**：Cloudwise 必须**先于** Datadog 其他组件初始化
+2. **数据采集控制**：只有当 **Host ID + Heartbeat + License** 三者都正常时，才可以采集和上报数据
+3. **失败重试间隔**：从 2秒/2分钟 统一调整为 **30秒**
+4. **应用注册周期**：从 10分钟 调整为 **3分钟**
+
+---
+
+## 🔄 初始化流程
+
+```
+应用启动
+    ↓
+┌──────────────────────────────────────────┐
+│  Cloudwise 组件初始化（优先执行）          │
+└──────────────────────────────────────────┘
+    ↓
+[1] Host ID Worker 启动
+    ├─ 调用 POST /v2/app/generateHostId
+    ├─ 成功条件：success=true && code=1000
+    ├─ 成功：获取 account_id，设置 ENV['CLOUDWISE_ACCOUNT_ID']，标记 host_id_ready=true，停止 Worker
+    ├─ 失败：30秒后重试
+    └─ ⚠️  失败时：数据不采集，不上报，后续步骤不执行
+    ↓
+[2] Heartbeat Worker 启动
+    ├─ 等待 Host ID 就绪
+    ├─ 调用 POST /api/v1/agent/heartbeat
+    ├─ 执行周期：60秒
+    ├─ 成功条件：success=true && code=1000
+    ├─ 成功：标记 heartbeat_active=true
+    ├─ 失败：30秒后重试，失败3次标记 heartbeat_active=false
+    └─ ⚠️  heartbeat_active=false 时：数据不采集，不上报
+    ↓
+[3] Application Registration Worker 启动
+    ├─ 等待 Host ID 就绪
+    ├─ 调用 POST /api/v1/application/register
+    ├─ 执行周期：3分钟
+    ├─ 成功条件：success=true && code=1000
+    ├─ 成功：标记 app_registered=true
+    ├─ 失败：继续定时重试（3分钟后）
+    └─ ✅ 注册失败不影响数据采集
+    ↓
+[4] License Worker 启动
+    ├─ 等待 Host ID 就绪
+    ├─ 调用 POST /api/v1/license/verify
+    ├─ 执行周期：5分钟
+    ├─ 成功条件：success=true && code=1000
+    ├─ 成功：标记 license_valid=true
+    ├─ 失败：累计失败3次标记 license_valid=false
+    └─ ⚠️  license_valid=false 时：数据不采集，不上报
+    ↓
+┌──────────────────────────────────────────┐
+│  Datadog 其他组件初始化                    │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## 🎯 核心实现
+
+### 1. ProbeState（探针状态管理器）
+
+**文件**: `lib/datadog/core/cloudwise/probe_state.rb`
+
+**职责**: 追踪所有影响数据采集的条件
+
+```ruby
+class ProbeState
+  # 三个关键状态
+  @host_id_ready      # Host ID 是否就绪
+  @heartbeat_active   # 心跳是否正常
+  @license_valid      # License 是否有效
+  @app_registered     # 应用是否已注册（不影响采集）
+
+  # 数据采集判断
+  def can_collect_data?
+    @host_id_ready && @heartbeat_active && @license_valid
+  end
+end
+```
+
+**关键方法**:
+- `mark_host_id_ready!` / `mark_host_id_failed!`
+- `mark_heartbeat_active!` / `mark_heartbeat_inactive!`
+- `mark_license_valid!` / `mark_license_invalid!`
+- `can_collect_data?` - **核心判断**：三者都满足才返回 true
+
+---
+
+### 2. HostIdWorker（Host ID 生成）
+
+**文件**: `lib/datadog/core/cloudwise/host_id_worker.rb`
+
+**配置**:
+- 重试间隔：**30秒**
+- 成功条件：`code == 1000`
+
+**逻辑**:
+```ruby
+result = client.generate_host_id
+
+if result[:success] && result[:code] == 1000 && client.account_id
+  # 成功
+  probe_state.mark_host_id_ready!
+  ENV['CLOUDWISE_ACCOUNT_ID'] = client.account_id
+  stop_loop  # 只需成功一次
+else
+  # 失败，30秒后重试
+  probe_state.mark_host_id_failed!
+  # 数据不采集
+end
+```
+
+---
+
+### 3. HeartbeatWorker（心跳）
+
+**文件**: `lib/datadog/core/cloudwise/heartbeat_worker.rb`
+
+**配置**:
+- 执行周期：**60秒**
+- 失败重试间隔：**30秒**
+- 最大失败次数：**3次**
+- 成功条件：`code == 1000`
+
+**逻辑**:
+```ruby
+result = client.heartbeat
+
+if !result[:success]
+  # 接口请求失败
+  @failure_count += 1
+  if @failure_count >= 3
+    probe_state.mark_heartbeat_inactive!
+    # 数据不采集
+  end
+elsif result[:code] != 1000
+  # 接口成功但 code 不对
+  probe_state.mark_heartbeat_inactive!
+  # 数据不采集
+else
+  # 成功
+  probe_state.mark_heartbeat_active!
+  @failure_count = 0
+end
+```
+
+**关键点**:
+- 接口请求失败：累计失败次数，达到3次后标记为 inactive
+- 接口成功但 code ≠ 1000：立即标记为 inactive
+- 任何一次成功（code == 1000）：恢复 active，重置失败计数
+
+---
+
+### 4. LicenseWorker（License 校验）
+
+**文件**: `lib/datadog/core/cloudwise/license_worker.rb`
+
+**配置**:
+- 执行周期：**5分钟**
+- 最大失败次数：**3次**
+- 成功条件：`code == 1000`
+
+**逻辑**:
+```ruby
+result = client.verify_license
+
+if !result[:success]
+  # 接口请求失败
+  @failure_count += 1
+  if @failure_count >= 3
+    probe_state.mark_license_invalid!
+    # 数据不采集
+  end
+elsif result[:code] == 1000
+  # License 校验成功
+  probe_state.mark_license_valid!
+  @failure_count = 0
+else
+  # License 校验失败
+  probe_state.mark_license_invalid!
+  # 数据不采集
+end
+```
+
+**关键点**:
+- 接口请求失败：累计失败3次后标记为 invalid
+- code ≠ 1000：立即标记为 invalid
+- 任何一次成功（code == 1000）：恢复 valid
+
+---
+
+### 5. AppRegistrationWorker（应用注册）
+
+**文件**: `lib/datadog/core/cloudwise/app_registration_worker.rb`
+
+**配置**:
+- 执行周期：**3分钟**
+- 成功条件：`code == 1000`
+
+**逻辑**:
+```ruby
+result = client.register_application
+
+if result[:success] && result[:code] == 1000
+  # 注册成功
+  probe_state.mark_app_registered!
+else
+  # 注册失败，3分钟后重试
+  probe_state.mark_app_unregistered!
+  # ⚠️ 注册失败不影响数据采集
+end
+```
+
+**关键点**:
+- 注册失败**不影响**数据采集
+- 失败后继续定时重试（3分钟周期）
+
+---
+
+### 6. Component（组件管理器）
+
+**文件**: `lib/datadog/core/cloudwise/component.rb`
+
+**初始化顺序**:
+```ruby
+def start
+  # 1. Host ID Worker（30秒重试）
+  @host_id_worker.start
+  
+  # 2. Heartbeat Worker（60秒周期）
+  @heartbeat_worker.start
+  
+  # 3. Application Registration Worker（3分钟周期）
+  @app_registration_worker.start
+  
+  # 4. License Worker（5分钟周期）
+  @license_worker.start
+end
+```
+
+**状态查询**:
+```ruby
+def status
+  {
+    host_id_ready: probe_state.host_id_ready?,
+    heartbeat_active: probe_state.heartbeat_active?,
+    license_valid: probe_state.license_valid?,
+    app_registered: probe_state.app_registered?,
+    can_collect_data: probe_state.can_collect_data?  # 核心判断
+  }
+end
+```
+
+---
+
+## 📊 数据采集控制
+
+### 在 traces.rb 中的集成
+
+**文件**: `lib/datadog/tracing/transport/http/traces.rb`
+
+```ruby
+def call(env, &block)
+  # 检查探针状态
+  if cloudwise_probe_suspended?
+    Datadog.logger.debug { 'Cloudwise: Probe suspended, skipping trace submission' }
+    return build_mock_response(env)
+  end
+
+  # 正常发送 traces
+  # ...
+end
+
+def cloudwise_probe_suspended?
+  return false unless defined?(Datadog.components)
+  return false unless Datadog.components.respond_to?(:cloudwise)
+  
+  cloudwise = Datadog.components.cloudwise
+  return false unless cloudwise&.enabled?
+  
+  # 核心判断：can_collect_data?
+  cloudwise.probe_state.suspended?  # 即 !can_collect_data?
+end
+```
+
+---
+
+## 🔑 关键配置
+
+### 环境变量
+
+```bash
+# Cloudwise 配置
+export DD_CLOUDWISE_ENABLED=true
+export DD_CLOUDWISE_BASE_URL=https://api.cloudwise.com
+export DD_CLOUDWISE_SERVER_NAME=my-ruby-app
+export DD_CLOUDWISE_LICENSE_KEY=your-license-key
+
+# 可选：自定义周期
+export DD_CLOUDWISE_HEARTBEAT_INTERVAL=60          # 默认 60秒
+export DD_CLOUDWISE_LICENSE_CHECK_INTERVAL=300     # 默认 5分钟
+export DD_CLOUDWISE_APP_REGISTRATION_INTERVAL=180  # 默认 3分钟
+
+# 自动设置（由 Host ID Worker 设置）
+# CLOUDWISE_ACCOUNT_ID  # 成功后自动设置
+```
+
+### 配置文件
+
+```ruby
+Datadog.configure do |c|
+  c.cloudwise.enabled = true
+  c.cloudwise.base_url = 'https://api.cloudwise.com'
+  c.cloudwise.server_name = 'my-ruby-app'
+  c.cloudwise.license_key = 'your-license-key'
+  
+  # 可选
+  c.cloudwise.heartbeat_interval = 60
+  c.cloudwise.license_check_interval = 300
+  c.cloudwise.app_registration_interval = 180
+end
+```
+
+---
+
+## ⚠️ 重要注意事项
+
+### 1. 初始化顺序
+
+❗ **Cloudwise 组件必须在 Datadog 其他组件之前初始化**
+
+```ruby
+# 正确的初始化顺序
+Datadog.configure do |c|
+  # 1. 先配置 Cloudwise
+  c.cloudwise.enabled = true
+  c.cloudwise.base_url = 'https://api.cloudwise.com'
+  # ...
+  
+  # 2. 再配置其他 Datadog 组件
+  c.service = 'my-app'
+  c.tracing.enabled = true
+  # ...
+end
+```
+
+### 2. 数据采集条件
+
+数据采集**必须同时满足三个条件**：
+
+1. ✅ `host_id_ready == true`
+2. ✅ `heartbeat_active == true`
+3. ✅ `license_valid == true`
+
+任何一个条件不满足，数据都不会被采集和上报。
+
+### 3. 应用注册
+
+❗ 应用注册失败**不影响**数据采集，只会在日志中记录警告并继续重试。
+
+### 4. 失败重试
+
+- **Host ID**：30秒重试，直到成功
+- **Heartbeat**：接口失败累计3次后标记为 inactive，但Worker继续运行（60秒周期）
+- **License**：接口失败累计3次后标记为 invalid，但Worker继续运行（5分钟周期）
+- **App Registration**：失败后继续定时重试（3分钟周期）
+
+### 5. 恢复机制
+
+- **Heartbeat**：任何一次成功（code == 1000）即恢复 active
+- **License**：任何一次成功（code == 1000）即恢复 valid
+
+---
+
+## 📝 日志示例
+
+### 启动时
+
+```
+============================================================
+🚀 Starting Cloudwise Component
+   Initialization Order: Host ID → Heartbeat → App Registration → License
+============================================================
+📍 Step 1: Starting Host ID generation worker (30s retry)...
+💓 Step 2: Starting Heartbeat worker (60s interval, 30s retry)...
+📝 Step 3: Starting Application registration worker (3 min interval)...
+🔑 Step 4: Starting License verification worker (5 min interval)...
+============================================================
+✅ Cloudwise Component started successfully
+   Data collection will be enabled when: Host ID + Heartbeat + License are ready
+============================================================
+```
+
+### Host ID 成功
+
+```
+INFO -- : Cloudwise: Host ID generated successfully, account_id: acc-1234567890-123
+INFO -- : ✅ Cloudwise: Host ID ready
+INFO -- : 🔴 Cloudwise: Probe SUSPENDED - data collection disabled (Heartbeat inactive, License invalid)
+```
+
+### Heartbeat 成功
+
+```
+DEBUG -- : Cloudwise: Heartbeat successful
+INFO -- : ✅ Cloudwise: Heartbeat active
+INFO -- : 🔴 Cloudwise: Probe SUSPENDED - data collection disabled (License invalid)
+```
+
+### License 成功
+
+```
+INFO -- : Cloudwise: License valid
+INFO -- : ✅ Cloudwise: License valid
+INFO -- : 🟢 Cloudwise: Probe ACTIVE - data collection enabled
+```
+
+### 数据采集被阻止
+
+```
+DEBUG -- : Cloudwise: Probe suspended, skipping trace submission
+```
+
+---
+
+## 🧪 测试
+
+### Mock API Server
+
+```bash
+cd lib/datadog/core/cloudwise
+ruby mock_api_server.rb
+```
+
+### 运行测试
+
+```bash
+cd lib/datadog/core/cloudwise
+ruby test_integration.rb
+```
+
+### 状态检查
+
+```ruby
+status = Datadog.components.cloudwise.status
+
+puts "Host ID Ready: #{status[:host_id_ready]}"
+puts "Heartbeat Active: #{status[:heartbeat_active]}"
+puts "License Valid: #{status[:license_valid]}"
+puts "Can Collect Data: #{status[:can_collect_data]}"
+```
+
+---
+
+## 📁 文件清单
+
+### 核心文件
+
+1. `lib/datadog/core/cloudwise/probe_state.rb` - 探针状态管理 ⭐
+2. `lib/datadog/core/cloudwise/client.rb` - HTTP 客户端
+3. `lib/datadog/core/cloudwise/host_id_worker.rb` - Host ID 生成 ⭐
+4. `lib/datadog/core/cloudwise/heartbeat_worker.rb` - 心跳 ⭐
+5. `lib/datadog/core/cloudwise/license_worker.rb` - License 校验 ⭐
+6. `lib/datadog/core/cloudwise/app_registration_worker.rb` - 应用注册
+7. `lib/datadog/core/cloudwise/component.rb` - 组件管理器 ⭐
+8. `lib/datadog/tracing/transport/http/traces.rb` - Trace 上报拦截 ⭐
+
+### 文档文件
+
+- `README.md` - 基础说明
+- `IMPLEMENTATION_V2.md` - 本文档（V2 实现方案）
+- `INTEGRATION_GUIDE.md` - 集成指南
+- `QUICKSTART.md` - 快速开始
+
+### 测试文件
+
+- `mock_api_server.rb` - Mock API 服务器
+- `test_integration.rb` - 集成测试脚本
+
+---
+
+## ✅ V2 改进总结
+
+相比 V1 版本，V2 做了以下改进：
+
+1. ✅ **简化状态管理**：三个核心状态（Host ID、Heartbeat、License），清晰明了
+2. ✅ **统一重试间隔**：从 2秒/2分钟 统一为 30秒，更合理
+3. ✅ **优化失败处理**：累计失败次数而非每次都重试多次
+4. ✅ **明确恢复机制**：任何一次成功即可恢复
+5. ✅ **应用注册独立**：注册失败不影响数据采集
+6. ✅ **初始化顺序明确**：Cloudwise 优先于 Datadog 其他组件
+7. ✅ **日志信息丰富**：清晰显示当前状态和失败原因
+
+---
+
+## 🔗 相关文档
+
+- [README.md](./README.md) - 基础使用说明
+- [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md) - 详细集成指南
+- [QUICKSTART.md](./QUICKSTART.md) - 快速开始教程
+
+
+
+
+
+
+
+
+