cw-datadog 2.23.0.2 → 2.23.0.4

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

@@ -1,398 +0,0 @@
-# Cloudwise 快速开始指南
-
-## 🚀 5 分钟快速测试
-
-### 步骤 1: 启动 Mock API 服务器
-
-```bash
-cd lib/datadog/core/cloudwise
-ruby mock_api_server.rb
-```
-
-你会看到：
-
-```
-============================================================
-🚀 Cloudwise Mock API Server
-============================================================
-Server starting on http://localhost:8080
-...
-```
-
-在浏览器中打开 http://localhost:8080 查看 API 文档。
-
-### 步骤 2: 运行集成测试
-
-在另一个终端窗口：
-
-```bash
-cd lib/datadog/core/cloudwise
-
-# 方式 1: 完整流程（会调用 generateHostId）
-ruby test_integration.rb
-
-# 方式 2: 使用已有 account_id（跳过 generateHostId）
-CLOUDWISE_ACCOUNT_ID=acc-existing-123 ruby test_integration.rb
-```
-
-### 步骤 3: 观察日志
-
-你会看到类似的输出：
-
-```
-🧪 Cloudwise Integration Test
-✅ Mock API server is running
-✅ Datadog configured
-⏳ Waiting for Cloudwise initialization (5 seconds)...
-
-============================================================
-📊 Cloudwise Status
-============================================================
-Enabled:              true
-Account ID:           acc-1234567890-123
-Host ID Generated:    ✅
-Probe Active:         🟢 Active
-Heartbeat Running:    ✅
-License Running:      ✅
-App Reg Running:      ✅
-App Registered:       ✅
-============================================================
-```
-
-### 步骤 4: 测试探针熔断
-
-在第三个终端窗口，切换探针状态：
-
-```bash
-curl http://localhost:8080/admin/toggle_probe
-```
-
-返回：
-
-```json
-{
-  "status": "suspended",
-  "message": "Probe status changed to suspended"
-}
-```
-
-观察测试脚本的输出，会看到：
-
-```
-⚠️  PROBE STATE CHANGED!
-   🔴 Probe suspended - data collection stopped
-```
-
-再次调用恢复探针：
-
-```bash
-curl http://localhost:8080/admin/toggle_probe
-```
-
-会看到：
-
-```
-⚠️  PROBE STATE CHANGED!
-   🟢 Probe recovered - data collection resumed
-```
-
-## 📝 完整集成步骤
-
-### 1. 添加配置
-
-编辑 `lib/datadog/core/configuration/settings.rb`，添加：
-
-```ruby
-settings :cloudwise do
-  option :enabled do |o|
-    o.type :bool
-    o.env 'DD_CLOUDWISE_ENABLED'
-    o.default false
-  end
-
-  option :base_url do |o|
-    o.type :string
-    o.env 'DD_CLOUDWISE_BASE_URL'
-    o.default 'http://localhost:8080'
-  end
-
-  option :server_name do |o|
-    o.type :string
-    o.env 'DD_CLOUDWISE_SERVER_NAME'
-    o.default { Socket.gethostname }
-  end
-
-  option :license_key do |o|
-    o.type :string, nilable: true
-    o.env 'DD_CLOUDWISE_LICENSE_KEY'
-    o.default nil
-  end
-
-  option :heartbeat_interval do |o|
-    o.type :int
-    o.env 'DD_CLOUDWISE_HEARTBEAT_INTERVAL'
-    o.default 60
-  end
-
-  option :license_check_interval do |o|
-    o.type :int
-    o.env 'DD_CLOUDWISE_LICENSE_CHECK_INTERVAL'
-    o.default 300
-  end
-
-  option :app_registration_interval do |o|
-    o.type :int
-    o.env 'DD_CLOUDWISE_APP_REGISTRATION_INTERVAL'
-    o.default 600
-  end
-end
-```
-
-### 2. 集成组件
-
-编辑 `lib/datadog/core/configuration/components.rb`：
-
-```ruby
-class Components
-  def initialize(settings)
-    # ... 现有代码 ...
-
-    # Cloudwise component
-    @cloudwise = build_cloudwise(settings)
-  end
-
-  attr_reader :cloudwise
-
-  private
-
-  def build_cloudwise(settings)
-    require_relative '../cloudwise/component'
-    Datadog::Core::Cloudwise::Component.new(
-      settings: settings,
-      logger: logger
-    )
-  end
-
-  def startup!
-    # ... 现有代码 ...
-    cloudwise.start if cloudwise.enabled?
-  end
-
-  def shutdown!
-    # ... 现有代码 ...
-    cloudwise.stop if cloudwise.enabled?
-  end
-end
-```
-
-### 3. 配置应用
-
-在你的应用中：
-
-```ruby
-require 'datadog'
-
-Datadog.configure do |c|
-  c.service = 'my-app'
-  
-  # Cloudwise 配置
-  c.cloudwise.enabled = true
-  c.cloudwise.base_url = ENV['CLOUDWISE_API_URL']
-  c.cloudwise.server_name = ENV['SERVER_NAME']
-  c.cloudwise.license_key = ENV['CLOUDWISE_LICENSE_KEY']
-end
-```
-
-或使用环境变量：
-
-```bash
-export DD_CLOUDWISE_ENABLED=true
-export DD_CLOUDWISE_BASE_URL=https://api.cloudwise.com
-export DD_CLOUDWISE_SERVER_NAME=my-app
-export DD_CLOUDWISE_LICENSE_KEY=your-license-key
-```
-
-## 🎯 关键功能
-
-### 1. Host ID 生成
-
-- **自动执行**: 应用启动时
-- **失败重试**: 每 2 分钟
-- **完成后**: 自动停止 Worker
-
-### 2. 心跳注册
-
-- **执行周期**: 60 秒
-- **失败重试**: 间隔 2 秒，最多 3 次
-- **探针熔断**: 返回 code=1001 时停止采集
-- **探针恢复**: 返回 code=1000/1002 时恢复采集
-
-### 3. License 校验
-
-- **执行周期**: 5 分钟
-- **失败重试**: 间隔 2 秒，最多 3 次
-- **校验失败**: 停止数据采集
-- **校验成功**: 恢复数据采集
-
-### 4. 应用注册
-
-- **执行周期**: 10 分钟
-- **失败重试**: 间隔 2 秒，最多 3 次
-- **注意**: 注册失败不影响数据采集
-
-## 🔍 状态监控
-
-### 查看状态
-
-```ruby
-status = Datadog.components.cloudwise.status
-puts status.inspect
-```
-
-输出：
-
-```ruby
-{
-  enabled: true,
-  account_id: "acc-1234567890-123",
-  host_id_generated: true,
-  probe_active: true,
-  probe_suspended: false,
-  heartbeat_running: true,
-  license_running: true,
-  app_registration_running: true,
-  app_registered: true
-}
-```
-
-### 健康检查端点
-
-```ruby
-# In Rails
-get '/health/cloudwise' do
-  cloudwise = Datadog.components.cloudwise
-  
-  if cloudwise&.probe_active?
-    render json: { status: 'ok', probe: 'active' }
-  else
-    render json: { status: 'suspended', probe: 'suspended' }, status: 503
-  end
-end
-```
-
-## 📊 日志示例
-
-### 正常运行
-
-```
-[INFO] 🚀 Starting Cloudwise Component
-[INFO] 📍 Step 1: Starting Host ID generation worker...
-[INFO] Cloudwise: Generated Host ID, account_id: acc-xxx
-[INFO] 💓 Step 2: Starting Heartbeat worker (60s interval)...
-[INFO] 🔑 Step 3: Starting License verification worker (5 min interval)...
-[INFO] 📝 Step 4: Starting Application registration worker (10 min interval)...
-[INFO] ✅ Cloudwise Component started successfully
-```
-
-### 探针熔断
-
-```
-[WARN] 🔴 Cloudwise: Probe suspended - data collection stopped
-[DEBUG] Cloudwise: Probe suspended, skipping trace submission
-```
-
-### 探针恢复
-
-```
-[INFO] 🟢 Cloudwise: Probe resumed - data collection active
-```
-
-## 🧪 测试场景
-
-### 场景 1: 正常运行
-
-1. 启动 Mock API 服务器
-2. 启动应用
-3. 观察所有接口正常调用
-
-### 场景 2: 探针熔断
-
-1. 切换探针状态: `curl http://localhost:8080/admin/toggle_probe`
-2. 观察数据采集停止
-3. 再次切换恢复
-4. 观察数据采集恢复
-
-### 场景 3: License 失效
-
-1. 切换 License 状态: `curl http://localhost:8080/admin/toggle_license`
-2. 等待 License 校验（5 分钟或重启应用加快测试）
-3. 观察数据采集停止
-4. 切换 License 状态恢复
-
-### 场景 4: 网络故障
-
-1. 停止 Mock API 服务器
-2. 观察重试日志
-3. 重启 Mock API 服务器
-4. 观察自动恢复
-
-## 📚 文档索引
-
-| 文档 | 说明 |
-|------|------|
-| `QUICKSTART.md` | 本文件 - 快速开始 |
-| `README.md` | 完整功能文档 |
-| `INTEGRATION_GUIDE.md` | 详细集成步骤 |
-| `example.rb` | 代码示例 |
-| `mock_api_server.rb` | 测试服务器 |
-| `test_integration.rb` | 集成测试脚本 |
-
-## 🆘 常见问题
-
-### Q: 如何验证 Cloudwise 是否正常工作？
-
-A: 查看日志中是否有 Cloudwise 相关输出，或检查状态：
-
-```ruby
-puts Datadog.components.cloudwise.status
-```
-
-### Q: 如何临时禁用 Cloudwise？
-
-A: 设置环境变量：
-
-```bash
-export DD_CLOUDWISE_ENABLED=false
-```
-
-或在代码中：
-
-```ruby
-c.cloudwise.enabled = false
-```
-
-### Q: 探针熔断后多久会恢复？
-
-A: 取决于心跳或 License 校验接口下次返回成功的时间：
-- 心跳: 最多 60 秒
-- License: 最多 5 分钟
-
-### Q: Host ID 一直生成失败怎么办？
-
-A: 检查：
-1. API 服务器是否可达
-2. base_url 配置是否正确
-3. license_key 是否有效
-4. 网络防火墙设置
-
-## 🎉 完成！
-
-现在你已经了解了 Cloudwise 集成的基本使用。
-
-更多详细信息，请参考：
-- `README.md` - 完整功能文档
-- `INTEGRATION_GUIDE.md` - 详细集成指南
-- `CLOUDWISE_IMPLEMENTATION.md` - 实现总结
-
-祝使用愉快！🚀
-