Awesome

Transforms your existing cloud alerts from this 👇

To this 👇

Key Features

• Automatic data collection: HolmesGPT surfaces up the observability data you need to investigate
• Runbook automation and knowledge sharing: Tell Holmes how you investigate today and it will automate it
• Extensible: Add your own data sources (tools) and Holmes will use them to investigate
• Data Privacy: Bring your own API key for any AI provider (OpenAI, Azure, AWS Bedrock, etc)
• Integrates with your existing tools including Prometheus, PagerDuty, OpsGenie, Jira, and more

See it in Action

Ways to Use HolmesGPT

Sign up for Robusta SaaS (Kubernetes cluster required) or contact us about on-premise options.

Investigate Prometheus alerts right from Slack with the official Robusta integration.

Or run HolmesGPT from the cli:

kubectl port-forward alertmanager-robusta-kube-prometheus-st-alertmanager-0 9093:9093 &
holmes investigate alertmanager --alertmanager-url http://localhost:9093

Note - if on Mac OS and using the Docker image, you will need to use http://docker.for.mac.localhost:9093 instead of http://localhost:9093

holmes ask "what pods are in crashloopbackoff in my cluster and why?"

holmes investigate opsgenie --opsgenie-api-key <PLACEHOLDER_APIKEY>

By default results are displayed in the CLI . Use --update --opsgenie-team-integration-key <PLACEHOLDER_TEAM_KEY> to get the results as a comment in the OpsGenie alerts. Refer to the CLI help for more info.

holmes investigate pagerduty --pagerduty-api-key <PLACEHOLDER_APIKEY>

By default results are displayed in the CLI. Use --update --pagerduty-user-email <PLACEHOLDER_EMAIL> to get the results as a comment in the PagerDuty issue. Refer to the CLI help for more info.

You can add HolmesGPT as a plugin for K9s to investigate why any Kubernetes resource is unhealthy.

Add the following contents to the K9s plugin file, typically ~/.config/k9s/plugins.yaml on Linux and ~/Library/Application Support/k9s/plugins.yaml on Mac. Read more about K9s plugins here and check your plugin path here.

Note: HolmesGPT must be installed and configured for the K9s plugin to work.

Basic plugin to run an investigation on any Kubernetes object, using the shortcut Shift + H:

plugins:
  holmesgpt:
    shortCut: Shift-H
    description: Ask HolmesGPT
    scopes:
      - all
    command: bash
    background: false
    confirm: false
    args:
      - -c
      - |
        holmes ask "why is $NAME of $RESOURCE_NAME in -n $NAMESPACE not working as expected"
        echo "Press 'q' to exit"
        while : ; do
        read -n 1 k <&1
        if [[ $k = q ]] ; then
        break
        fi
        done

Advanced plugin that lets you modify the questions HolmesGPT asks about the LLM, using the shortcut Shift + O. (E.g. you can change the question to "generate an HPA for this deployment" and the AI will follow those instructions and output an HPA configuration.)

plugins:
  custom-holmesgpt:
    shortCut: Shift-Q
    description: Custom HolmesGPT Ask
    scopes:
      - all
    command: bash
    background: false
    confirm: false
    args:
      - -c
      - |
        INSTRUCTIONS="# Edit the line below. Lines starting with '#' will be ignored."
        DEFAULT_ASK_COMMAND="why is $NAME of $RESOURCE_NAME in -n $NAMESPACE not working as expected"
        QUESTION_FILE=$(mktemp)

        echo "$INSTRUCTIONS" > "$QUESTION_FILE"
        echo "$DEFAULT_ASK_COMMAND" >> "$QUESTION_FILE"

        # Open the line in the default text editor
        ${EDITOR:-nano} "$QUESTION_FILE"

        # Read the modified line, ignoring lines starting with '#'
        user_input=$(grep -v '^#' "$QUESTION_FILE")
        echo running: holmes ask "\"$user_input\""

        holmes ask "$user_input"
        echo "Press 'q' to exit"
        while : ; do
        read -n 1 k <&1
        if [[ $k = q ]] ; then
        break
        fi
        done

