oodle-onboarding

Oodle 入门 — 集成设置

使用 oodle integrations 命令将基础设施接入 Oodle 可观测性平台。主动探索环境，以推荐集成并调整设置步骤。设置规范是一份蓝图——它定义了方案和参数，但具体执行会根据代码库和环境的实际情况灵活调整。

先决条件

开始任何接入工作之前，请确认已安装并验证 Oodle CLI。每次会话开始时都要运行以下检查：

步骤 1：检查是否已安装 CLI

oodle version

如果找不到该命令，请安装：

brew install oodle-ai/oodle/oodle

如果无法使用 brew，请改用：

go install github.com/oodle-ai/oodle-cli/cmd/oodle@latest

步骤 2：检查 CLI 是否已完成身份验证

oodle auth status

如果尚未完成身份验证，或状态显示错误，请运行交互式登录：

oodle auth login

这会打开浏览器以进行 OAuth 登录。用户必须完成浏览器中的流程——请提示他们完成操作并等待确认。登录成功后，使用 oodle auth status 验证。

注意： oodle integrations list-setup-specs 和 oodle integrations get-setup-spec 不需要身份验证。即使尚未配置身份验证，也可以使用这些命令发现可用集成并获取设置说明。其他所有集成命令都需要有效凭据——在继续执行命令顺序中的步骤 2 之后的操作前，请先完成上述身份验证步骤。

命令执行顺序

每次集成接入请求都请按以下顺序操作：

1. 确定集成类型。 如果用户指定了类型（例如，“kubernetes”或“aws-cloudwatch”），则使用该类型。否则，运行环境发现，以检测当前基础设施并推荐匹配的集成（参见 references/environment-discovery.md）。
2. 获取可用的设置规范——运行 oodle integrations list-setup-specs -o json（无需身份验证），确认该类型存在，并与环境发现结果交叉比对。
3. 获取集成记录——运行 oodle integrations list -o json，提取：(a) type 字段（转换为小写，以供步骤 4 使用），(b) 用于 helm values 的 collectorDomain/logsCollectorDomain，(c) 从域名模式中提取的实例 ID。然后运行 oodle api-keys list -o json 查找现有 API 密钥；如果没有，则运行 oodle api-keys create --name <name> --scopes <scopes> 创建一个。此步骤需要身份验证——如果尚未配置，请先完成先决条件中的步骤 1–2。
4. 获取设置规范——运行 oodle integrations get-setup-spec <type-lowercase> -o json。该规范是集成的蓝图，而非固定不变的脚本。它定义了总体方案、所需工具和参数。
5. 深入探索环境——检查代码库、运行中的服务和现有配置。根据发现结果确定参数，并调整规范中的步骤（参见 references/environment-discovery.md）。
6. 收集剩余参数——完成探索后，询问用户任何无法自动检测的信息。将问题集中在一起提出。
7. 执行设置——逐步执行规范中的步骤，并根据探索结果调整每一步。执行任何非只读命令前，都要先征得用户确认。执行前请查看 references/gotchas.md。
8. 验证集成——运行 oodle integrations list -o json 并检查状态。
9. 确认 Oodle 端的数据存在（参见 references/post-install-validation.md）。

遇到失败情形时，请参阅 references/failure-handling.md。

快速参考

任务	命令	是否需要身份验证？
发现可用的设置规范	oodle integrations list-setup-specs -o json	否
发现可用的设置规范（表格）	oodle integrations list-setup-specs	否
获取设置规范	oodle integrations get-setup-spec <type> -o json	否
获取设置规范（YAML）	oodle integrations get-setup-spec <type> -o yaml	否
列出已配置的集成	oodle integrations list -o json	是
列出已配置的集成（表格）	oodle integrations list	是
列出 API 密钥	oodle api-keys list -o json	是
创建 API 密钥	oodle api-keys create --name <name> --scopes <scopes> -o json	是

别名：oodle integration、oodle integ

常见操作

发现可用的集成类型

# CORRECT — discover all types with setup specs (no auth required)
oodle integrations list-setup-specs -o json

# CORRECT — table output for display (no auth required)
oodle integrations list-setup-specs

# WRONG — guessing integration types without checking
oodle integrations get-setup-spec some-random-type -o json

