{"id":15978636,"url":"https://github.com/xperimental/ipromnb","last_synced_at":"2025-06-22T07:01:56.334Z","repository":{"id":41262426,"uuid":"141463975","full_name":"xperimental/ipromnb","owner":"xperimental","description":"Jupyter notebook kernel for running Prometheus queries.","archived":false,"fork":false,"pushed_at":"2018-08-09T11:17:38.000Z","size":4846,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T06:44:04.875Z","etag":null,"topics":["data-science","jupyter-notebook","jupyter-notebook-kernel","prometheus"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xperimental.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-18T16:52:15.000Z","updated_at":"2023-10-24T19:58:18.000Z","dependencies_parsed_at":"2022-09-10T07:41:06.867Z","dependency_job_id":null,"html_url":"https://github.com/xperimental/ipromnb","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/xperimental/ipromnb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fipromnb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fipromnb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fipromnb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fipromnb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xperimental","download_url":"https://codeload.github.com/xperimental/ipromnb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fipromnb/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261250176,"owners_count":23130533,"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","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":["data-science","jupyter-notebook","jupyter-notebook-kernel","prometheus"],"created_at":"2024-10-07T23:21:37.168Z","updated_at":"2025-06-22T07:01:51.311Z","avatar_url":"https://github.com/xperimental.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Docker Build Status](https://img.shields.io/docker/build/xperimental/ipromnb.svg?style=flat-square)](https://hub.docker.com/r/xperimental/ipromnb/)\n\n# ipromnb\n\nKernel for [Jupyter Notebooks](http://jupyter.org/) which can query [Prometheus](https://prometheus.io/) servers.\n\nBecause notebooks can also contain documentation this makes it ideal for things like\n\n- prototyping new queries for future dashboards\n- documenting an outage using metrics\n\nThe generated files also contain the results of the queries and so are self-contained and can be read without actively querying the Prometheus server that was used to generate them. This is ideal for sharing thoughts or for archival purposes. GitHub also contains a preview renderer, have a look at [the example file](_examples/Test.ipynb).\n\n## Usage\n\n### Starting an instance\n\nFor easy start there is a Docker image: [`xperimental/ipromnb`](https://hub.docker.com/r/xperimental/ipromnb/) which is directly runnable.\n\nThere's also a `docker-compose.yml` file in this repo, so manually building and running an image should be as easy as (if you have Docker and docker-compose installed):\n\n```bash\ngit clone https://github.com/xperimental/ipromnb.git\ncd ipromnb\ndocker-compose up --build\n```\n\nThis will run a jupyter notebooks instance and map it to port 8888. The directory the repository is in will be mounted as a volume in the \"work\" directory accessible in the Notebook UI.\n\nCheck the `_examples` directory for a simple [example notebook](_examples/Test.ipynb).\n\n### Creating your first notebook\n\nThis example assumes that a Prometheus server is available using the URL `http://prometheus:9090/`.\n\nJupyter notebooks contain blocks (so called \"cells\") that can either be `Code` or `Markdown`. The Markdown is rendered as HTML and can be used for descriptions. The Code cells are rendered by the so-called \"kernel\" used for the notebook. This project provides a kernel that will interpret the code cells as queries which are to be sent to a Prometheus server.\n\nFor this to work the kernel first needs to know which server to send the queries to, so create a first code block and set its contents to:\n\n```plain\n@server=http://prometheus:9090\n```\n\nOnce you run the cell (by using the keyboard shortcut or the small play button to its left) you should get an output similar to the one below (the time will be different):\n\n```plain\nServer: http://prometheus:9090\n  Time: 2018-08-07T20:32:13Z - 2018-08-08T20:32:13Z (24h0m0.000000578s)\n```\n\nNew create a second code cell and type the following into it:\n\n```plain\nup\n```\n\nAgain, run the cell. You should get a small table with all your \"up\" metrics, similar to the \"Console\" inside Prometheus.\n\nNow, let's finally create a graph. Again, create a new cell (or resume the one from the \"up\" example) and put the following content into it:\n\n```plain\ngraph(sum by(job) (rate(scrape_samples_scraped[30m])))\n```\n\nWhen you run this cell, the output below should be a graph plotting your sample rates per job. The `graph()` function is not part of the Prometheus query language but instead interpreted by the `ipromnb` kernel to produce the graph output.\n\nThere are also commands to change the timeframe used for the queries. Modify the first cell (the one with the `@server` command in it) to show the following content:\n\n```plain\n@server=http://prometheus:9090\n@end=now\n@start=end-12h\n```\n\nThis sets the timeframe to \"from 12 hours ago until now\". The times can either be given relative to `now`, `start` or `end` or in RFC3339 format (for example `2018-08-08T12:00:00Z`).\n\nNow let's restart the notebook and watch what happens. To do this select the \"Restart \u0026 Run All\" item from the \"Kernel\" menu at the top. This restarts the kernel and re-runs all the code blocks. You should now have output that reflects the changed timeframe in all outputs.\n\n### Commands interpreted by kernel\n\nThe kernel tries to interpret every code cell as a query to the Prometheus server except if it is a command that is directly executed by the kernel itself.\n\n#### Setting options\n\nAll the internal commands modify internal state of the kernel, which means that they have an effect for all subsequent cell executions until the kernel is either restarted or another command is issued.\n\nCurrently the following commands are understood by the kernel:\n\n- `@server=` sets the Prometheus server used for queries.\n- `@start=` sets the start time of the timerange used by range queries.\n- `@end=` sets the end time of the timerange used by range queries. This time is also used for instant queries.\n\nThe `@start=` and `@end=` commands accept either a RFC3339 formatted timestamp (for example `2018-08-08T12:00:00Z`) or a time relative to either `now`, `start` or `end`:\n\n|                                                          |                    |\n| -------------------------------------------------------: | ------------------ |\n|                                Set the end time to \"now\" | `@end=now`         |\n|              Set the start time to \"12 hours before end\" | `@start=end-12h`   |\n|                     Set the start time to \"24 hours ago\" | `@start=now-24h`   |\n| Set the end time to \"6 hours and 30 minutes after start\" | `@end=start+6h30m` |\n\nMore than one command can be provided in a single code cell (one per line).\n\n#### Plotting graphs\n\nIn addition to commands which are used for changing the kernel options there is another command which controls whether a query will be executed as an \"instant\" or \"range\" query yielding either a table of values at the `end` time or a plot of the values between the `start` and `end` time:\n\n```plain\ngraph(\u003cquery\u003e)\n```\n\nIt has a single optional parameter which can be used to set the minimum of the Y axis of the plot to zero:\n\n```plain\ngraph0(\u003cquery\u003e)\n```\n\n## Features (including planned)\n\nThis project is still in a very early stage of development which means that only a subset of the planned features are implemented already and also that some existing features might change in the future. Feedback and suggestions are appreciated.\n\n- [x] Send range and instant queries to Prometheus server\n- [x] Graph range queries\n- [x] Provide a way to set timerange to fixed and dynamic values\n- [x] Simple tab-completion of series names\n- [ ] Make graphs more interactive (currently pre-rendered images)\n- [ ] Code highlighting and more advanced tab-completion\n- [ ] Possibility to test recording rules which are not on the server yet\n- [ ] Make it possible to test alerting rules against past data\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxperimental%2Fipromnb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxperimental%2Fipromnb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxperimental%2Fipromnb/lists"}