{"id":13584827,"url":"https://github.com/elastic/sysgrok","last_synced_at":"2025-10-10T22:15:19.922Z","repository":{"id":176962877,"uuid":"640964274","full_name":"elastic/sysgrok","owner":"elastic","description":"LLM-driven assistant for analyzing, understanding and optimizing systems","archived":false,"fork":false,"pushed_at":"2024-08-09T06:32:38.000Z","size":132,"stargazers_count":115,"open_issues_count":16,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-06T00:34:55.910Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elastic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-15T13:46:56.000Z","updated_at":"2025-08-29T11:57:29.000Z","dependencies_parsed_at":"2024-12-16T14:45:50.099Z","dependency_job_id":"5fa5273d-3777-4623-9921-8b68a54a1e17","html_url":"https://github.com/elastic/sysgrok","commit_stats":{"total_commits":121,"total_committers":3,"mean_commits":"40.333333333333336","dds":0.2644628099173554,"last_synced_commit":"2667fbcf74498689c99c26498d27428402cbed0f"},"previous_names":["elastic/sysgrok"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/elastic/sysgrok","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsysgrok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsysgrok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsysgrok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsysgrok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elastic","download_url":"https://codeload.github.com/elastic/sysgrok/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elastic%2Fsysgrok/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005466,"owners_count":26083900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:04:32.783Z","updated_at":"2025-10-10T22:15:19.880Z","avatar_url":"https://github.com/elastic.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"`sysgrok` is an experimental proof-of-concept, intended to demonstrate how\nLLMs can be used to help SWEs and SREs to understand systems, debug issues, and optimise performance.\n\nIt can do things like:\n\n* Take the top most expensive functions and processes identified by a profiler, explain\nthe functionality that each provides, and suggest optimisations.\n* Take a host and a description of a problem that host is encountering and automatically\ndebug the issue and suggest remediations.\n* Take source code that has been annotated by a profiler, explain the hot paths, and\nsuggest ways to improve the performance of the code.\n\nCheck out the release [blog post](https://www.elastic.co/blog/open-sourcing-sysgrok-ai-assistant) for\na longer introduction. \n\nSee the Command Overview section below for an overview of the full list of available\ncommands that it supports.\n\nHere's an example using the `analyzecmd` sub-command, which connects to a remote host,\nexecutes one or more commands, and summarises the result. The demo shows how this can be\nused to automate the process described in Brendan Gregg's article -\n[Linux Performance Analysis in 60 seconds](https://www.brendangregg.com/Articles/Netflix_Linux_Perf_Analysis_60s.pdf).\n\n[![asciicast](https://asciinema.org/a/593518.svg)](https://asciinema.org/a/593518)\n\n# Installation\n\n1. Copy `.env.example` to `.env` and fill the required variables. The `GAI_API_TYPE` must be either \"azure\" or \"openai\",\nand the `GAI_API_KEY` must be your API key. If you are using an Azure endpoint then you must also provide the\n`GAI_API_BASE` and `GAI_API_VERSION` variables. The correct values for these can be found in your Azure portal.\n\n2. Install requirements via pip\n\n```\n$ python -m venv venv # Create a virtual environment\n$ source venv/bin/activate # Activate the virtual environment\n$ pip install -r requirements.txt # Install requirements in the virtual environment\n```\n\n# Usage\n\nFor now, `sysgrok` is a command line tool and takes input either via stdin\nor from a file, depending on the command. Usage is as follows:\n\n```\nusage: ./sysgrok.py [-h] [-d] [-e] [-c] [--output-format OUTPUT_FORMAT] [-m MODEL] [--temperature TEMPERATURE] [--max-concurrent-queries MAX_CONCURRENT_QUERIES]\n                    {analyzecmd,code,explainfunction,explainprocess,debughost,findfaster,stacktrace,topn} ...\n\n                               _\n ___ _   _ ___  __ _ _ __ ___ | | __\n/ __| | | / __|/ _` | '__/ _ \\| |/ /\n\\__ \\ |_| \\__ \\ (_| | | | (_) |   \u003c\n|___/\\__, |___/\\__, |_|  \\___/|_|\\_\n     |___/     |___/\n\nSystem analysis and optimisation with LLMs\n\npositional arguments:\n  {analyzecmd,code,explainfunction,explainprocess,debughost,findfaster,stacktrace,topn}\n                        The sub-command to execute\n    analyzecmd          Summarise the output of a command, optionally with respect to a problem under investigation\n    code                Summarise profiler-annoted code and suggest optimisations\n    explainfunction     Explain what a function does and suggest optimisations\n    explainprocess      Explain what a process does and suggest optimisations\n    debughost           Debug an issue by executing CLI tools and interpreting the output\n    findfaster          Search for faster alternatives to a provided library or program\n    stacktrace          Summarise a stack trace and suggest changes to optimise the software\n    topn                Summarise Top-N output from a profiler and suggest improvements\n\noptions:\n  -h, --help            show this help message and exit\n  -d, --debug           Debug output\n  -e, --echo-input      Echo the input provided to sysgrok. Useful when input is piped in and you want to see what it is\n  -c, --chat            Enable interactive chat after each LLM response\n  --output-format OUTPUT_FORMAT\n                        Specify the output format for the LLM to use\n  -m MODEL, --model-or-deployment-id MODEL\n                        The OpenAI model, or Azure deployment ID, to use.\n  --temperature TEMPERATURE\n                        ChatGPT temperature. See OpenAI docs.\n  --max-concurrent-queries MAX_CONCURRENT_QUERIES\n                        Maximum number of parallel queries to OpenAI\n```\n\n# Feature Requests, Bugs and Suggestions\n\nPlease log them via the Github Issues tab. If you have specific requests or bugs\nthen great, but I'm also happy to discuss open-ended topics, future work, and\nideas.\n\n# Adding a New Command\n\nAdding a new command is easy. You need to:\n1. Create a file, yourcommand.py, in the `sysgrok/commands` directory. It's\nlikely easiest to just copy an existing command, e.g. `stacktrace.py`\n2. Your command file needs to have the following components:\n    * A top level `command` variable which is the name users will use to invoke\n    your command\n    * A top level `help` variable describing the command, and which will appear\n    when the `-h` flag is passed.\n    * A `add_to_command_subparsers` function which should add a sub-parser\n    which will handle the command line arguments that are specific to your\n    command.\n    * A `run` function that is the interface to your command. It will be the\n    function that creates the LLM queries and produces a result. It should\n    return 0 upon success, or -1 otherwise.\n3. Update `sysgrok.py`:\n    * Add your command to the imports\n    * Add your command to the `commands` dict.\n\n# Examples\n\nNote 1: The output of `sysgrok` is heavily dependent on the input prompts, and\nI am still experimenting with them. This means that the output you get from\nrunning `sysgrok` may differ from what you see below. It may also vary based\non minor differences in your input format, or the usual quirks of LLMs. If you\nhave an example where the output you get from a command is incorrect or\notherwise not helpful, please file an issue and let me know. If I can figure out\nhow to get `sysgrok` to act more usefully, I will.\n\nNote 2: The output of `sysgrok` is also heavily dependent on the OpenAI model\nused. The default is `gpt-3.5-turbo` and these examples have been generated\nusing that. See the usage docs for other options. If the results you get are not\ngood enough with `gpt-3.5-turbo` then try `gpt-4`. It is slower and more\nexpensive but may provide higher quality output.\n\n## Finding faster replacement programs and libraries\n\nOne of the easiest wins in optimisation is replacing an existing library with\na functionally equivalent, faster, alternative. Usually this process begins\nwith an engineering looking at the Top-N output of their profiler, which lists\nthe most expensive libraries and functions in their system, and then going on\na hunt for an optimised version. The `findfaster` command solves this problem\nfor you. Here are some examples.\n\n[![asciicast](https://asciinema.org/a/593479.svg)](https://asciinema.org/a/593479)\n\n## Analysing the TopN functions and suggesting optimisations\n\nA good starting place for analysing a system is often looking at what libraries\nand functions your profiler tells you are using the most CPU. Most commercial\nprofilers will have a tab for this information, and you can get it from `perf`\nvia `perf report --stdio --max-stack=0`. One of the stumbling blocks when\nencountering this data is that firstly you need to understand what each\nprogram, library and function actually is, and then you need to come up with\nideas for how to optimise them. This is made even more complicated in the\nworld of whole-system, or whole-data-center, profiling, where there are a\nhuge number of programs and libraries running, and you are often unfamiliar\nwith many of them.\n\nThe `sysgrok topn` command helps with this. Provide it with your Top-N, and\nit will try to summarise what each program, library and function is doing, as\nwell as providing you with some suggestions as to what you might do to\noptimise your system.\n\n[![asciicast](https://asciinema.org/a/593492.svg)](https://asciinema.org/a/593492)\n\n## Explaining a specific function and suggesting optimisations\n\nIf you know a particular function is using signficant CPU then, using the\n`explainfunction` command, you can ask for an explanation of that\nspecific function, and for optimistion suggestions, instead of asking about\nthe entire Top N.\n\n[![asciicast](https://asciinema.org/a/593483.svg)](https://asciinema.org/a/593483)\n\n## Executing commands on a remote host and analysing the response using the LLM\n\nThe `analyzecmd` command takes a host and one or more Linux commands to execute.\nIt connects to the host, executes the commands and summarises the results. You can\nalso provide it with an optional description of an issue you are investigating, and\nthe command output will be summarised with respect to that problem.\n\nThis first example shows how one or more commands can be executed.\n\n[![asciicast](https://asciinema.org/a/593515.svg)](https://asciinema.org/a/593515)\n\nWe can also use `analyzecmd` to analyse commands that produce logs.\n\n[![asciicast](https://asciinema.org/a/593516.svg)](https://asciinema.org/a/593516)\n\nAnd in this final example we execute and analyze the commands recommended by\nBrendan Gregg  in his article \"Linux Performance Analysis in 60 seconds\".\n\n[![asciicast](https://asciinema.org/a/593518.svg)](https://asciinema.org/a/593518)\n\n## Automatically debug a problem on a host\n\nThe `debughost` command takes a host and a problem description and then:\n\n1. Queries the LLM for commands to run that may generate information useful in\ndebugging the problem.\n2. Connects to the host via ssh and executes the commands\n3. Uses the LLM to summarise the output of each command, individually.\n4. Concatenates the summaries and passes them to the LLM to ask for a report on\nthe likely source of the problem the user is facing.\n\n[![asciicast](https://asciinema.org/a/593520.svg)](https://asciinema.org/a/593520)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fsysgrok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felastic%2Fsysgrok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felastic%2Fsysgrok/lists"}