Like what you see? Checkout other use cases or get started by installing HolmesGPT.

Installation

Prerequisite: <a href="#getting-an-api-key"> Get an API key for a supported LLM.</a>

Installation Methods:

1. Add our tap:

brew tap robusta-dev/homebrew-holmesgpt

2. Install holmesgpt:

brew install holmesgpt

3. Check that installation was successful. This will take a few seconds on the first run - wait patiently.:

holmes --help

4. Run holmesgpt:

holmes ask "what issues do I have in my cluster"

Run the prebuilt Docker container docker.pkg.dev/genuine-flight-317411/devel/holmes, with extra flags to mount relevant config files (so that kubectl and other tools can access AWS/GCP resources using your local machine's credentials)

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 ask "what pods are unhealthy and why?"

You can install HolmesGPT from the latest git version with pip or pipx.

We recommend using pipx because it guarantees that HolmesGPT is isolated from other python packages on your system, preventing dependency conflicts.

First Pipx (skip this step if you are using pip).

Then install HolmesGPT from git with either pip or pipx:

pipx install "https://github.com/robusta-dev/holmesgpt/archive/refs/heads/master.zip"

Verify that HolmesGPT was installed by checking the version:

holmes version

To upgrade HolmesGPT with pipx, you can run:

pipx upgrade holmesgpt

First install poetry (the python package manager)

git clone https://github.com/robusta-dev/holmesgpt.git
cd holmesgpt
poetry install --no-root
poetry run python3 holmes.py ask "what pods are unhealthy and why?"

Clone the project from github, and then run:

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 "what pods are unhealthy and why?"

Most users should install Holmes using the instructions in the Robusta docs ↗ and NOT the below instructions.

By using the Robusta integration you’ll benefit from an end-to-end integration that integrates with Prometheus alerts and Slack. Using the below instructions you’ll have to build many of those components yourself.

In this mode, all the parameters should be passed to the HolmesGPT deployment, using environment variables.

We recommend pulling sensitive variables from Kubernetes secrets.

First, you'll need to create your holmes-values.yaml file, for example:

additionalEnvVars:
- name: MODEL
  value: gpt-4o
- name: OPENAI_API_KEY
  value: <your open ai key>

Then, install with helm;

helm repo add robusta https://robusta-charts.storage.googleapis.com && helm repo update
helm install holmes robusta/holmes -f holmes-values.yaml

For all LLMs you need to provide the MODEL environment variable, which specifies which model you are using.

Some LLMs requires additional variables:

For OpenAI, only the model and api-key should be provided

additionalEnvVars:
- name: MODEL
  value: gpt-4o
- name: OPENAI_API_KEY
  valueFrom:
    secretKeyRef:
      name: my-holmes-secret
      key: openAiKey

Note: gpt-4o is optional since it's default model.

To work with Azure AI, you need to provide the below variables:

additionalEnvVars:
- name: MODEL
  value: azure/my-azure-deployment         # your azure deployment name
- name: AZURE_API_VERSION
  value: 2024-02-15-preview                # azure openai api version
- name: AZURE_API_BASE
  value: https://my-org.openai.azure.com/  # base azure openai url
- name: AZURE_API_KEY
  valueFrom:
    secretKeyRef:
      name: my-holmes-secret
      key: azureOpenAiKey

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

Note: bedrock claude provides better results when using post-processing to summarize the results.

Trusting custom Certificate Authority (CA) certificate:

If your llm provider url uses a certificate from a custom CA, in order to trust it, base-64 encode the certificate, and store it in an environment variable named CERTIFICATE

Getting an API Key

HolmesGPT requires an LLM API Key to function. The most common option is OpenAI, but many LiteLLM-compatible models are supported. To use an LLM, set --model (e.g. gpt-4o or bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0) and --api-key (if necessary). Depending on the provider, you may need to set environment variables too.

Instructions for popular LLMs:

To work with OpenAI’s GPT 3.5 or GPT-4 models you need a paid OpenAI API key.

Note: This is different from being a “ChatGPT Plus” subscriber.

Pass your API key to holmes with the --api-key cli argument. Because OpenAI is the default LLM, the --model flag is optional for OpenAI (gpt-4o is the default).

holmes ask --api-key="..." "what pods are crashing in my cluster and why?"

If you prefer not to pass secrets on the cli, set the OPENAI_API_KEY environment variable or save the API key in a HolmesGPT config file.

To work with Azure AI, you need an Azure OpenAI resource and to set the following environment variables:

• AZURE_API_VERSION - e.g. 2024-02-15-preview
• AZURE_API_BASE - e.g. https://my-org.openai.azure.com/
• AZURE_API_KEY (optional) - equivalent to the --api-key cli argument

Set those environment variables and run:

holmes ask "what pods are unhealthy and why?" --model=azure/<DEPLOYMENT_NAME> --api-key=<API_KEY>

Refer LiteLLM Azure docs ↗ for more details.

Before running the below command you must run pip install boto3>=1.28.57 and set the following environment variables:

• AWS_REGION_NAME
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

If the AWS cli is already configured on your machine, you may be able to find those parameters with:

cat ~/.aws/credentials ~/.aws/config

Once everything is configured, run:

holmes ask "what pods are unhealthy and why?" --model=bedrock/<MODEL_NAME>

Be sure to replace MODEL_NAME with a model you have access to - e.g. anthropic.claude-3-5-sonnet-20240620-v1:0. To list models your account can access:

aws bedrock list-foundation-models --region=us-east-1

Note that different models are available in different regions. For example, Claude Opus is only available in us-west-2.

Refer to LiteLLM Bedrock docs ↗ for more details.

If you'd like to try using Ollama anyway, see below:

export OLLAMA_API_BASE="http://localhost:11434"
holmes ask "what pods are unhealthy in my cluster?" --model="ollama_chat/llama3.1"

You can also connect to Ollama in the standard OpenAI format (this should be equivalent to the above):

# note the v1 at the end
export OPENAI_API_BASE="http://localhost:11434/v1"
# holmes requires OPENAPI_API_KEY to be set but value does not matter
export OPENAI_API_KEY=123
holmes ask "what pods are unhealthy in my cluster?" --model="openai/llama3.1"

You will need an LLM with support for function-calling (tool-calling).

• Set the environment variable for your URL with OPENAI_API_BASE
• Set the model as openai/<your-model-name> (e.g., llama3.1:latest)
• Set your API key (if your URL doesn't require a key, then add a random value for --api-key)

export OPENAI_API_BASE=<URL_HERE>
holmes ask "what pods are unhealthy and why?" --model=openai/<MODEL_NAME> --api-key=<API_KEY_HERE>

Important: Please verify that your model and inference server support function calling! HolmesGPT is currently unable to check if the LLM it was given supports function-calling or not. Some models that lack function-calling capabilities will hallucinate answers instead of reporting that they are unable to call functions. This behaviour depends on the model.

In particular, note that vLLM does not yet support function calling, whereas llama-cpp does support it.

Enabling Integrations

• CONFLUENCE_BASE_URL - e.g. https://robusta-dev-test.atlassian.net
• CONFLUENCE_USER - e.g. user@company.com
• CONFLUENCE_API_KEY - refer to Atlassian docs on generating API keys

HolmesGPT can pull tickets/alerts from each of these sources and investigate them.

Refer to holmes investigate jira --help etc for details, or view the <a href="#examples">examples</a>.

HolmesGPT can consult webpages containing runbooks or other relevant information. HolmesGPT uses playwright to scrape webpages and requires playwright to be installed and working through playwright install.

Other Use Cases

HolmesGPT was designed for incident response, but it is a general DevOps assistant too. Here are some examples:

holmes ask "what services does my cluster expose externally?"

holmes investigate jira  --jira-url https://<PLACEDHOLDER>.atlassian.net --jira-username <PLACEHOLDER_EMAIL> --jira-api-key <PLACEHOLDER_API_KEY>

LLM uses the built-in Helm toolset to gather information.

holmes ask "what helm value should I change to increase memory request of the my-argo-cd-argocd-server-6864949974-lzp6m pod"

LLM uses the built-in Docker toolset to gather information.

holmes ask "Tell me what layers of my pavangudiwada/robusta-ai docker image consume the most storage and suggest some fixes to it"

Customizing HolmesGPT

HolmesGPT can investigate many issues out of the box, with no customization or training.

That said, we provide several extension points for teaching HolmesGPT to investigate your issues, according to your best practices. The two main extension points are:

• Custom Tools - give HolmesGPT access to data that it can't otherwise access - e.g. traces, APM data, or custom APIs
• Custom Runbooks - give HolmesGPT instructions for investigating specific issues it otherwise wouldn't know how to handle

The more data you give HolmesGPT, the better it will perform. Give it access to more data by adding custom tools.

New tools are loaded using -t from custom toolset files or by adding them to the ~/.holmes/config.yaml with the setting custom_toolsets: ["/path/to/toolset.yaml"].

HolmesGPT can investigate by following runbooks written in plain English. Add your own runbooks to provided the LLM specific instructions.

New runbooks are loaded using -r from custom runbook files or by adding them to the ~/.holmes/config.yaml with the custom_runbooks: ["/path/to/runbook.yaml"].

You can customize HolmesGPT's behaviour with command line flags, or you can save common settings in config file for re-use.

You can view an example config file with all available settings here.

By default, without specifying --config the agent will try to read ~/.holmes/config.yaml. When settings are present in both config file and cli, the cli option takes precedence.

You can define your own custom toolsets to extend the functionality of your setup. These toolsets can include querying company-specific data, fetching logs from observability tools, and more.

# Add paths to your custom toolsets here
# Example: ["path/to/your/custom_toolset.yaml"]
#custom_toolsets: ["examples/custom_toolset.yaml"]

Configure the URL for your Alertmanager instance to enable alert management and notifications.

# URL for the Alertmanager
#alertmanager_url: "http://localhost:9093"

Integrate with Jira to automate issue tracking and project management tasks. Provide your Jira credentials and specify the query to fetch issues and optionally update their status.

# Jira credentials and query settings
#jira_username: "user@company.com"
#jira_api_key: "..."
#jira_url: "https://your-company.atlassian.net"
#jira_query: "project = 'Natan Test Project' and Status = 'To Do'"

1. jira_username: The email you use to log into your Jira account. Eg: jira-user@company.com
2. jira_api_key: Follow these instructions to get your API key.
3. jira_url: The URL of your workspace. For example: https://workspace.atlassian.net (Note: schema (https) is required)
4. project: Name of the project you want the Jira tickets to be created in. Go to Project Settings -> Details -> Name.
5. status: Status of a ticket. Example: To Do, In Progress

Integrate with GitHub to automate issue tracking and project management tasks. Provide your GitHub PAT (personal access token) and specify the owner/repository.

# GitHub credentials and query settings
#github_owner: "robusta-dev"
#github_pat: "..."
#github_url: "https://api.github.com" (default)
#github_repository: "holmesgpt"
#github_query: "is:issue is:open"

1. github_owner: The repository owner. Eg: robusta-dev
2. github_pat: Follow these instructions to get your GitHub pat (personal access token).
3. github_url: The URL of your GitHub API. For example: https://api.github.com (Note: schema (https) is required)
4. github_repository: Name of the repository you want the GitHub issues to be scanned. Eg: holmesgpt.

Integrate with PagerDuty to automate incident tracking and project management tasks. Provide your PagerDuty credentials and specify the user email to update the incident with findings.

pagerduty_api_key: "..."
pagerduty_user_email: "user@mail.com"
pagerduty_incident_key:  "..."

1. pagerduty_api_key: The PagerDuty API key. This can be found in the PagerDuty UI under Integrations > API Access Key.
2. pagerduty_user_email: When --update is set, which user will be listed as the user who updated the incident. (Must be the email of a valid user in your PagerDuty account.)
3. pagerduty_incident_key: If provided, only analyze a single PagerDuty incident matching this key

Integrate with OpsGenie to automate alert investigations. Provide your OpsGenie credentials and specify the query to fetch alerts.

opsgenie_api_key : "..."
opsgenie-team-integration-key: "...."
opsgenie-query: "..."

1. opsgenie_api_key: The OpsGenie API key. Get it from Settings > API key management > Add new API key
2. opsgenie-team-integration-key: OpsGenie Team Integration key for writing back results. (NOT a normal API Key.) Get it from Teams > YourTeamName > Integrations > Add Integration > API Key. Don't forget to turn on the integration and add the Team as Responders to the alert.
3. opsgenie-query: E.g. 'message: Foo' (see https://support.atlassian.com/opsgenie/docs/search-queries-for-alerts/)

Configure Slack to send notifications to specific channels. Provide your Slack token and the desired channel for notifications.

# Slack token and channel configuration
#slack_token: "..."
#slack_channel: "#general"

1. slack-token: The Slack API key. You can generate with pip install robusta-cli && robusta integrations slack
2. slack-channel: The Slack channel where you want to receive the findings.

Define custom runbooks to give explicit instructions to the LLM on how to investigate certain alerts. This can help in achieving better results for known alerts.

# Add paths to your custom runbooks here
# Example: ["path/to/your/custom_runbook.yaml"]
#custom_runbooks: ["examples/custom_runbooks.yaml"]

Large Language Model (LLM) Configuration

Choose between OpenAI, Azure, AWS Bedrock, and more. Provide the necessary API keys and endpoints for the selected service.

# Configuration for OpenAI LLM
#api_key: "your-secret-api-key"

# Configuration for Azure LLM
#api_key: "your-secret-api-key"
#model: "azure/<DEPLOYMENT_NAME>"
#you will also need to set environment variables - see above

# Configuration for AWS Bedrock LLM
#model: "bedrock/<MODEL_ID>"
#you will also need to set environment variables - see above

License

Distributed under the MIT License. See LICENSE.txt for more information.

Support

If you have any questions, feel free to message us on robustacommunity.slack.com

How to Contribute

To contribute to HolmesGPT, first follow the <a href="#installation"><strong>Installation</strong></a> instructions for running HolmesGPT from source using Poetry. Then follow an appropriate guide below, or ask us for help on Slack

You can contribute knowledge on solving common alerts and HolmesGPT will use this knowledge to solve related issues. To do so, add a new file to ./holmes/plugins/runbooks - or edit an existing runbooks file in that same directory.

Note: if you prefer to keep your runbooks private, you can store them locally and pass them to HolmesGPT with the -r flag. However, if your runbooks relate to common problems that others may encounter, please consider opening a PR and making HolmesGPT better for everyone!

You can add define new tools in YAML and HolmesGPT will use those tools in it's investigation. To do so, add a new file to ./holmes/plugins/toolsets - or edit an existing toolsets file in that same directory.

Note: if you prefer to keep your tools private, you can store them locally and pass them to HolmesGPT with the -t flag. However, please consider contributing your toolsets! At least one other community member will probably find them useful!

The default prompts for HolmesGPT are located in ./holmes/plugins/prompts. Most holmes commands accept a --system-prompt flag that you can use to override this.

If you find a scenario where the default prompts don't work, please consider letting us know by opening a GitHub issue or messaging us on Slack! We have an internal evaluation framework for benchmarking prompts on many troubleshooting scenarios and if you share a case where HolmesGPT doesn't work, we will be able to add it to our test framework and fix the performance on that issue and similar ones.

If you want HolmesGPT to investigate external tickets or alert, you can add a new datasource. This requires modifying the source code and opening a PR. You can see an example PR like that here, which added support for investigating GitHub issues.