cw-datadog 2.23.0.2

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

@@ -0,0 +1,722 @@
+# Cloudwise Integration
+
+## 概述
+
+Cloudwise 集成提供了探针管理、License 校验和应用注册功能。
+
+**重要特性**：
+- **异步初始化**: 不阻塞应用启动
+- **延迟加载**: Datadog 组件在 Host ID 就绪后才初始化
+- **无限重试**: Host ID 获取失败时会一直重试
+- **正常服务**: 应用在监控组件初始化期间可以正常处理请求
+
+## 功能特性
+
+### 1. Host ID 生成
+- **接口**: `POST /v2/app/generateHostId`
+- **执行时机**: 应用启动时（后台异步执行）
+- **重试策略**: 失败时每 30 秒重试一次，**无限重试直到成功**
+- **阻塞行为**: 
+  - ✅ 不阻塞应用启动
+  - ❌ 阻塞 Cloudwise 和 Datadog 组件的初始化
+  - ✅ 应用可以正常处理请求
+- **环境变量**: 
+  - 成功后自动设置 `ENV['CLOUDWISE_ACCOUNT_ID']`
+  - **这是 Cloudwise 正常工作的前提条件**
+
+### 2. 心跳注册
+- **接口**: `POST /api/v1/agent/heartbeat`
+- **执行时机**: Host ID 成功后**首先启动**（阻塞后续初始化）
+- **执行周期**: 30 秒
+- **重试策略**: 同一周期内失败时间隔 30 秒重试，最多 3 次
+- **失败处理**:
+  - 接口成功但 code ≠ 1000：标记为 inactive，数据不采集和上报
+  - 接口连续失败 3 次：标记为 inactive，失败计数重置为 0
+  - 下个周期（30s 后）继续尝试，直到成功
+  - 任何周期返回 code = 1000：标记为 active，继续后续初始化
+- **阻塞行为**: 必须首次成功（code = 1000）才能继续后续流程
+
+### 3. 应用注册
+- **接口**: `POST /api/v1/application/register`
+- **执行时机**: Heartbeat 成功后启动（**不阻塞**后续初始化）
+- **执行周期**: 3 分钟
+- **重试策略**: 失败时在下个周期继续尝试
+- **失败处理**:
+  - 成功：标记为 registered
+  - 失败：标记为 unregistered，3 分钟后再次尝试
+- **阻塞行为**: **不阻塞**，后台运行，失败不影响后续流程
+
+### 4. License 校验
+- **接口**: `POST /api/v1/license/verify`
+- **执行时机**: App Registration 启动后**立即启动**（阻塞后续初始化）
+- **执行周期**: 5 分钟
+- **重试策略**: 每个周期尝试一次，失败累计计数
+- **失败处理**:
+  - 接口成功但 code ≠ 1000：标记为 invalid，数据不采集和上报
+  - 接口连续失败 3 次：标记为 invalid，失败计数重置为 0
+  - 下个周期（5min 后）继续尝试，直到成功
+  - 任何周期返回 code = 1000：标记为 valid，继续后续初始化
+- **阻塞行为**: 必须首次成功（code = 1000）才能初始化 Datadog 组件
+
+## 配置方式
+
+### 环境变量配置
+
+```bash
+# 必需配置
+export DD_CLOUDWISE_ENABLED=true
+export DD_CLOUDWISE_LICENSE_KEY=your-license-key-here
+export DD_SERVICE=my-ruby-app              # 用作 server_name
+export DD_AGENT_HOST=127.0.0.1             # API base URL 的 host 部分
+export DD_AGENT_PORT=8126                  # API base URL 的 port 部分
+
+# 可选配置（带默认值）
+export DD_CLOUDWISE_HEARTBEAT_INTERVAL=30        # 默认: 30秒
+export DD_CLOUDWISE_LICENSE_CHECK_INTERVAL=300   # 默认: 5分钟
+export DD_CLOUDWISE_APP_REGISTRATION_INTERVAL=180 # 默认: 3分钟
+```
+
+**说明**：
+- `DD_SERVICE`: 服务名称，用作 Cloudwise API 的 `server_name` 参数
+- `DD_AGENT_HOST` + `DD_AGENT_PORT`: 组合成 `base_url`，例如 `http://127.0.0.1:8126`
+
+### 代码配置
+
+```ruby
+require 'datadog'
+
+Datadog.configure do |c|
+  # Cloudwise 配置
+  c.cloudwise.enabled = true
+  c.cloudwise.license_key = 'your-license-key-here'
+  
+  # 可选: 自定义间隔时间
+  c.cloudwise.heartbeat_interval = 30           # 30秒
+  c.cloudwise.license_check_interval = 300      # 5分钟
+  c.cloudwise.app_registration_interval = 180   # 3分钟
+  
+  # Datadog 通用配置（用于 Cloudwise）
+  c.service = 'my-ruby-app'        # server_name
+  c.agent.host = '127.0.0.1'       # base_url host
+  c.agent.port = 8126              # base_url port
+end
+```
+
+## 初始化流程
+
+### 完整流程图
+
+```
+Web 应用启动
+    ↓
+Components.initialize(settings)
+    ↓
+┌────────────────────────────────────────────────────────────┐
+│ [1] Cloudwise.initialize_async(callback)                  │  ← 异步，非阻塞
+│     ├─ 启动 HostIdWorker (后台线程，无限重试)              │
+│     └─ 启动监听线程                                        │
+│         └─ 等待 Host ID 就绪                               │
+│         └─ 就绪后调用 callback 初始化 Datadog 组件         │
+└────────────────────────────────────────────────────────────┘
+    ↓ (立即返回，不等待)
+    ↓
+✅ [2] 应用启动完成
+    ↓
+✅ [3] 应用开始处理请求 🚀
+    │
+    │ 此时状态：
+    │ • Cloudwise: HostIdWorker 在后台运行 ⏳
+    │ • Datadog 组件: 尚未初始化 ❌
+    │ • 数据采集: 未启动 ❌
+    │ • 应用服务: 正常运行 ✅
+    │
+    ↓ (后台持续运行...)
+    │
+┌──────────────────────────────────────────────────────────────┐
+│ [4] 后台: HostIdWorker 无限重试                              │
+│     尝试 1: 失败 → 等待 30s                                   │
+│     尝试 2: 失败 → 等待 30s                                   │
+│     尝试 3: 失败 → 等待 30s                                   │
+│     ...                                                      │
+│     尝试 N: 成功! ✅                                         │
+│     └─ 设置 ENV['CLOUDWISE_ACCOUNT_ID']                     │
+│     └─ probe_state.mark_host_id_ready!                     │
+└──────────────────────────────────────────────────────────────┘
+    ↓
+┌──────────────────────────────────────────────────────────────┐
+│ [5] Heartbeat 验证（阻塞，必须成功）                         │
+│                                                              │
+│ Thread: Cloudwise-Initializer                              │
+│   ├─ 启动 HeartbeatWorker                                   │
+│   └─ 等待首次成功 ⏳                                        │
+│                                                              │
+│ Thread: Heartbeat-Worker                                   │
+│   ├─ 尝试 1: POST /api/v1/agent/heartbeat                   │
+│   │   ├─ 失败 → 等待 30s → 重试                            │
+│   │   ├─ 失败 → 等待 30s → 重试                            │
+│   │   ├─ 失败 → 等待 30s → 重试                            │
+│   │   └─ 失败 3 次 → mark_heartbeat_inactive!             │
+│   │                  → 失败计数重置为 0                     │
+│   │                  → 下个周期（30s后）继续尝试           │
+│   │                                                        │
+│   ├─ 尝试 2 (30s后): POST /api/v1/agent/heartbeat          │
+│   │   └─ 成功! code = 1000 ✅                              │
+│   │       └─ mark_heartbeat_active!                       │
+│   │                                                        │
+│   └─ 继续定时任务（每 30s 一次）                           │
+│       ├─ 成功 (code=1000): 保持 active                     │
+│       ├─ 失败 or code≠1000: mark_inactive (继续尝试)       │
+│       └─ 连续失败 3 次: 失败计数重置，下周期继续           │
+└──────────────────────────────────────────────────────────────┘
+    ↓ (Heartbeat 首次成功后)
+    ↓
+┌──────────────────────────────────────────────────────────────┐
+│ [6] 启动 App Registration（非阻塞，后台运行）               │
+│                                                              │
+│ Thread: Cloudwise-Initializer                              │
+│   └─ 启动 AppRegistrationWorker ✅                          │
+│                                                              │
+│ Thread: AppRegistration-Worker                             │
+│   ├─ 每 3 分钟调用一次                                      │
+│   ├─ POST /api/v1/application/register                     │
+│   │   ├─ 成功: mark_app_registered!                       │
+│   │   └─ 失败: mark_app_unregistered!                     │
+│   │            (3分钟后再次尝试)                           │
+│   └─ 失败不影响其他流程                                     │
+└──────────────────────────────────────────────────────────────┘
+    ↓ (不等待，立即继续)
+    ↓
+┌──────────────────────────────────────────────────────────────┐
+│ [7] License 验证（阻塞，必须成功）                           │
+│                                                              │
+│ Thread: Cloudwise-Initializer                              │
+│   ├─ 启动 LicenseWorker                                     │
+│   └─ 等待首次成功 ⏳                                        │
+│                                                              │
+│ Thread: License-Worker                                     │
+│   ├─ 尝试 1: POST /api/v1/license/verify                    │
+│   │   ├─ 失败 → failure_count++                           │
+│   │   ├─ 失败 → failure_count++                           │
+│   │   ├─ 失败 → failure_count++                           │
+│   │   └─ 失败 3 次 → mark_license_invalid!                │
+│   │                  → 失败计数重置为 0                     │
+│   │                  → 下个周期（5分钟后）继续尝试         │
+│   │                                                        │
+│   ├─ 尝试 2 (5分钟后): POST /api/v1/license/verify         │
+│   │   └─ 成功! code = 1000 ✅                              │
+│   │       └─ mark_license_valid!                          │
+│   │                                                        │
+│   └─ 继续定时任务（每 5分钟 一次）                         │
+│       ├─ 成功 (code=1000): 保持 valid                      │
+│       ├─ 失败 or code≠1000: mark_invalid (继续尝试)        │
+│       └─ 连续失败 3 次: 失败计数重置，下周期继续           │
+└──────────────────────────────────────────────────────────────┘
+    ↓ (License 首次成功后)
+    ↓
+┌──────────────────────────────────────────────────────────────┐
+│ [8] 初始化 Datadog 组件 🎉                                  │
+│                                                              │
+│ Thread: Cloudwise-Initializer                              │
+│   └─ block.call  # 调用回调函数                             │
+│       └─ initialize_datadog_components(settings)            │
+│           ├─ telemetry                                      │
+│           ├─ tracer                                         │
+│           ├─ profiler                                       │
+│           ├─ runtime_metrics                                │
+│           ├─ health_metrics                                 │
+│           ├─ appsec                                         │
+│           ├─ dynamic_instrumentation                        │
+│           ├─ error_tracking                                 │
+│           ├─ data_streams                                   │
+│           └─ remote                                         │
+└──────────────────────────────────────────────────────────────┘
+    ↓
+✅ [9] Cloudwise & Datadog 全部就绪
+    ↓
+✅ [10] 开始数据采集和上报 🎉
+```
+
+### 状态时间线
+
+| 时间 | 应用状态 | Cloudwise 状态 | Datadog 组件 | 数据采集 |
+|------|---------|---------------|-------------|---------|
+| T0   | 启动中   | 初始化中 (async) | 未初始化 ❌ | 未启动 ❌ |
+| T1   | 运行中 ✅ | 等待 Host ID ⏳ | 未初始化 ❌ | 未启动 ❌ |
+|      | 处理请求 | (后台重试) |             |         |
+| T2   | 运行中 ✅ | Host ID 就绪 ✅ | 未初始化 ❌ | 未启动 ❌ |
+|      | 处理请求 | 等待 Heartbeat ⏳ |             |         |
+| T3   | 运行中 ✅ | Heartbeat 就绪 ✅ | 未初始化 ❌ | 未启动 ❌ |
+|      | 处理请求 | App Reg 启动<br>等待 License ⏳ |             |         |
+| T4   | 运行中 ✅ | License 就绪 ✅ | 初始化中 ⏳ | 未启动 ❌ |
+|      | 处理请求 | (初始化 Datadog) |             |         |
+| T5   | 运行中 ✅ | 正常工作 ✅ | 正常工作 ✅ | 开始采集 ✅ |
+|      | 处理请求 | (所有 workers 运行) |             |         |
+
+## Workers 执行顺序详解
+
+### 为什么需要顺序执行？
+
+Cloudwise 采用**顺序验证**策略，确保每个关键步骤都成功后才继续：
+
+1. **Host ID** - 所有 API 调用的前提，必须先获取
+2. **Heartbeat** - 验证探针是否被服务端允许运行
+3. **App Registration** - 注册应用信息（可选，不阻塞）
+4. **License** - 验证 License 是否有效
+5. **Datadog 初始化** - 所有验证通过后才初始化
+
+### 执行顺序
+
+```
+Host ID 就绪
+    ↓
+启动 HeartbeatWorker（阻塞等待首次成功）
+    ├─ 周期 1: 尝试 3 次（间隔 30s）
+    │   └─ 全部失败 → mark_inactive，重置计数
+    ├─ 周期 2 (30s后): 继续尝试
+    │   └─ 成功 (code=1000) → mark_active ✅
+    └─ 继续后续流程
+    ↓
+启动 AppRegistrationWorker（不阻塞，后台运行）
+    ├─ 每 3 分钟尝试一次
+    └─ 失败不影响其他流程
+    ↓
+启动 LicenseWorker（阻塞等待首次成功）
+    ├─ 周期 1: 尝试 1 次
+    │   └─ 失败 → failure_count++
+    ├─ 周期 2 (5min后): 尝试 1 次
+    │   └─ 失败 → failure_count++
+    ├─ 周期 3 (10min后): 尝试 1 次
+    │   └─ 失败 → failure_count++ (达到3次)
+    │       → mark_invalid，重置计数
+    ├─ 周期 4 (15min后): 继续尝试
+    │   └─ 成功 (code=1000) → mark_valid ✅
+    └─ 继续后续流程
+    ↓
+初始化 Datadog 组件 ✅
+    ↓
+开始数据采集和上报 🎉
+```
+
+### 关键特性
+
+#### 1. HeartbeatWorker（阻塞）
+
+- **间隔**: 30 秒
+- **重试**: 同一周期内失败重试（间隔 30s，最多 3 次）
+- **失败处理**: 
+  - 连续失败 3 次 → `mark_heartbeat_inactive!`
+  - 失败计数重置为 0
+  - 下个周期（30s 后）继续尝试
+- **成功条件**: `code = 1000`
+- **阻塞**: ✅ 必须首次成功才能继续
+
+#### 2. AppRegistrationWorker（非阻塞）
+
+- **间隔**: 3 分钟
+- **重试**: 失败后在下个周期继续尝试
+- **失败处理**: 
+  - 失败 → `mark_app_unregistered!`
+  - 3 分钟后再次尝试
+- **成功条件**: `code = 1000`
+- **阻塞**: ❌ 不阻塞，后台运行
+
+#### 3. LicenseWorker（阻塞）
+
+- **间隔**: 5 分钟
+- **重试**: 每个周期尝试 1 次，失败累计计数
+- **失败处理**: 
+  - 失败 → `failure_count++`
+  - 连续失败 3 次 → `mark_license_invalid!`
+  - 失败计数重置为 0
+  - 下个周期（5min 后）继续尝试
+- **成功条件**: `code = 1000`
+- **阻塞**: ✅ 必须首次成功才能初始化 Datadog
+
+### 失败恢复机制
+
+所有 workers 都支持**自动恢复**：
+
+- **HeartbeatWorker**: 任何周期返回 `code=1000` → `mark_heartbeat_active!` → 继续初始化
+- **LicenseWorker**: 任何周期返回 `code=1000` → `mark_license_valid!` → 继续初始化
+- **失败计数重置**: 连续失败达到最大次数后，计数重置为 0，下个周期重新开始计数
+
+### 为什么这样设计？
+
+1. **渐进式验证**: 确保每个步骤都成功后才继续，避免无效数据采集
+2. **持续重试**: 失败后不放弃，持续尝试直到成功
+3. **应用不阻塞**: 所有验证在后台线程执行，不影响应用正常运行
+4. **灵活性**: App Registration 可选，不阻塞关键流程
+
+## 探针状态管理
+
+### ProbeState 组件
+
+`ProbeState` 负责管理探针的全局状态，追踪多个独立条件：
+
+```ruby
+class ProbeState
+  def initialize
+    @host_id_ready = false       # Host ID 是否就绪
+    @heartbeat_active = false    # 心跳是否活跃
+    @license_valid = false       # License 是否有效
+    @app_registered = false      # 应用是否注册
+  end
+  
+  # 是否可以采集数据
+  def can_collect_data?
+    @host_id_ready && @heartbeat_active && @license_valid
+  end
+  
+  # 探针是否暂停
+  def suspended?
+    !can_collect_data?
+  end
+  
+  # 探针是否活跃
+  def active?
+    can_collect_data?
+  end
+end
+```
+
+### 状态转换
+
+```
+初始状态:
+  host_id_ready = false
+  heartbeat_active = false
+  license_valid = false
+  → suspended = true (不采集数据)
+
+Host ID 生成成功:
+  host_id_ready = true
+  heartbeat_active = false
+  license_valid = false
+  → suspended = true (仍不采集数据)
+
+首次心跳成功:
+  host_id_ready = true
+  heartbeat_active = true
+  license_valid = false
+  → suspended = true (仍不采集数据)
+
+首次 License 校验成功:
+  host_id_ready = true
+  heartbeat_active = true
+  license_valid = true
+  → active = true (开始采集数据) ✅
+
+心跳失败 3 次:
+  heartbeat_active = false
+  → suspended = true (停止采集数据) ❌
+
+License 校验失败 3 次:
+  license_valid = false
+  → suspended = true (停止采集数据) ❌
+
+心跳恢复:
+  heartbeat_active = true
+  license_valid = true
+  → active = true (恢复采集数据) ✅
+```
+
+## 架构设计
+
+### 组件概览
+
+```
+Cloudwise::Component
+    ├─ Client (HTTP 客户端)
+    ├─ ProbeState (状态管理)
+    ├─ HostIdWorker (Host ID 生成)
+    ├─ HeartbeatWorker (心跳)
+    ├─ LicenseWorker (License 校验)
+    └─ AppRegistrationWorker (应用注册)
+```
+
+### 核心机制
+
+#### 1. 回调机制（Callback）
+
+Cloudwise 使用 Ruby block (callback) 实现延迟初始化：
+
+```ruby
+# components.rb
+@cloudwise.initialize_async do
+  initialize_datadog_components(settings)  # 回调函数
+end
+```
+
+当 Host ID 就绪后，Cloudwise 调用这个回调函数来初始化 Datadog 组件。
+
+#### 2. 线程模型
+
+```
+Main Thread (应用主线程)
+    ├─ 创建 Cloudwise 组件
+    └─ 立即返回，应用启动完成 ✅
+
+Thread: Host-ID-Worker (HostIdWorker)
+    └─ 无限循环调用 generateHostId（每 30s 重试）
+    └─ 成功后设置 host_id_generated = true
+
+Thread: Cloudwise-Initializer (监听线程)
+    ├─ [步骤 1] 轮询 host_id_generated? (阻塞)
+    ├─ [步骤 2] 启动 HeartbeatWorker，轮询 heartbeat_active? (阻塞)
+    ├─ [步骤 3] 启动 AppRegistrationWorker（不阻塞）
+    ├─ [步骤 4] 启动 LicenseWorker，轮询 license_valid? (阻塞)
+    └─ [步骤 5] 调用 callback 初始化 Datadog 组件
+
+Thread: Heartbeat-Worker (HeartbeatWorker)
+    ├─ 每 30 秒调用一次心跳接口
+    ├─ 同一周期内失败重试（间隔 30s，最多 3 次）
+    └─ 失败 3 次后重置计数，下周期继续
+
+Thread: AppRegistration-Worker (AppRegistrationWorker)
+    ├─ 每 3 分钟调用一次应用注册接口
+    └─ 失败不影响其他流程，下周期继续
+
+Thread: License-Worker (LicenseWorker)
+    ├─ 每 5 分钟调用一次 License 接口
+    ├─ 失败累计计数（最多 3 次）
+    └─ 失败 3 次后重置计数，下周期继续
+```
+
+#### 3. 数据采集控制
+
+数据采集由 `traces.rb` 中的 `cloudwise_probe_suspended?` 方法控制：
+
+```ruby
+# lib/datadog/tracing/transport/http/traces.rb
+def call(env, &block)
+  # 检查 Cloudwise 探针状态
+  if cloudwise_probe_suspended?
+    Datadog.logger.debug { 'Cloudwise: Probe suspended, skipping trace submission' }
+    return build_mock_response(env)
+  end
+  
+  # 正常上报 trace
+  # ...
+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?
+  
+  cloudwise.probe_state.suspended?
+end
+```
+
+## 使用示例
+
+### 基本使用
+
+```ruby
+require 'datadog'
+
+Datadog.configure do |c|
+  c.service = 'my-ruby-app'
+  c.agent.host = '127.0.0.1'
+  c.agent.port = 8126
+  
+  c.cloudwise.enabled = true
+  c.cloudwise.license_key = 'your-license-key'
+end
+
+# 应用立即启动，不等待 Cloudwise
+# Cloudwise 在后台初始化
+```
+
+### 检查状态
+
+```ruby
+# 检查 Cloudwise 状态
+status = Datadog.components.cloudwise.status
+puts status
+# => {
+#   enabled: true,
+#   account_id: "acc-1234567890",
+#   host_id_generated: true,
+#   host_id_ready: true,
+#   heartbeat_active: true,
+#   license_valid: true,
+#   app_registered: true,
+#   can_collect_data: true,
+#   heartbeat_running: true,
+#   license_running: true,
+#   app_registration_running: true
+# }
+
+# 检查是否可以采集数据
+if Datadog.components.cloudwise.probe_state.active?
+  puts "Probe is active, collecting data"
+else
+  puts "Probe is suspended, NOT collecting data"
+end
+```
+
+## 故障排查
+
+### 常见问题
+
+#### 1. Host ID 一直获取失败
+
+**现象**: 应用正常启动，但日志显示 Host ID 一直在重试
+
+**原因**:
+- API 服务器无法访问
+- 网络问题
+- 认证失败
+
+**解决方案**:
+```bash
+# 检查网络连通性
+curl -X POST http://127.0.0.1:8126/v2/app/generateHostId \
+  -H "Content-Type: application/json" \
+  -d '{
+    "serverName": "my-ruby-app",
+    "licenseKey": "your-license-key",
+    "timestamp": 1234567890
+  }'
+
+# 检查日志
+grep "Host ID generation failed" application.log
+```
+
+#### 2. 数据不上报
+
+**现象**: 应用运行正常，但没有数据上报到 Datadog
+
+**检查步骤**:
+
+1. 检查 Host ID 是否就绪:
+```ruby
+Datadog.components.cloudwise.status[:host_id_ready]
+```
+
+2. 检查探针状态:
+```ruby
+Datadog.components.cloudwise.probe_state.active?
+```
+
+3. 检查 ProbeState 各项条件:
+```ruby
+status = Datadog.components.cloudwise.probe_state.status
+# => {
+#   host_id_ready: true/false,
+#   heartbeat_active: true/false,
+#   license_valid: true/false,
+#   app_registered: true/false,
+#   can_collect_data: true/false
+# }
+```
+
+#### 3. 心跳失败
+
+**现象**: 日志显示心跳失败
+
+**解决方案**:
+```bash
+# 手动测试心跳接口
+curl -X POST http://127.0.0.1:8126/api/v1/agent/heartbeat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "accountId": "acc-1234567890",
+    "serverName": "my-ruby-app",
+    "timestamp": 1234567890
+  }'
+```
+
+## 开发和测试
+
+### 单元测试
+
+运行 Cloudwise 相关测试：
+
+```bash
+bundle exec rspec spec/datadog/core/cloudwise/
+```
+
+### 集成测试
+
+创建一个测试应用：
+
+```ruby
+# test_app.rb
+require 'datadog'
+require 'sinatra'
+
+Datadog.configure do |c|
+  c.service = 'test-app'
+  c.agent.host = '127.0.0.1'
+  c.agent.port = 8126
+  
+  c.cloudwise.enabled = true
+  c.cloudwise.license_key = 'test-license-key'
+end
+
+get '/' do
+  "Hello, Cloudwise!"
+end
+
+get '/status' do
+  Datadog.components.cloudwise.status.to_json
+end
+```
+
+运行应用并检查状态：
+
+```bash
+ruby test_app.rb
+
+# 在另一个终端
+curl http://localhost:4567/status
+```
+
+## 性能考虑
+
+### 资源消耗
+
+- **内存**: Cloudwise 组件占用约 1-2 MB
+- **CPU**: 后台 workers 几乎不占用 CPU（大部分时间在 sleep）
+- **网络**: 
+  - Host ID: 一次性请求（每 30s 重试，成功后停止）
+  - 心跳: 每 30 秒一次
+  - License: 每 5 分钟一次
+  - 应用注册: 每 3 分钟一次
+
+### 启动时间影响
+
+- ✅ **不影响**: Cloudwise 是异步的，不阻塞应用启动
+- ✅ **不影响**: 应用可以立即处理请求
+- ⚠️ **延迟**: Datadog 组件会延迟初始化（等待 Host ID）
+
+## 最佳实践
+
+1. **配置管理**: 使用环境变量而非硬编码配置
+2. **监控日志**: 定期检查 Cloudwise 相关日志
+3. **健康检查**: 在应用的健康检查端点中包含 Cloudwise 状态
+4. **错误处理**: Cloudwise 失败不应导致应用崩溃
+5. **资源限制**: 确保容器有足够的内存和网络访问权限
+
+## 版本历史
+
+### v2.0 (当前版本)
+- ✅ 异步初始化，不阻塞应用启动
+- ✅ Datadog 组件延迟加载
+- ✅ Host ID 无限重试
+- ✅ 使用 DD_SERVICE 和 DD_AGENT_HOST/PORT 配置
+
+### v1.0 (已弃用)
+- ❌ 同步初始化，阻塞应用启动
+- ❌ Datadog 组件立即初始化
+- ❌ Host ID 有重试限制
+
+## 参考文档
+
+- [实现指南 V2](./IMPLEMENTATION_V2.md) - 详细的实现说明
+- [静态类型检查指南](../../docs/StaticTypingGuide.md) - RBS 类型定义
+- [Pull Request 模板](../../../.github/PULL_REQUEST_TEMPLATE.md) - 贡献指南