Reorganize examples and improve ext packages documentation #483

mauriciovasquezbernal · 2020-03-13T16:02:21Z

Update examples according to #482.

A preview of the resulting documentation is available at https://opentelemetry-python-kinvolk.readthedocs.io/en/reorganize-examples/.

This PR also moves the text on the readmes of the external packages to their
source code as a docstring. This improves the generated documentation and helps
to consolidate the documentation in a single place.

This commit uniforms all the readmes present on each packager, they only contain
a 1 line description, installation instructions and a link to the online
documentation of such package. This small readme will be the one shown on Github
and on PyPI.

The full documentation will be generated by autodoc and stored in readthedocs
or whatever site we choose.

This commit moves the text on the readmes of the external packages to their source code as a docstring. This improves the generated documentation and helps to consolidate the documentation in a single place. This commit uniforms all the readmes present on each packager, they only contain a 1 line description, installation instructions and a link to the online documentation of such package. This small readme will be the one shown on Github and on PyPI. The full documentation will be generated by autodoc and stored in readthedocs or whatever site we choose.

This commit changes the examples structure to have the following examples: - basic meter & tracer - http integration - jaeger, prometheus, otcollector{tracer, metrics} - opentracing shim

codecov-io · 2020-03-13T16:24:05Z

Codecov Report

Merging #483 into master will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master     #483   +/-   ##
=======================================
  Coverage   89.47%   89.47%           
=======================================
  Files          43       43           
  Lines        2213     2214    +1     
  Branches      250      250           
=======================================
+ Hits         1980     1981    +1     
  Misses        161      161           
  Partials       72       72

