唯一一个像人类一样调查事件的AI助手——通过查看警报并获取缺失的数据直到找到根本原因。由OpenAI、Azure AI、AWS Bedrock或任何你选择的工具调用LLM驱动,包括开源模型。
HolmesGPT能做什么?
- 调查事件(AIOps):通过PagerDuty/OpsGenie/Prometheus/Jira等平台
- 双向集成:在现有的工单/事件管理系统中查看调查结果
- 自动分诊:使用HolmesGPT作为第一响应者。标记关键警报,并优先处理它们
- 警报丰富:自动添加上下文到警报中 - 如日志和微服务健康信息 - 更快找到根本原因
- 识别云问题:通过向HolmesGPT询问不健康的基础设施问题
- 用普通英语进行运行手册自动化:根据你提供的运行手册加快对已知问题的响应
观看实战
示例
Kubernetes 故障排除
holmes ask "我的集群中有哪些pods不健康,为什么?"
Prometheus警报根本原因分析
通过Slack上的官方Robusta集成调查Prometheus警报。
或者从命令行运行HolmesGPT:
kubectl port-forward alertmanager-robusta-kube-prometheus-st-alertmanager-0 9093:9093 &
holmes investigate alertmanager --alertmanager-url http://localhost:9093
注意 - 如果在Mac OS上使用Docker镜像,需要使用http://docker.for.mac.localhost:9093
代替http://localhost:9093
日志文件分析
使用-f
将文件附加到HolmesGPT会话:
sudo dmesg > dmesg.log
poetry run python3 holmes.py ask "调查这个dmesg日志中的错误" -f dmesg.log
Jira工单调查
holmes investigate jira --jira-url https://<PLACEDHOLDER>.atlassian.net --jira-username <PLACEHOLDER_EMAIL> --jira-api-key <PLACEHOLDER_API_KEY>
默认情况下,结果在CLI中显示。使用--update
可以将结果作为评论添加到Jira工单中。
GitHub问题调查
holmes investigate github --github-url https://<PLACEHOLDER> --github-owner <PLACEHOLDER_OWNER_NAME> --github-repository <PLACEHOLDER_GITHUB_REPOSITORY> --github-pat <PLACEHOLDER_GITHUB_PAT>
默认情况下,结果在CLI中显示。使用--update
可以将结果作为评论添加到GitHub问题中。
OpsGenie警报调查
holmes investigate opsgenie --opsgenie-api-key <PLACEHOLDER_APIKEY>
默认情况下,结果在CLI中显示。使用--update --opsgenie-team-integration-key <PLACEHOLDER_TEAM_KEY>
可以将结果作为评论添加到OpsGenie警报中。更多信息请参考CLI帮助。
PagerDuty事件调查
holmes investigate pagerduty --pagerduty-api-key <PLACEHOLDER_APIKEY>
默认情况下,结果在CLI中显示。使用--update --pagerduty-user-email <PLACEHOLDER_EMAIL>
可以将结果作为评论添加到PagerDuty问题中。更多信息请参考CLI帮助。
添加K9s插件
你可以将HolmesGPT作为K9s插件来调查任何Kubernetes资源为什么不健康。
将以下内容添加到K9s插件文件中,通常是Linux的~/.config/k9s/plugins.yaml
和Mac的~/Library/Application Support/k9s/plugins.yaml
。更多关于K9s插件的信息请参考此处并检查你的插件路径这里。
注意:HolmesGPT必须安装并配置好才能让K9s插件工作。
使用快捷键Shift + H
进行调查的基础插件:
plugins:
holmesgpt:
shortCut: Shift-H
description: 询问HolmesGPT
scopes:
- all
command: bash
background: false
confirm: false
args:
- -c
- |
holmes ask "为什么$NAMESPACE命名空间中的$RESOURCE_NAME的$NAME不是按预期工作的"
echo "按'q'退出"
while : ; do
read -n 1 k <&1
if [[ $k = q ]] ; then
break
fi
done
使用快捷键Shift + O
允许你修改HolmesGPT对LLM提问内容的高级插件。(例如你可以将问题改为“为这个部署生成一个HPA”,AI将遵循这些指示并输出一个HPA配置。)
plugins:
custom-holmesgpt:
shortCut: Shift-Q
description: 自定义HolmesGPT询问
scopes:
- all
command: bash
background: false
confirm: false
args:
- -c
- |
INSTRUCTIONS="# 编辑下面一行。以'#'开头的行将被忽略。"
DEFAULT_ASK_COMMAND="为什么$NAMESPACE命名空间中的$RESOURCE_NAME的$NAME不是按预期工作的"
QUESTION_FILE=$(mktemp)
echo "$INSTRUCTIONS" > "$QUESTION_FILE"
echo "$DEFAULT_ASK_COMMAND" >> "$QUESTION_FILE"
# 在默认文本编辑器中打开该行
${EDITOR:-nano} "$QUESTION_FILE"
# 读取修改后的行,忽略以'#'开头的行
user_input=$(grep -v '^#' "$QUESTION_FILE")
echo running: holmes ask "\"$user_input\""
holmes ask "$user_input"
echo "按'q'退出"
while : ; do
read -n 1 k <&1
if [[ $k = q ]] ; then
break
fi
done
喜欢这个吗?查看其他用例或者通过安装HolmesGPT开始使用。
主要功能
- 连接现有的可观察数据:发现你不知道的相关性。无需收集新数据或添加仪器。
- 符合规范:可以在本地运行你的LLM(或在云中使用OpenAI/Azure/AWS)
- 透明结果:查看AI的动作日志和它收集的数据,以了解它是如何得出结论的
- 可扩展的数据源:通过提供自己的工具定义,将AI连接到自定义数据
- 运行手册自动化:可选地提供普通英语的运行手册,AI将自动遵循它们
- 集成现有的工作流:连接Slack和Jira,在现有工具中查看结果
安装
先决条件: 获取支持的LLM的API密钥。
安装方法:
Brew (Mac/Linux)
- 添加我们的tap:
brew tap robusta-dev/homebrew-holmesgpt
- 安装holmesgpt:
brew install holmesgpt
- 检查安装是否成功。首次运行需要几秒钟,请耐心等待。:
holmes --help
- 运行holmesgpt:
holmes ask "我的集群中有哪些问题"
预建的Docker容器
运行预建的Docker容器docker.pkg.dev/genuine-flight-317411/devel/holmes-dev
,带有额外的标志来挂载相关的配置文件(这样kubectl和其他工具可以使用你本机的凭证访问AWS/GCP资源)
docker run -it --net=host -v ~/.holmes:/root/.holmes -v ~/.aws:/root/.aws -v ~/.config/gcloud:/root/.config/gcloud -v $HOME/.kube/config:/root/.kube/config us-central1-docker.pkg.dev/genuine-flight-317411/devel/holmes-dev ask "哪些pods不健康,为什么?"
前沿版本(Pip和Pipx)
你可以通过pip或pipx从最新的git版本安装HolmesGPT。
我们推荐使用pipx,因为它确保HolmesGPT与系统上的其他python包隔离,防止依赖冲突。
首先安装Pipx(如果你使用pip可以跳过这一步)。
然后使用pip或pipx从git安装HolmesGPT:
pipx install "https://github.com/robusta-dev/holmesgpt/archive/refs/heads/master.zip"
通过检查版本验证HolmesGPT是否安装成功:
holmes version
要用pipx升级HolmesGPT,可以运行:
pipx upgrade holmesgpt
从源码(Python Poetry)
git clone https://github.com/robusta-dev/holmesgpt.git
cd holmesgpt
poetry install --no-root
poetry run python3 holmes.py ask "哪些pods不健康,为什么?"
从源码(Docker)
从github克隆项目,然后运行:
cd holmesgpt
docker build -t holmes . -f Dockerfile.dev
docker run -it --net=host -v -v ~/.holmes:/root/.holmes -v ~/.aws:/root/.aws -v ~/.config/gcloud:/root/.config/gcloud -v $HOME/.kube/config:/root/.kube/config holmes ask "哪些pods不健康,为什么?"
在你的集群中运行HolmesGPT(Helm)
大多数用户应该按照Robusta文档↗中的说明安装Holmes,而不是以下说明。
通过使用“Robusta”集成,您将受益于与“Prometheus 警报”和“Slack”的端到端集成。使用以下说明,您将需要自己构建许多这些组件。
在这种模式下,所有参数应通过环境变量传递给 HolmesGPT 部署。
我们建议从 Kubernetes 的“secrets”中提取敏感变量。
首先,您需要创建您的“holmes-values.yaml”文件,例如:
additionalEnvVars:
- name: MODEL
value: gpt-4o
- name: OPENAI_API_KEY
value: <your open ai key>
然后,通过“helm”安装;
helm repo add robusta https://robusta-charts.storage.googleapis.com && helm repo update
helm install holmes robusta/holmes -f holmes-values.yaml
对于所有 LLM,您需要提供“MODEL”环境变量,指定您使用的是哪个模型。
某些 LLM 需要额外的变量:
OpenAI
对于 OpenAI,仅需提供“model”和“api-key”
additionalEnvVars:
- name: MODEL
value: gpt-4o
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: my-holmes-secret
key: openAiKey
注意:“gpt-4o”是可选的,因为它是默认模型。
Azure OpenAI
要使用 Azure AI,您需要提供以下变量:
additionalEnvVars:
- name: MODEL
value: azure/my-azure-deployment # 你的 Azure 部署名称
- name: AZURE_API_VERSION
value: 2024-02-15-preview # Azure OpenAI API 版本
- name: AZURE_API_BASE
value: https://my-org.openai.azure.com/ # 基础 Azure OpenAI URL
- name: AZURE_API_KEY
valueFrom:
secretKeyRef:
name: my-holmes-secret
key: azureOpenAiKey
AWS Bedrock
enablePostProcessing: true
additionalEnvVars:
- name: MODEL
value: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0
- name: AWS_REGION_NAME
value: us-east-1
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: my-holmes-secret
key: awsAccessKeyId
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: my-holmes-secret
key: awsSecretAccessKey
注意:使用后处理总结结果时,“bedrock claude”提供更好的结果。
获取 API 密钥
HolmesGPT 需要 LLM API 密钥才能运行。最常见的选项是 OpenAI,但也支持许多LiteLLM 兼容的模型。要使用 LLM,请设置 --model
(例如 gpt-4o
或 bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0
)和 --api-key
(如有必要)。根据提供商的不同,您可能还需要设置环境变量。
流行 LLM 的说明:
OpenAI
要使用 OpenAI 的 GPT 3.5 或 GPT-4 模型,您需要一个付费的OpenAI API 密钥。
注意:这不同于成为“ChatGPT Plus”订阅者。
通过 --api-key
CLI 参数将您的 API 密钥传递给 Holmes。由于 OpenAI 是默认的 LLM,因此 --model
标志对于 OpenAI 是可选的(gpt-4o 是默认值)。
holmes ask --api-key="..." "我的集群中哪些 pod 正在崩溃,为什么?"
如果您不希望在 CLI 中传递秘密,可以设置OPENAI_API_KEY环境变量或将API密钥保存在HolmesGPT配置文件中。
Azure OpenAI
要使用 Azure AI,您需要一个Azure OpenAI 资源并设置以下环境变量:
- AZURE_API_VERSION - 例如 2024-02-15-preview
- AZURE_API_BASE - 例如:https://my-org.openai.azure.com/
- AZURE_API_KEY(可选)- 相当于
--api-key
CLI 参数
设置这些环境变量并运行:
holmes ask "哪些 pod 状态不健康,为什么?" --model=azure/<DEPLOYMENT_NAME> --api-key=<API_KEY>
有关更多详细信息,请参阅 LiteLLM Azure 文档 ↗。
AWS Bedrock
在运行以下命令之前,您必须运行 pip install boto3>=1.28.57
并设置以下环境变量:
AWS_REGION_NAME
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
如果您的计算机上已经配置了 AWS CLI,您可以通过以下方式找到这些参数:
cat ~/.aws/credentials ~/.aws/config
一切配置完毕后,运行:
holmes ask "哪些 pod 状态不健康,为什么?" --model=bedrock/<MODEL_NAME>
确保将 MODEL_NAME
替换为您有访问权限的模型-例如 anthropic.claude-3-5-sonnet-20240620-v1:0
。要列出您的帐户可以访问的模型:
aws bedrock list-foundation-models --region=us-east-1
注意,不同的模型在不同的地区可用。例如,Claude Opus 仅在 us-west-2 可用。
有关更多详细信息,请参阅 LiteLLM Bedrock 文档 ↗。
使用自托管 LLM
您将需要一个支持函数调用(工具调用)的 LLM。
- 使用
OPENAI_API_BASE
设置您的 URL 环境变量 - 模型设置为
openai/<您的模型名称>
(例如,llama3.1:latest
) - 设置您的 API 密钥(如果您的 URL 不需要密钥,则为
--api-key
添加一个随机值)
export OPENAI_API_BASE=<URL_HERE>
holmes ask "哪些 pod 状态不健康,为什么?" --model=openai/<MODEL_NAME> --api-key=<API_KEY_HERE>
重要:请确保您的模型和推理服务器支持函数调用!HolmesGPT 目前无法检查所给定的 LLM 是否支持函数调用。某些不具备函数调用能力的模型会产生虚假的答案,而不是报告它们无法调用函数。这种行为取决于模型。
特别需要注意的是,vLLM 尚不支持函数调用,而llama-cpp 支持。
其他用例
HolmesGPT 通常用于应急响应,但它也可以作为通用的 DevOps 助手。以下是一些示例:
询问有关您的云的问题
holmes ask "我的集群暴露了哪些外部服务?"
票务管理 - 自动响应与 DevOps 任务相关的 Jira 票据
holmes investigate jira --jira-url https://<PLACEDHOLDER>.atlassian.net --jira-username <PLACEHOLDER_EMAIL> --jira-api-key <PLACEHOLDER_API_KEY>
找到在大型 Helm 图表中需要更改的配置
LLM 使用内置的 Helm 工具集 来收集信息。
holmes ask "我应该更改哪个 helm 值来增加 my-argo-cd-argocd-server-6864949974-lzp6m pod 的内存请求"
优化 Docker 容器大小
LLM 使用内置的 Docker 工具集 来收集信息。
holmes ask "告诉我 pavangudiwada/robusta-ai docker 镜像的哪些层消耗了最多的存储并提出一些修复建议"
自定义 HolmesGPT
HolmesGPT 能够开箱即用地调查许多问题,无需定制或训练。
尽管如此,我们提供了几个扩展点,以便根据您的最佳实践教 HolmesGPT 调查您的问题。主要的两个扩展点是:
- 自定义工具 - 让 HolmesGPT 访问它无法访问的数据 - 例如,跟踪、APM 数据或自定义 API
- 自定义操作手册 - 给 HolmesGPT 指示,调查特定的问题,否则它不会知道如何处理
添加自定义工具
您提供给 HolmesGPT 的数据越多,它的表现就越好。通过添加自定义工具来让它访问更多的数据。
新工具是通过 custom toolset 文件 或将它们添加到 ~/.holmes/config.yaml
,使用 -t
加载的,设置 custom_toolsets: ["/path/to/toolset.yaml"]
。
添加自定义操作手册
HolmesGPT 可以按照用纯英语编写的操作手册进行调查。添加您自己的操作手册,为 LLM 提供特定的指导。
新操作手册是通过 custom runbook 文件 或将它们添加到 ~/.holmes/config.yaml
,使用 -r
加载的,设置 custom_runbooks: ["/path/to/runbook.yaml"]
。
从配置文件读取设置
您可以使用命令行标志自定义 HolmesGPT 的行为,也可以将常用设置保存在配置文件中以便重复使用。
您可以在 此处 查看带有所有可用设置的示例配置文件。
默认情况下,不指定 --config
时,代理会尝试读取 ~/.holmes/config.yaml
。当配置文件和 CLI 中都存在设置时,CLI 选项优先。
自定义工具集
您可以定义自己的自定义工具集,以扩展设置的功能。这些工具集可以包括查询公司特定数据、从可观测性工具中获取日志等。
# 在此处添加您的自定义工具集的路径
# 示例:["path/to/your/custom_toolset.yaml"]
#custom_toolsets: ["examples/custom_toolset.yaml"]
Alertmanager 配置
配置 Alertmanager 实例的 URL,以启用警报管理和通知。
# Alertmanager 的 URL
#alertmanager_url: "http://localhost:9093"
Jira 集成
集成 Jira 以自动化问题跟踪和项目管理任务。提供您的 Jira 凭证并指定查询以获取问题并可选的更新其状态。
# Jira 凭证和查询设置
#jira_username: "user@company.com"
#jira_api_key: "..."
#jira_url: "https://your-company.atlassian.net"
#jira_query: "项目 = 'Natan Test Project' 并且状态 = '待办'"
- jira_username: 用于登录 Jira 账户的电子邮件地址。例如:
jira-user@company.com
- jira_api_key: 按照这些说明获取你的 API 密钥。
- jira_url: 你的工作区 URL。例如:https://workspace.atlassian.net (注意: 需要使用 https 模式)
- project: 你希望创建 Jira 工单的项目名称。进入 项目设置 -> 详情 -> 名称。
- status: 工单的状态。例如:
待办
,进行中
GitHub 集成
与 GitHub 集成以自动化问题跟踪和项目管理任务。提供你的 GitHub PAT(个人访问令牌)并指定 owner/repository
(所有者/库)。
# GitHub 凭据和查询设置
#github_owner: "robusta-dev"
#github_pat: "..."
#github_url: "https://api.github.com" (默认)
#github_repository: "holmesgpt"
#github_query: "is:issue is:open"
- github_owner: 仓库所有者。例如:
robusta-dev
- github_pat: 按照这些说明获取你的 GitHub PAT(个人访问令牌)。
- github_url: 你的 GitHub API 的 URL。例如:https://api.github.com (注意: 需要使用 https 模式)
- github_repository: 你希望扫描 GitHub 问题的仓库名称。例如:
holmesgpt
。
PagerDuty 集成
与 PagerDuty 集成以自动化事件跟踪和项目管理任务。提供你的 PagerDuty 凭据并指定用户电子邮件以更新带有发现的事件。
pagerduty_api_key: "..."
pagerduty_user_email: "user@mail.com"
pagerduty_incident_key: "..."
- pagerduty_api_key: PagerDuty 的 API 密钥。可以在 PagerDuty 的用户界面中找到:Settings > API Access Key.
- pagerduty_user_email: 当设置 --update 时,哪个用户会被列为更新事件的用户。(必须是你 PagerDuty 账户中的有效用户电子邮件。)
- pagerduty_incident_key: 如果提供,仅分析匹配此密钥的单个 PagerDuty 事件。
OpsGenie 集成
与 OpsGenie 集成以自动化警报调查。提供你的 OpsGenie 凭据并指定要获取警报的查询。
opsgenie_api_key : "..."
opsgenie-team-integration-key: "...."
opsgenie-query: "..."
- opsgenie_api_key: OpsGenie 的 API 密钥。可以从 Settings > API key management > Add new API key 获取。
- opsgenie-team-integration-key: 用于写回结果的 OpsGenie 团队集成密钥(不是普通的 API 密钥)。可以从 Teams > YourTeamName > Integrations > Add Integration > API Key 获取。别忘了开启集成并将团队添加为警报的响应者。
- opsgenie-query: 例如:'message: Foo' (参见 https://support.atlassian.com/opsgenie/docs/search-queries-for-alerts/)
Slack 集成
配置 Slack 以向特定频道发送通知。提供你的 Slack 令牌和所需的通知频道。
# Slack 令牌和频道配置
#slack_token: "..."
#slack_channel: "#general"
- slack-token: Slack API 密钥。你可以通过
pip install robusta-cli && robusta integrations slack
生成。 - slack-channel: 你希望接收发现的 Slack 频道。
自定义运行手册
定义自定义运行手册,以向 LLM 说明如何调查某些警报。这有助于在已知警报中取得更好的结果。
# 在此处添加自定义运行手册的路径
# 例如: ["path/to/your/custom_runbook.yaml"]
#custom_runbooks: ["examples/custom_runbooks.yaml"]
大型语言模型(LLM)配置
在 OpenAI、Azure、AWS Bedrock 等之间进行选择。提供所选服务的必要 API 密钥和端点。
OpenAI
# OpenAI LLM 配置
#api_key: "your-secret-api-key"
Azure
# Azure LLM 配置
#api_key: "your-secret-api-key"
#model: "azure/<DEPLOYMENT_NAME>"
#你还需要设置环境变量 - 参见上文
Bedrock
# AWS Bedrock LLM 配置
#model: "bedrock/<MODEL_ID>"
#你还需要设置环境变量 - 参见上文
许可证
根据 MIT 许可证分发。更多信息请参见 LICENSE.txt。
支持
如果你有任何疑问,请在 robustacommunity.slack.com 上联系我们。
如何贡献
要贡献给 HolmesGPT,请首先按照安装指南从源代码运行 HolmesGPT。然后按照下面的适当指南操作,或者在 Slack 上向我们请求帮助。
添加新的运行手册
你可以贡献解决常见警报的知识,HolmesGPT 将利用这些知识来解决相关问题。为此,请在 ./holmes/plugins/runbooks 中添加一个新文件 - 或编辑该目录中的现有运行手册文件。
注意:如果你更愿意将运行手册保持私有,你可以将它们存储在本地,并通过 -r
标志传递给 HolmesGPT。然而,如果你的运行手册与其他人可能遇到的常见问题相关,请考虑提交一个 PR,使 HolmesGPT 对所有人都更好!
添加新的工具集
你可以在 YAML 中添加定义新工具,HolmesGPT 将在调查中使用这些工具。为此,请在 ./holmes/plugins/toolsets 中添加一个新文件 - 或编辑该目录中的现有工具集文件。
注意:如果你更愿意将工具集保持私有,你可以将它们存储在本地,并通过 -t
标志传递给 HolmesGPT。然而,请考虑贡献你的工具集!至少一位社区成员可能会发现它们有用!
修改默认提示(提示工程)
HolmesGPT 的默认提示位于 ./holmes/plugins/prompts 中。大多数 holmes
命令接受一个 --system-prompt
标志,你可以用它来覆盖此设置。
如果你发现默认提示不起作用的情况,请考虑通过打开 GitHub 问题或在 Slack 上联系我们,让我们知道!我们有一个内部评估框架,可以在许多故障排除场景中对提示进行基准测试,如果你分享一个 HolmesGPT 不起作用的案例,我们将能够将其添加到我们的测试框架中,并解决该问题及类似问题的性能。
添加新数据源
如果你希望 HolmesGPT 调查外部工单或警报,可以添加新数据源。这需要修改源代码并提交 PR。你可以在这里看到一个示例 PR,该 PR 添加了支持调查 GitHub 问题。