From 7045e1116c95cc01195a6c8c232335f4a79f8c00 Mon Sep 17 00:00:00 2001 From: rajat404 <404rajat@gmail.com> Date: Wed, 15 Jan 2020 23:58:58 +0530 Subject: [PATCH 01/15] Inspect metrics and generate metric list in docs; Add monitoring section in Docs --- .gitignore | 1 + docs/Makefile | 4 ++++ docs/generator.py | 32 ++++++++++++++++++++++++++++++ docs/requirements.txt | 2 ++ docs/source/index.rst | 8 ++++++++ docs/source/monitoring/index.rst | 10 ++++++++++ docs/source/monitoring/overview.md | 3 +++ 7 files changed, 60 insertions(+) create mode 100644 docs/generator.py create mode 100644 docs/source/monitoring/index.rst create mode 100644 docs/source/monitoring/overview.md diff --git a/.gitignore b/.gitignore index 2eb6e784..0949331f 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,4 @@ htmlcov .vscode/ .pytest_cache pip-wheel-metadata +docs/source/monitoring/metrics.md diff --git a/docs/Makefile b/docs/Makefile index b20dc238..387343e2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -48,6 +48,7 @@ help: @echo " doctest to run all doctests embedded in the documentation (if enabled)" @echo " coverage to run coverage check of the documentation (if enabled)" @echo " spelling to run spell check on documentation" + @echo " generate to generate documentation by inspecting the source code" clean: rm -rf $(BUILDDIR)/* @@ -60,6 +61,9 @@ rest-api: source/_static/rest-api/index.html source/_static/rest-api/index.html: rest-api.yml node_modules npm run rest-api +auto-generate: + python3 generator.py + html: rest-api $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo diff --git a/docs/generator.py b/docs/generator.py new file mode 100644 index 00000000..3909153e --- /dev/null +++ b/docs/generator.py @@ -0,0 +1,32 @@ +from pytablewriter import MarkdownTableWriter +from pytablewriter.style import Style + +import jupyterhub.metrics + +class Generator: + + def prometheus_metrics(self): + filename = "./source/monitoring/metrics.md" + + writer = MarkdownTableWriter() + writer.table_name = "List of Prometheus Metrics\n" + writer.headers = ["Type", "Name", "Description"] + writer.value_matrix = [] + writer.margin = 1 + + for name in dir(jupyterhub.metrics): + obj = getattr(jupyterhub.metrics, name) + if obj.__class__.__module__.startswith('prometheus_client.'): + for metric in obj.describe(): + writer.value_matrix.append([metric.type, metric.name, metric.documentation]) + + with open(filename, 'w') as f: + f.write(writer.dumps()) + +def main(): + doc_generator = Generator() + doc_generator.prometheus_metrics() + + +if __name__ == "__main__": + main() diff --git a/docs/requirements.txt b/docs/requirements.txt index 472fcc28..9a067d9a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,3 +9,5 @@ recommonmark>=0.6 sphinx-copybutton sphinx-jsonschema sphinx>=1.7 +pytablewriter==0.46.3 +sphinx-markdown-tables==0.0.10 diff --git a/docs/source/index.rst b/docs/source/index.rst index 8d51a6bc..d7781191 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,6 +84,14 @@ Getting Started getting-started/index +Monitoring +------------------- + +.. toctree:: + :maxdepth: 2 + + monitoring/index + Technical Reference ------------------- diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst new file mode 100644 index 00000000..c76d5d79 --- /dev/null +++ b/docs/source/monitoring/index.rst @@ -0,0 +1,10 @@ +Monitoring +=================== + +This section covers details on monitoring the state of your Jupyterhub installation. + +.. toctree:: + :maxdepth: 2 + + overview + metrics diff --git a/docs/source/monitoring/overview.md b/docs/source/monitoring/overview.md new file mode 100644 index 00000000..d6692975 --- /dev/null +++ b/docs/source/monitoring/overview.md @@ -0,0 +1,3 @@ +# Monitoring Overview + +Jupyterhub operational metrics are collected using Prometheus. Please refer to [this doc](https://github.com/jupyterhub/mybinder.org-deploy/blob/master/docs/source/components/metrics.md) for a primer on Prometheus. From 7ed3e0506bfc5f762a74b5c1478506d854b8a86e Mon Sep 17 00:00:00 2001 From: rajat404 <404rajat@gmail.com> Date: Thu, 16 Jan 2020 00:15:59 +0530 Subject: [PATCH 02/15] Extract doc generation logic in separate method --- docs/generator.py | 27 +++++++++++++++++++-------- docs/requirements.txt | 3 +-- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/generator.py b/docs/generator.py index 3909153e..f8352a6c 100644 --- a/docs/generator.py +++ b/docs/generator.py @@ -3,26 +3,37 @@ from pytablewriter.style import Style import jupyterhub.metrics + class Generator: - - def prometheus_metrics(self): - filename = "./source/monitoring/metrics.md" - + @classmethod + def create_writer(cls, table_name, headers, values): writer = MarkdownTableWriter() - writer.table_name = "List of Prometheus Metrics\n" - writer.headers = ["Type", "Name", "Description"] - writer.value_matrix = [] + writer.table_name = table_name + writer.headers = headers + writer.value_matrix = values writer.margin = 1 + [writer.set_style(header, Style(align="center")) for header in headers] + return writer + def _parse_metrics(self): + table_rows = [] for name in dir(jupyterhub.metrics): obj = getattr(jupyterhub.metrics, name) if obj.__class__.__module__.startswith('prometheus_client.'): for metric in obj.describe(): - writer.value_matrix.append([metric.type, metric.name, metric.documentation]) + table_rows.append([metric.type, metric.name, metric.documentation]) + return table_rows + def prometheus_metrics(self): + filename = "./source/monitoring/metrics.md" + table_name = "List of Prometheus Metrics\n" + headers = ["Type", "Name", "Description"] + values = self._parse_metrics() + writer = Generator.create_writer(table_name, headers, values) with open(filename, 'w') as f: f.write(writer.dumps()) + def main(): doc_generator = Generator() doc_generator.prometheus_metrics() diff --git a/docs/requirements.txt b/docs/requirements.txt index 9a067d9a..3f45c36a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -8,6 +8,5 @@ pydata-sphinx-theme recommonmark>=0.6 sphinx-copybutton sphinx-jsonschema -sphinx>=1.7 -pytablewriter==0.46.3 sphinx-markdown-tables==0.0.10 +sphinx>=1.7 From 9e5993f1da9e41685739b6c389eb0144e44ae3f0 Mon Sep 17 00:00:00 2001 From: rajat404 <404rajat@gmail.com> Date: Thu, 16 Jan 2020 00:43:48 +0530 Subject: [PATCH 03/15] Docs: Fix typo; Add `generate` task as sub-task in `html` --- docs/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 387343e2..08454aa1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,10 +61,10 @@ rest-api: source/_static/rest-api/index.html source/_static/rest-api/index.html: rest-api.yml node_modules npm run rest-api -auto-generate: +generate: python3 generator.py -html: rest-api +html: rest-api generate $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." From c830d964d527fffff6a0779447d688702dfddf8d Mon Sep 17 00:00:00 2001 From: Rajat Goyal Date: Tue, 18 Aug 2020 22:32:39 +0530 Subject: [PATCH 04/15] Apply suggestions from code review Co-authored-by: Min RK --- docs/generator.py | 2 +- docs/source/monitoring/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/generator.py b/docs/generator.py index f8352a6c..a4d58a14 100644 --- a/docs/generator.py +++ b/docs/generator.py @@ -29,7 +29,7 @@ class Generator: table_name = "List of Prometheus Metrics\n" headers = ["Type", "Name", "Description"] values = self._parse_metrics() - writer = Generator.create_writer(table_name, headers, values) + writer = self.create_writer(table_name, headers, values) with open(filename, 'w') as f: f.write(writer.dumps()) diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index c76d5d79..8e24cc38 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -1,7 +1,7 @@ Monitoring =================== -This section covers details on monitoring the state of your Jupyterhub installation. +This section covers details on monitoring the state of your JupyterHub installation. .. toctree:: :maxdepth: 2 From dcd520179c0da754f39b20bab4c7223a19af693a Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 19 Aug 2020 00:04:01 +0530 Subject: [PATCH 05/15] Made changes in monitoring docs as per the feedback on PR review --- .gitignore | 2 +- docs/Makefile | 8 ++++---- docs/{generator.py => generate-metrics.py} | 13 +++++++++++-- docs/requirements.txt | 1 + docs/source/monitoring/index.rst | 5 +++-- docs/source/monitoring/overview.md | 3 --- 6 files changed, 20 insertions(+), 12 deletions(-) rename docs/{generator.py => generate-metrics.py} (78%) delete mode 100644 docs/source/monitoring/overview.md diff --git a/.gitignore b/.gitignore index 0949331f..e1545c33 100644 --- a/.gitignore +++ b/.gitignore @@ -27,4 +27,4 @@ htmlcov .vscode/ .pytest_cache pip-wheel-metadata -docs/source/monitoring/metrics.md +docs/source/monitoring/gen/ diff --git a/docs/Makefile b/docs/Makefile index 08454aa1..f444e2a7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -48,7 +48,7 @@ help: @echo " doctest to run all doctests embedded in the documentation (if enabled)" @echo " coverage to run coverage check of the documentation (if enabled)" @echo " spelling to run spell check on documentation" - @echo " generate to generate documentation by inspecting the source code" + @echo " metrics to generate documentation for metrics by inspecting the source code" clean: rm -rf $(BUILDDIR)/* @@ -61,10 +61,10 @@ rest-api: source/_static/rest-api/index.html source/_static/rest-api/index.html: rest-api.yml node_modules npm run rest-api -generate: - python3 generator.py +metrics: + python3 generate-metrics.py -html: rest-api generate +html: rest-api $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/generator.py b/docs/generate-metrics.py similarity index 78% rename from docs/generator.py rename to docs/generate-metrics.py index a4d58a14..f9600d5b 100644 --- a/docs/generator.py +++ b/docs/generate-metrics.py @@ -1,8 +1,13 @@ +import os +from os.path import join + from pytablewriter import MarkdownTableWriter from pytablewriter.style import Style import jupyterhub.metrics +HERE = os.path.abspath(os.path.dirname(__file__)) + class Generator: @classmethod @@ -25,8 +30,12 @@ class Generator: return table_rows def prometheus_metrics(self): - filename = "./source/monitoring/metrics.md" - table_name = "List of Prometheus Metrics\n" + generated_directory = f"{HERE}/source/monitoring" + if not os.path.exists(generated_directory): + os.makedirs(generated_directory) + + filename = f"{generated_directory}/metrics.md" + table_name = "List of Prometheus Metrics" headers = ["Type", "Name", "Description"] values = self._parse_metrics() writer = self.create_writer(table_name, headers, values) diff --git a/docs/requirements.txt b/docs/requirements.txt index 3f45c36a..d473e423 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,6 +5,7 @@ alabaster_jupyterhub # 0.1.0 released. https://github.com/jupyterhub/autodoc-traits/archive/75885ee24636efbfebfceed1043459715049cd84.zip pydata-sphinx-theme +pytablewriter==0.56.1 recommonmark>=0.6 sphinx-copybutton sphinx-jsonschema diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index 8e24cc38..8d99e4f8 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -3,8 +3,9 @@ Monitoring This section covers details on monitoring the state of your JupyterHub installation. +Jupyterhub operational metrics are collected using Prometheus. For more details about Prometheus please refer to the [official documentation](https://prometheus.io/docs/introduction/overview). + .. toctree:: :maxdepth: 2 - overview - metrics + gen/metrics diff --git a/docs/source/monitoring/overview.md b/docs/source/monitoring/overview.md deleted file mode 100644 index d6692975..00000000 --- a/docs/source/monitoring/overview.md +++ /dev/null @@ -1,3 +0,0 @@ -# Monitoring Overview - -Jupyterhub operational metrics are collected using Prometheus. Please refer to [this doc](https://github.com/jupyterhub/mybinder.org-deploy/blob/master/docs/source/components/metrics.md) for a primer on Prometheus. From 65b83f5f009b840a2ab810430a5631b5cff29bcd Mon Sep 17 00:00:00 2001 From: Rajat Goyal Date: Wed, 19 Aug 2020 09:59:28 +0530 Subject: [PATCH 06/15] Update docs/source/monitoring/index.rst Co-authored-by: Erik Sundell --- docs/source/monitoring/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index 8d99e4f8..7e85cff0 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -3,7 +3,7 @@ Monitoring This section covers details on monitoring the state of your JupyterHub installation. -Jupyterhub operational metrics are collected using Prometheus. For more details about Prometheus please refer to the [official documentation](https://prometheus.io/docs/introduction/overview). +JupyterHub expose the ``/metrics`` endpoint that returns text describing its current operational state formatted in a way `Prometheus _` understands. Prometheus is a separate open source tool that can be configured to repeatedly poll JupyterHub's ``/metrics`` endpoint to parse and save the momentary state. By doing so, Prometheus can describe JupyterHub's eolving state over time. This evolving state can then be accessed through Prometheus that expose its underlying storage to those allowed to access it, and be presented with dashboards by a tool like `Grafana _`. .. toctree:: :maxdepth: 2 From c0288ec6f6c9ac5b9e2a78180edf64535d5de389 Mon Sep 17 00:00:00 2001 From: Rajat Goyal Date: Wed, 19 Aug 2020 21:40:00 +0530 Subject: [PATCH 07/15] Update docs/source/monitoring/index.rst - Fixes typo (eolving -> evolving) - re-use the word current instead of momentary for comprehensibility - references JupyterHubs current state with its instead of the for comprehensibility Co-authored-by: Erik Sundell --- docs/source/monitoring/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index 7e85cff0..781ff09f 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -3,7 +3,7 @@ Monitoring This section covers details on monitoring the state of your JupyterHub installation. -JupyterHub expose the ``/metrics`` endpoint that returns text describing its current operational state formatted in a way `Prometheus _` understands. Prometheus is a separate open source tool that can be configured to repeatedly poll JupyterHub's ``/metrics`` endpoint to parse and save the momentary state. By doing so, Prometheus can describe JupyterHub's eolving state over time. This evolving state can then be accessed through Prometheus that expose its underlying storage to those allowed to access it, and be presented with dashboards by a tool like `Grafana _`. +JupyterHub expose the ``/metrics`` endpoint that returns text describing its current operational state formatted in a way `Prometheus _` understands. Prometheus is a separate open source tool that can be configured to repeatedly poll JupyterHub's ``/metrics`` endpoint to parse and save its current state. By doing so, Prometheus can describe JupyterHub's evolving state over time. This evolving state can then be accessed through Prometheus that expose its underlying storage to those allowed to access it, and be presented with dashboards by a tool like `Grafana _`. .. toctree:: :maxdepth: 2 From e553bcb7e2f25123150e0303ab99cbd7c14f1d28 Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 19 Aug 2020 21:43:28 +0530 Subject: [PATCH 08/15] Unpin dependencies from their patch versions --- docs/requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index d473e423..1a6636a4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,9 +5,9 @@ alabaster_jupyterhub # 0.1.0 released. https://github.com/jupyterhub/autodoc-traits/archive/75885ee24636efbfebfceed1043459715049cd84.zip pydata-sphinx-theme -pytablewriter==0.56.1 +pytablewriter>=0.56 recommonmark>=0.6 sphinx-copybutton sphinx-jsonschema -sphinx-markdown-tables==0.0.10 +sphinx-markdown-tables sphinx>=1.7 From 8ee60ce0c79d1cc1edd5b78cbfc5b285006cbee6 Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 30 Sep 2020 22:57:33 +0530 Subject: [PATCH 09/15] Add metrics documentation generation step in CircleCI & RTD configs Also rename generated metrics documentation directory `_gen` from `gen` --- .circleci/config.yml | 2 +- .gitignore | 2 +- docs/generate-metrics.py | 2 +- docs/source/conf.py | 2 +- docs/source/monitoring/index.rst | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index fb744df7..19c969f4 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -64,7 +64,7 @@ jobs: name: Build docs to store command: | cd docs - make html + make metrics html # Tell Circle to store the documentation output in a folder that we can access later - store_artifacts: path: docs/build/html/ diff --git a/.gitignore b/.gitignore index e1545c33..e1fd82a6 100644 --- a/.gitignore +++ b/.gitignore @@ -27,4 +27,4 @@ htmlcov .vscode/ .pytest_cache pip-wheel-metadata -docs/source/monitoring/gen/ +docs/source/monitoring/_gen/ diff --git a/docs/generate-metrics.py b/docs/generate-metrics.py index f9600d5b..4a89db2d 100644 --- a/docs/generate-metrics.py +++ b/docs/generate-metrics.py @@ -30,7 +30,7 @@ class Generator: return table_rows def prometheus_metrics(self): - generated_directory = f"{HERE}/source/monitoring" + generated_directory = f"{HERE}/source/monitoring/_gen" if not os.path.exists(generated_directory): os.makedirs(generated_directory) diff --git a/docs/source/conf.py b/docs/source/conf.py index 63f758c9..a97da124 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -220,7 +220,7 @@ if on_rtd: # build rest-api, since RTD doesn't run make from subprocess import check_call as sh - sh(['make', 'rest-api'], cwd=docs) + sh(['make', 'metrics', 'rest-api'], cwd=docs) # -- Spell checking ------------------------------------------------------- diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index 781ff09f..5741b336 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -8,4 +8,4 @@ JupyterHub expose the ``/metrics`` endpoint that returns text describing its cur .. toctree:: :maxdepth: 2 - gen/metrics + _gen/metrics From be272ffb2a4f5ad9dd709dc276d9897a9eaa96be Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 30 Sep 2020 23:14:06 +0530 Subject: [PATCH 10/15] Formatted text for better readability --- docs/source/monitoring/index.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/source/monitoring/index.rst b/docs/source/monitoring/index.rst index 5741b336..1299fbcc 100644 --- a/docs/source/monitoring/index.rst +++ b/docs/source/monitoring/index.rst @@ -3,7 +3,16 @@ Monitoring This section covers details on monitoring the state of your JupyterHub installation. -JupyterHub expose the ``/metrics`` endpoint that returns text describing its current operational state formatted in a way `Prometheus _` understands. Prometheus is a separate open source tool that can be configured to repeatedly poll JupyterHub's ``/metrics`` endpoint to parse and save its current state. By doing so, Prometheus can describe JupyterHub's evolving state over time. This evolving state can then be accessed through Prometheus that expose its underlying storage to those allowed to access it, and be presented with dashboards by a tool like `Grafana _`. +JupyterHub expose the ``/metrics`` endpoint that returns text describing its current +operational state formatted in a way `Prometheus `_ understands. + +Prometheus is a separate open source tool that can be configured to repeatedly poll +JupyterHub's ``/metrics`` endpoint to parse and save its current state. + +By doing so, Prometheus can describe JupyterHub's evolving state over time. +This evolving state can then be accessed through Prometheus that expose its underlying +storage to those allowed to access it, and be presented with dashboards by a +tool like `Grafana `_. .. toctree:: :maxdepth: 2 From 5b8a7fd191fa3351506cd3e4e3c3cd89a3d67ebb Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 30 Sep 2020 23:25:22 +0530 Subject: [PATCH 11/15] Remove unused dependency --- docs/requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 1a6636a4..2d9da795 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,5 +9,4 @@ pytablewriter>=0.56 recommonmark>=0.6 sphinx-copybutton sphinx-jsonschema -sphinx-markdown-tables sphinx>=1.7 From b194135a0f505f319ea50ecf4e6676893fcba4c3 Mon Sep 17 00:00:00 2001 From: Rajat Goyal <404rajat@gmail.com> Date: Wed, 30 Sep 2020 23:46:41 +0530 Subject: [PATCH 12/15] Generate list of prometheus metrics in reStructuredText rather than markdown --- docs/generate-metrics.py | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/generate-metrics.py b/docs/generate-metrics.py index 4a89db2d..372764fc 100644 --- a/docs/generate-metrics.py +++ b/docs/generate-metrics.py @@ -1,7 +1,7 @@ import os from os.path import join -from pytablewriter import MarkdownTableWriter +from pytablewriter import RstSimpleTableWriter from pytablewriter.style import Style import jupyterhub.metrics @@ -12,7 +12,7 @@ HERE = os.path.abspath(os.path.dirname(__file__)) class Generator: @classmethod def create_writer(cls, table_name, headers, values): - writer = MarkdownTableWriter() + writer = RstSimpleTableWriter() writer.table_name = table_name writer.headers = headers writer.value_matrix = values @@ -34,13 +34,17 @@ class Generator: if not os.path.exists(generated_directory): os.makedirs(generated_directory) - filename = f"{generated_directory}/metrics.md" - table_name = "List of Prometheus Metrics" + filename = f"{generated_directory}/metrics.rst" + table_name = "" headers = ["Type", "Name", "Description"] values = self._parse_metrics() writer = self.create_writer(table_name, headers, values) + + title = "List of Prometheus Metrics" + underline = "============================" + content = f"{title}\n{underline}\n{writer.dumps()}" with open(filename, 'w') as f: - f.write(writer.dumps()) + f.write(content) def main(): From e15b6ad52e046017f8560053717490c27619544f Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 1 Oct 2020 10:07:14 +0200 Subject: [PATCH 13/15] Makefile: let make html depend on generated metrics.rst --- .circleci/config.yml | 2 +- docs/Makefile | 6 ++++-- docs/generate-metrics.py | 1 + docs/source/conf.py | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 19c969f4..fb744df7 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -64,7 +64,7 @@ jobs: name: Build docs to store command: | cd docs - make metrics html + make html # Tell Circle to store the documentation output in a folder that we can access later - store_artifacts: path: docs/build/html/ diff --git a/docs/Makefile b/docs/Makefile index f444e2a7..280bce9a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,10 +61,12 @@ rest-api: source/_static/rest-api/index.html source/_static/rest-api/index.html: rest-api.yml node_modules npm run rest-api -metrics: +metrics: source/monitoring/_gen/metrics.rst + +source/monitoring/_gen/metrics.rst: generate-metrics.py python3 generate-metrics.py -html: rest-api +html: rest-api metrics $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/generate-metrics.py b/docs/generate-metrics.py index 372764fc..5435da20 100644 --- a/docs/generate-metrics.py +++ b/docs/generate-metrics.py @@ -45,6 +45,7 @@ class Generator: content = f"{title}\n{underline}\n{writer.dumps()}" with open(filename, 'w') as f: f.write(content) + print(f"Generated {filename}.") def main(): diff --git a/docs/source/conf.py b/docs/source/conf.py index a97da124..e1e09b3e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -217,7 +217,7 @@ intersphinx_mapping = {'https://docs.python.org/3/': None} on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if on_rtd: # readthedocs.org uses their theme by default, so no need to specify it - # build rest-api, since RTD doesn't run make + # build both metrics and rest-api, since RTD doesn't run make from subprocess import check_call as sh sh(['make', 'metrics', 'rest-api'], cwd=docs) From 50868f5bb5ba11ba47d7b7add07c57f7dcc40860 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 1 Oct 2020 10:36:19 +0200 Subject: [PATCH 14/15] monitoring docs: relocate monitoring section under technical reference --- docs/source/{monitoring/index.rst => reference/monitoring.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/{monitoring/index.rst => reference/monitoring.rst} (100%) diff --git a/docs/source/monitoring/index.rst b/docs/source/reference/monitoring.rst similarity index 100% rename from docs/source/monitoring/index.rst rename to docs/source/reference/monitoring.rst From 8c30724f174bc96faad203f063b7446308c85ba7 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Thu, 1 Oct 2020 10:40:13 +0200 Subject: [PATCH 15/15] monitoring docs: fixes following monitoring section relocation --- .gitignore | 2 +- docs/Makefile | 4 ++-- docs/generate-metrics.py | 2 +- docs/source/index.rst | 8 -------- docs/source/reference/index.rst | 1 + docs/source/reference/monitoring.rst | 4 ++-- 6 files changed, 7 insertions(+), 14 deletions(-) diff --git a/.gitignore b/.gitignore index e1fd82a6..44a7b3d4 100644 --- a/.gitignore +++ b/.gitignore @@ -27,4 +27,4 @@ htmlcov .vscode/ .pytest_cache pip-wheel-metadata -docs/source/monitoring/_gen/ +docs/source/reference/metrics.rst diff --git a/docs/Makefile b/docs/Makefile index 280bce9a..5e61789e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,9 +61,9 @@ rest-api: source/_static/rest-api/index.html source/_static/rest-api/index.html: rest-api.yml node_modules npm run rest-api -metrics: source/monitoring/_gen/metrics.rst +metrics: source/reference/metrics.rst -source/monitoring/_gen/metrics.rst: generate-metrics.py +source/reference/metrics.rst: generate-metrics.py python3 generate-metrics.py html: rest-api metrics diff --git a/docs/generate-metrics.py b/docs/generate-metrics.py index 5435da20..81304bef 100644 --- a/docs/generate-metrics.py +++ b/docs/generate-metrics.py @@ -30,7 +30,7 @@ class Generator: return table_rows def prometheus_metrics(self): - generated_directory = f"{HERE}/source/monitoring/_gen" + generated_directory = f"{HERE}/source/reference" if not os.path.exists(generated_directory): os.makedirs(generated_directory) diff --git a/docs/source/index.rst b/docs/source/index.rst index d7781191..8d51a6bc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,14 +84,6 @@ Getting Started getting-started/index -Monitoring -------------------- - -.. toctree:: - :maxdepth: 2 - - monitoring/index - Technical Reference ------------------- diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 4008a723..ed478fa1 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -16,6 +16,7 @@ what happens under-the-hood when you deploy and configure your JupyterHub. proxy separate-proxy rest + monitoring database templates ../events/index diff --git a/docs/source/reference/monitoring.rst b/docs/source/reference/monitoring.rst index 1299fbcc..774656ec 100644 --- a/docs/source/reference/monitoring.rst +++ b/docs/source/reference/monitoring.rst @@ -1,5 +1,5 @@ Monitoring -=================== +========== This section covers details on monitoring the state of your JupyterHub installation. @@ -17,4 +17,4 @@ tool like `Grafana