列出已配置的集成

# CORRECT — check which integrations are already configured (requires auth)
oodle integrations list -o json

# CORRECT — table output for display
oodle integrations list

获取设置规范

# CORRECT — fetch spec for a known type (no auth required)
oodle integrations get-setup-spec kubernetes -o json

# WRONG — hardcoding setup steps instead of fetching the spec
kubectl apply -f <hardcoded-collector-manifest>   # never hardcode a manifest source; fetch the spec instead

执行设置步骤（调整蓝图）

规范定义了需要执行的操作。每个步骤开始前都要发现当前状态并进行调整：

# CORRECT — check existing state, then adapt
kubectl get namespace oodle-system 2>/dev/null && echo "Already exists, skipping" || kubectl create namespace oodle-system

# CORRECT — existing release? upgrade instead of install
helm list -n oodle-system | grep oodle && helm upgrade ... || helm install ...

# CORRECT — show the command and ask for confirmation before running
echo "I will run: kubectl create namespace oodle-system"
# [wait for user confirmation]
kubectl create namespace oodle-system

# WRONG — blindly running spec commands without checking existing state
kubectl create namespace oodle-system  # fails if already exists

# WRONG — running destructive commands without confirmation
kubectl delete namespace oodle-system

验证集成

# CORRECT — check integration status after setup
oodle integrations list -o json

# CORRECT — check pods are running (for Kubernetes integrations)
kubectl get pods -n oodle-system

# WRONG — assuming success without verification
echo "Integration complete!"

最佳实践

始终获取最新的设置规范

在每次接入会话开始时运行 oodle integrations get-setup-spec <type> -o json。切勿缓存或重复使用之前获取的规范——随着平台演进，要求和步骤都会发生变化。将规范视为蓝图：它定义了需要执行的操作和所需参数，但要根据环境探查结果调整具体命令和取值。

先通过探查解析参数，再询问用户

开始执行前，收集所有必需参数。按以下顺序检查这些来源：

1. 环境探查——主动探查：使用 kubectl config current-context 获取集群名称，使用 helm list 查看已有的发布版本，通过进程列表检查正在运行的采集器，在代码库中查找配置文件中的端点，并通过环境变量查找 API 密钥。
2. 用户请求——用户可能已在提示词中指定取值。
3. 询问用户——仅针对无法自动检测的内容。将剩余问题合并后一并询问。

创建或修改资源前先确认

显示即将运行的命令，并等待用户确认，然后再执行任何创建、修改或删除资源的命令。只读命令（list、get、describe）无需确认。在显示的命令中遮盖密钥——先显示遮盖后的版本供用户确认，再在内部运行未遮盖的版本。对于需要密钥值的命令（例如 helm install --set apiKey=...），优先通过临时文件、标准输入或环境变量传递密钥，而不要使用命令行参数，以免密钥暴露在 shell 历史记录中。

妥善处理已存在的资源

如果资源（命名空间、Helm 发布版本、ConfigMap）已经存在，则跳过创建步骤，并注明该资源已存在。不要报错，也不要尝试删除后重新创建。

遮盖输出中的密钥

切勿显示完整的 API 密钥、令牌或密码。只显示开头和结尾各 4 个字符（例如 oodl...k9x2）。根据规范渲染配置模板时，在向用户展示前遮盖密钥值。

一次执行一个步骤

按顺序执行设置步骤。确认每个步骤成功后，再继续下一步。如果某个步骤失败，请诊断问题并提出修复建议——不要继续执行下一步。

完成后提供摘要

所有步骤完成且验证通过后，提供摘要：

• 集成类型和名称
• 已安装／配置的内容
• 当前状态
• 后续检查状态的方法（oodle integrations list）

参考资料

• references/environment-discovery.md — 基础设施检测和设置步骤调整
• references/gotchas.md — 执行设置前需要查看的重要注意事项
• references/post-install-validation.md — 使用查询技能验证数据是否存在
• references/failure-handling.md — 常见故障场景的排查
• Oodle CLI 仓库 — oodle 二进制文件的来源
• Oodle 文档 — 产品文档
• oodle-cli 技能 — CLI 核心用法、身份验证和输出格式