Impacted Files	Coverage Δ
...ts/src/opentelemetry/ext/http_requests/__init__.py	`89.47% <ø> (ø)`
...ry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py	`68.14% <ø> (ø)`
...-ext-flask/src/opentelemetry/ext/flask/__init__.py	`90.00% <100.00%> (+0.20%)`	⬆️
...xt-jaeger/src/opentelemetry/ext/jaeger/__init__.py	`86.54% <100.00%> (ø)`
...xt-zipkin/src/opentelemetry/ext/zipkin/__init__.py	`84.41% <100.00%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fbfafa4...b1cd37a. Read the comment docs.

codeboten

This is looking great. Just some suggestions and a few nits. At some point we'll need to review the content in all these docs but I suggest we don't do it with this PR. I've tested each example.

Couple of questions:
Reviewing the docs here, it looks like the prometheus doc is empty: https://opentelemetry-python-kinvolk.readthedocs.io/en/reorganize-examples/ext/prometheus/prometheus.html.
It also looks like the example app doesn't have much content https://opentelemetry-python-kinvolk.readthedocs.io/en/reorganize-examples/examples/opentelemetry-example-app/README.html, is that expected?

codeboten · 2020-03-13T21:35:07Z

ext/opentelemetry-ext-psycopg2/src/opentelemetry/ext/psycopg2/__init__.py

-The opentelemetry-ext-psycopg2 package allows tracing PostgreSQL queries made by the
-Psycopg2 library.
+The integration with PostgreSQL supports the `Psycopg`_ library and is specified
+to ``trace_integration`` using ``'PostgreSQL'``.


Not sure what this means.

ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py

ext/opentelemetry-ext-otcollector/src/opentelemetry/ext/otcollector/__init__.py

docs/examples/prometheus/README.rst

docs/examples/prometheus/prometheus.py

docs/examples/basic_meter/observer.py

docs/examples/basic_meter/README.rst

codeboten · 2020-03-13T22:28:23Z

docs/examples/otcollector-metrics/README.rst

+    python collector.py
+
+
+The metrics are available in the Prometheus dashboard at http://localhost:9090/graph.


Might be helpful here to give an example of a metric to look for ie. requests

Co-Authored-By: alrex <alrex.boten@gmail.com>

mauriciovasquezbernal · 2020-03-16T14:03:39Z

This PR includes also the changes in #475, given that I received feedback related to those changes here, I'm going to close that one and keep everything in this single PR.

mauriciovasquezbernal · 2020-03-16T14:24:48Z

Reviewing the docs here, it looks like the prometheus doc is empty: https://opentelemetry-python-kinvolk.readthedocs.io/en/reorganize-examples/ext/prometheus/prometheus.html.

prometheus-client dependency was missing from docs requirements. Fixed!

It also looks like the example app doesn't have much content https://opentelemetry-python-kinvolk.readthedocs.io/en/reorganize-examples/examples/opentelemetry-example-app/README.html, is that expected?

I have no idea what to do with that example. I don't know what is the added value of that. I'd like to hear others' opinions on this.

andrewhsu · 2020-03-16T16:29:11Z

Looks like PR #494 does a more up-to-date Getting Started guide.

ocelotl

Great! Just a few minor comments

docs/examples/basic_meter/basic_metrics.py

docs/examples/jaeger_exporter/jaeger_exporter.py

docs/examples/otcollector-tracer/collector.py

ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py

ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/__init__.py

Co-Authored-By: Diego Hurtado <ocelotl@users.noreply.github.com>

ocelotl

LGTM 👍

toumorokoshi · 2020-03-23T17:45:51Z

@mauriciovasquezbernal thanks for the work! I have a few thoughts on the docs themselves but we (I) can pick those up in future PRs.

The only real thought I have is putting the examples above the integrations. Examples are probably more pertinent to most people as they're learning the codebase.

toumorokoshi · 2020-03-23T19:49:58Z

@mauriciovasquezbernal can you merge in changes one last time? then I can merge in.

toumorokoshi · 2020-03-24T21:46:04Z

@mauriciovasquezbernal merged! thanks.

* fix(http-plugin): move node-sdk to dev deps * feat: update dependencies * feat: server implementation and tests * fix: remove console logger * fix: add types * feat(prometheus-exporter): counter and gauge * feat(prometheus-exporter): implement counter and gauge * feat(prometheus-exporter): export configuration interface * fix: linting * fix: typo Co-Authored-By: Mayur Kale <mayurkale@google.com> * chore: document ExporterConfig * fix: dependencies * fix: typo Co-Authored-By: Mayur Kale <mayurkale@google.com> * chore: document sanitize method and make behavior more strict * chore: do not use global prom-client registry * chore: add defaults to description and metric endpoint * test: export couter, gauge, multiple, and none * test: sanitize prom metric names * fix: typo Co-Authored-By: Mayur Kale <mayurkale@google.com> * chore: make _server read only * test: add tests for prom export configuration * style: make comments descriptive * test: update tests for label sets * fix: lint

mauriciovasquezbernal added 2 commits March 13, 2020 10:59

docs: Reorganize examples

f639c26

This commit changes the examples structure to have the following examples: - basic meter & tracer - http integration - jaeger, prometheus, otcollector{tracer, metrics} - opentracing shim

mauriciovasquezbernal added the doc Documentation-related label Mar 13, 2020

mauriciovasquezbernal requested a review from a team March 13, 2020 16:02

remove example from jaeger source code

ddbec13

codeboten approved these changes Mar 13, 2020

View reviewed changes

mauriciovasquezbernal and others added 3 commits March 16, 2020 08:15

Apply suggestions from code review

50f2970

Co-Authored-By: alrex <alrex.boten@gmail.com>

few more fixes

dfc8228

Merge branch 'master' into reorganize-examples

a747b61

mauriciovasquezbernal mentioned this pull request Mar 16, 2020

docs: move ext readmes to docstring #475

Closed

mauriciovasquezbernal changed the title ~~Reorganize examples~~ Reorganize examples and improve ext packages documentation Mar 16, 2020

add prometheus_client to docs_requirements

56df592

c24t mentioned this pull request Mar 16, 2020

Author a full getting started guide #491

Closed

Merge branch 'master' into reorganize-examples

23ec706

ocelotl suggested changes Mar 20, 2020

View reviewed changes

mauriciovasquezbernal and others added 3 commits March 20, 2020 07:35

Update docs/examples/basic_meter/basic_metrics.py

a5eb962

Co-Authored-By: Diego Hurtado <ocelotl@users.noreply.github.com>

Update docs/examples/jaeger_exporter/jaeger_exporter.py

c67c245

Co-Authored-By: Diego Hurtado <ocelotl@users.noreply.github.com>

further updates

6659ff7

ocelotl approved these changes Mar 20, 2020

View reviewed changes

mauriciovasquezbernal added 2 commits March 23, 2020 16:42

Merge branch 'master' into reorganize-examples

f258d9d

Merge branch 'master' into reorganize-examples

b1cd37a

codeboten added the PR:please merge This PR is ready to be merged by a Maintainer (has enough valid approvals, successful build, etc.) label Mar 24, 2020

c24t approved these changes Mar 24, 2020

View reviewed changes

toumorokoshi merged commit 04a9533 into open-telemetry:master Mar 24, 2020

This was referenced Mar 25, 2020

Reorganize examples #482

Closed

Create basic_metric example #423

Closed

Add an autoinstrumentation mechanism and an instrumentor for Flask #327

Merged

mauriciovasquezbernal deleted the reorganize-examples branch April 14, 2020 21:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize examples and improve ext packages documentation #483

Reorganize examples and improve ext packages documentation #483

mauriciovasquezbernal commented Mar 13, 2020 •

edited

Loading

codecov-io commented Mar 13, 2020 •

edited

Loading

codeboten left a comment

codeboten Mar 13, 2020

codeboten Mar 13, 2020

mauriciovasquezbernal Mar 16, 2020

mauriciovasquezbernal commented Mar 16, 2020

mauriciovasquezbernal commented Mar 16, 2020

andrewhsu commented Mar 16, 2020

ocelotl left a comment

ocelotl left a comment

toumorokoshi commented Mar 23, 2020

toumorokoshi commented Mar 23, 2020

toumorokoshi commented Mar 24, 2020

		python collector.py


		The metrics are available in the Prometheus dashboard at http://localhost:9090/graph.

Reorganize examples and improve ext packages documentation #483

Reorganize examples and improve ext packages documentation #483

Conversation

mauriciovasquezbernal commented Mar 13, 2020 • edited Loading

codecov-io commented Mar 13, 2020 • edited Loading

Codecov Report

codeboten left a comment

Choose a reason for hiding this comment

codeboten Mar 13, 2020

Choose a reason for hiding this comment

codeboten Mar 13, 2020

Choose a reason for hiding this comment

mauriciovasquezbernal Mar 16, 2020

Choose a reason for hiding this comment

mauriciovasquezbernal commented Mar 16, 2020

mauriciovasquezbernal commented Mar 16, 2020

andrewhsu commented Mar 16, 2020

ocelotl left a comment

Choose a reason for hiding this comment

ocelotl left a comment

Choose a reason for hiding this comment

toumorokoshi commented Mar 23, 2020

toumorokoshi commented Mar 23, 2020

toumorokoshi commented Mar 24, 2020

mauriciovasquezbernal commented Mar 13, 2020 •

edited

Loading

codecov-io commented Mar 13, 2020 •

edited

Loading