cw-datadog 2.23.0.2 → 2.23.0.4

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

@@ -1,517 +0,0 @@
-# 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) - 快速开始教程
-
-
-
-
-
-
-
-
-