diff --git a/docs-requirements.txt b/docs-requirements.txt index ab952473a9b..41600cfe8c9 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -8,3 +8,6 @@ Deprecated>=1.2.6 thrift>=0.10.0 pymongo~=3.1 flask~=1.0 +mysql-connector-python ~= 8.0 +wrapt >= 1.0.0, < 2.0.0 +psycopg2-binary >= 2.7.3.1 diff --git a/docs/api/api.rst b/docs/api/api.rst new file mode 100644 index 00000000000..3b15cd0d36b --- /dev/null +++ b/docs/api/api.rst @@ -0,0 +1,12 @@ +OpenTelemetry Python API +======================== + +.. TODO: what is the API + +.. toctree:: + :maxdepth: 1 + + context + metrics + trace + util.loader \ No newline at end of file diff --git a/docs/opentelemetry.context.context.rst b/docs/api/context.context.rst similarity index 100% rename from docs/opentelemetry.context.context.rst rename to docs/api/context.context.rst diff --git a/docs/opentelemetry.context.rst b/docs/api/context.rst similarity index 83% rename from docs/opentelemetry.context.rst rename to docs/api/context.rst index 2b25793458c..7aef5ffe7d7 100644 --- a/docs/opentelemetry.context.rst +++ b/docs/api/context.rst @@ -6,7 +6,7 @@ Submodules .. toctree:: - opentelemetry.context.context + context.context Module contents --------------- diff --git a/docs/opentelemetry.metrics.rst b/docs/api/metrics.rst similarity index 100% rename from docs/opentelemetry.metrics.rst rename to docs/api/metrics.rst diff --git a/docs/opentelemetry.trace.rst b/docs/api/trace.rst similarity index 72% rename from docs/opentelemetry.trace.rst rename to docs/api/trace.rst index bfef5839bf0..00823aa0362 100644 --- a/docs/opentelemetry.trace.rst +++ b/docs/api/trace.rst @@ -6,8 +6,8 @@ Submodules .. toctree:: - opentelemetry.trace.sampling - opentelemetry.trace.status + trace.sampling + trace.status Module contents --------------- diff --git a/docs/opentelemetry.trace.sampling.rst b/docs/api/trace.sampling.rst similarity index 100% rename from docs/opentelemetry.trace.sampling.rst rename to docs/api/trace.sampling.rst diff --git a/docs/opentelemetry.trace.status.rst b/docs/api/trace.status.rst similarity index 100% rename from docs/opentelemetry.trace.status.rst rename to docs/api/trace.status.rst diff --git a/docs/opentelemetry.util.loader.rst b/docs/api/util.loader.rst similarity index 100% rename from docs/opentelemetry.util.loader.rst rename to docs/api/util.loader.rst diff --git a/docs/conf.py b/docs/conf.py index aa0b4096bc2..a509f14f5d6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,8 +30,8 @@ # -- Project information ----------------------------------------------------- -project = "OpenTelemetry" -copyright = "2019, OpenTelemetry Authors" # pylint: disable=redefined-builtin +project = "OpenTelemetry Python" +copyright = "OpenTelemetry Authors" # pylint: disable=redefined-builtin author = "OpenTelemetry Authors" @@ -57,6 +57,8 @@ # Add a .nojekyll file to the generated HTML docs # https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing "sphinx.ext.githubpages", + # Support external links to different versions in the Github repo + "sphinx.ext.extlinks", ] intersphinx_mapping = { @@ -106,3 +108,27 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = [] + +# Support external links to specific versions of the files in the Github repo +branch = os.environ.get("READTHEDOCS_VERSION") +if branch is None or branch == "latest": + branch = "master" + +REPO = "open-telemetry/opentelemetry-python/" +scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch +scm_web = "https://github.com/" + REPO + "blob/" + branch + +# Store variables in the epilogue so they are globally available. +rst_epilog = """ +.. |SCM_WEB| replace:: {s} +.. |SCM_RAW_WEB| replace:: {sr} +.. |SCM_BRANCH| replace:: {b} +""".format( + s=scm_web, sr=scm_raw_web, b=branch +) + +# used to have links to repo files +extlinks = { + "scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"), + "scm_web": (scm_web + "/%s", "scm_web"), +} diff --git a/docs/examples/basic_tracer/README.rst b/docs/examples/basic_tracer/README.rst new file mode 100644 index 00000000000..2cc2d0c6a6b --- /dev/null +++ b/docs/examples/basic_tracer/README.rst @@ -0,0 +1,76 @@ +Basic Tracer +============ + +This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job. +It supports exporting spans either to the console or to Jaeger_. + +The source files required to run this example are available :scm_web:`here `. + + +Run the application +------------------- + +Console +******* + +* Run the sample + +.. code-block:: sh + + $ python tracer.py + +The output will be displayed at the console + +:: + + Hello world from OpenTelemetry Python! + Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={})), start_time=2019-11-07T21:26:45.934412Z, end_time=2019-11-07T21:26:45.934567Z) + Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={})), start_time=2019-11-07T21:26:45.934396Z, end_time=2019-11-07T21:26:45.934576Z) + Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z) + + +Jaeger +****** + +Setup `Jaeger Tracing `_. + +* Run the sample + +.. code-block:: sh + + $ pip install opentelemetry-ext-jaeger + $ EXPORTER=jaeger python tracer.py + + +The traces should be available in the Jaeger UI at ``_ + + +Collector +********* + +* Start Collector + +.. code-block:: sh + + $ pip install docker-compose + $ cd docker + $ docker-compose up + +* Run the sample + +.. code-block:: sh + + $ pip install opentelemetry-ext-otcollector + $ EXPORTER=collector python tracer.py + + +Collector is configured to export to Jaeger, follow Jaeger UI instructions to find the traces. + +Useful links +------------ + +- For more information on OpenTelemetry, visit OpenTelemetry_. +- For more information on tracing in Python, visit Jaeger_. + +.. _Jaeger: https://www.jaegertracing.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ \ No newline at end of file diff --git a/examples/basic_tracer/__init__.py b/docs/examples/basic_tracer/__init__.py similarity index 100% rename from examples/basic_tracer/__init__.py rename to docs/examples/basic_tracer/__init__.py diff --git a/examples/basic_tracer/docker/collector-config.yaml b/docs/examples/basic_tracer/docker/collector-config.yaml similarity index 100% rename from examples/basic_tracer/docker/collector-config.yaml rename to docs/examples/basic_tracer/docker/collector-config.yaml diff --git a/examples/basic_tracer/docker/docker-compose.yaml b/docs/examples/basic_tracer/docker/docker-compose.yaml similarity index 100% rename from examples/basic_tracer/docker/docker-compose.yaml rename to docs/examples/basic_tracer/docker/docker-compose.yaml diff --git a/examples/basic_tracer/tests/__init__.py b/docs/examples/basic_tracer/tests/__init__.py similarity index 100% rename from examples/basic_tracer/tests/__init__.py rename to docs/examples/basic_tracer/tests/__init__.py diff --git a/examples/basic_tracer/tests/test_tracer.py b/docs/examples/basic_tracer/tests/test_tracer.py similarity index 100% rename from examples/basic_tracer/tests/test_tracer.py rename to docs/examples/basic_tracer/tests/test_tracer.py diff --git a/examples/basic_tracer/tracer.py b/docs/examples/basic_tracer/tracer.py similarity index 100% rename from examples/basic_tracer/tracer.py rename to docs/examples/basic_tracer/tracer.py diff --git a/docs/examples/http/README.rst b/docs/examples/http/README.rst new file mode 100644 index 00000000000..2d7ef887d7a --- /dev/null +++ b/docs/examples/http/README.rst @@ -0,0 +1,87 @@ +HTTP Example +============ + +This example shows how to use +`OpenTelemetryMiddleware `_ +and `requests `_ integrations to instrument a client and a server in Python. +It supports exporting spans either to the console or to Jaeger_. + +The source files required to run this example are available :scm_web:`here `. + + +Installation +------------ + +.. code-block:: sh + + $ pip install opentelemetry-api + $ pip install opentelemetry-sdk + $ pip install opentelemetry-ext-wsgi + $ pip install opentelemetry-ext-http-requests + + +Run the application +------------------- + +Console +******* + +* Run the server + +.. code-block:: sh + + $ python server.py + + +* Run the client from a different terminal + +.. code-block:: sh + + $ python tracer_client.py + + +The output will be displayed at the console on the client side + +:: + + Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), kind=SpanKind.CLIENT, parent=None, start_time=2019-11-07T21:52:59.591634Z, end_time=2019-11-07T21:53:00.386014Z) + + +And on the server + +:: + + 127.0.0.1 - - [07/Nov/2019 13:53:00] "GET / HTTP/1.1" 200 - + Span(name="/wiki/Rabbit", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x4bf0be462b91d6ef, trace_state={}), kind=SpanKind.CLIENT, parent=Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={})), start_time=2019-11-07T21:52:59.601597Z, end_time=2019-11-07T21:53:00.380491Z) + Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={})), start_time=2019-11-07T21:52:59.601233Z, end_time=2019-11-07T21:53:00.384485Z) + Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={}), kind=SpanKind.SERVER, parent=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), start_time=2019-11-07T21:52:59.600816Z, end_time=2019-11-07T21:53:00.385322Z) + + +Jaeger +****** + +Setup `Jaeger Tracing `_. + +* Run the server + +.. code-block:: sh + + $ pip install opentelemetry-ext-jaeger + $ EXPORTER=jaeger python server.py + +* Run the client from a different terminal + +.. code-block:: sh + + $ EXPORTER=jaeger python tracer_client.py + +The traces should be available in the Jaeger UI at ``_ + +Useful links +------------ + +- For more information on OpenTelemetry, visit OpenTelemetry_. +- For more information on tracing in Python, visit Jaeger_. + +.. _Jaeger: https://www.jaegertracing.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ \ No newline at end of file diff --git a/examples/http/__init__.py b/docs/examples/http/__init__.py similarity index 100% rename from examples/http/__init__.py rename to docs/examples/http/__init__.py diff --git a/examples/http/requirements.txt b/docs/examples/http/requirements.txt similarity index 100% rename from examples/http/requirements.txt rename to docs/examples/http/requirements.txt diff --git a/examples/http/server.py b/docs/examples/http/server.py similarity index 100% rename from examples/http/server.py rename to docs/examples/http/server.py diff --git a/examples/http/tests/__init__.py b/docs/examples/http/tests/__init__.py similarity index 100% rename from examples/http/tests/__init__.py rename to docs/examples/http/tests/__init__.py diff --git a/examples/http/tests/test_http.py b/docs/examples/http/tests/test_http.py similarity index 100% rename from examples/http/tests/test_http.py rename to docs/examples/http/tests/test_http.py diff --git a/examples/http/tracer_client.py b/docs/examples/http/tracer_client.py similarity index 100% rename from examples/http/tracer_client.py rename to docs/examples/http/tracer_client.py diff --git a/examples/metrics/observer_example.py b/docs/examples/metrics/observer_example.py similarity index 100% rename from examples/metrics/observer_example.py rename to docs/examples/metrics/observer_example.py diff --git a/examples/metrics/prometheus.py b/docs/examples/metrics/prometheus.py similarity index 100% rename from examples/metrics/prometheus.py rename to docs/examples/metrics/prometheus.py diff --git a/examples/metrics/record.py b/docs/examples/metrics/record.py similarity index 100% rename from examples/metrics/record.py rename to docs/examples/metrics/record.py diff --git a/examples/metrics/simple_example.py b/docs/examples/metrics/simple_example.py similarity index 100% rename from examples/metrics/simple_example.py rename to docs/examples/metrics/simple_example.py diff --git a/examples/opentelemetry-example-app/README.rst b/docs/examples/opentelemetry-example-app/README.rst similarity index 100% rename from examples/opentelemetry-example-app/README.rst rename to docs/examples/opentelemetry-example-app/README.rst diff --git a/examples/opentelemetry-example-app/setup.py b/docs/examples/opentelemetry-example-app/setup.py similarity index 100% rename from examples/opentelemetry-example-app/setup.py rename to docs/examples/opentelemetry-example-app/setup.py diff --git a/examples/opentelemetry-example-app/src/opentelemetry_example_app/__init__.py b/docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/__init__.py similarity index 100% rename from examples/opentelemetry-example-app/src/opentelemetry_example_app/__init__.py rename to docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/__init__.py diff --git a/examples/opentelemetry-example-app/src/opentelemetry_example_app/flask_example.py b/docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/flask_example.py similarity index 100% rename from examples/opentelemetry-example-app/src/opentelemetry_example_app/flask_example.py rename to docs/examples/opentelemetry-example-app/src/opentelemetry_example_app/flask_example.py diff --git a/examples/opentelemetry-example-app/tests/__init__.py b/docs/examples/opentelemetry-example-app/tests/__init__.py similarity index 100% rename from examples/opentelemetry-example-app/tests/__init__.py rename to docs/examples/opentelemetry-example-app/tests/__init__.py diff --git a/examples/opentelemetry-example-app/tests/test_flask_example.py b/docs/examples/opentelemetry-example-app/tests/test_flask_example.py similarity index 100% rename from examples/opentelemetry-example-app/tests/test_flask_example.py rename to docs/examples/opentelemetry-example-app/tests/test_flask_example.py diff --git a/docs/examples/opentracing/README.rst b/docs/examples/opentracing/README.rst new file mode 100644 index 00000000000..0305da99558 --- /dev/null +++ b/docs/examples/opentracing/README.rst @@ -0,0 +1,97 @@ +OpenTracing Shim Example +========================== + +This example shows how to use the `opentelemetry-ext-opentracing-shim +package `_ +to interact with libraries instrumented with +`opentracing-python `_. + +The included ``rediscache`` library creates spans via the OpenTracing Redis +integration, +`redis_opentracing `_. +Spans are exported via the Jaeger exporter, which is attached to the +OpenTelemetry tracer. + + +The source files required to run this example are available :scm_web:`here `. + +Installation +------------ + +Jaeger +****** + +Setup `Jaeger Tracing `_. + +Redis +***** + +Install Redis following the `instructions `_. + +Make sure that the Redis server is running by executing this: + +.. code-block:: sh + + $ redis-server + + +Python Dependencies +******************* + +Install the Python dependencies in :scm_raw_web:`requirements.txt ` + +.. code-block:: sh + + $ pip install -r requirements.txt + + +Alternatively, you can install the Python dependencies separately: + +.. code-block:: sh + + $ pip install \ + opentelemetry-api \ + opentelemetry-sdk \ + opentelemetry-ext-jaeger \ + opentelemetry-opentracing-shim \ + redis \ + redis_opentracing + + +Run the Application +------------------- + +The example script calculates a few Fibonacci numbers and stores the results in +Redis. The script, the ``rediscache`` library, and the OpenTracing Redis +integration all contribute spans to the trace. + +To run the script: + +.. code-block:: sh + + $ python main.py + + +After running, you can view the generated trace in the Jaeger UI. + +Jaeger UI +********* + +Open the Jaeger UI in your browser at +``_ and view traces for the +"OpenTracing Shim Example" service. + +Each ``main.py`` run should generate a trace, and each trace should include +multiple spans that represent calls to Redis. + +Note that tags and logs (OpenTracing) and attributes and events (OpenTelemetry) +from both tracing systems appear in the exported trace. + +Useful links +------------ + +- For more information on OpenTelemetry, visit OpenTelemetry_. +- For more information on tracing in Python, visit Jaeger_. + +.. _Jaeger: https://www.jaegertracing.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ diff --git a/examples/opentracing/__init__.py b/docs/examples/opentracing/__init__.py similarity index 100% rename from examples/opentracing/__init__.py rename to docs/examples/opentracing/__init__.py diff --git a/examples/opentracing/images/jaeger-span-expanded.png b/docs/examples/opentracing/images/jaeger-span-expanded.png similarity index 100% rename from examples/opentracing/images/jaeger-span-expanded.png rename to docs/examples/opentracing/images/jaeger-span-expanded.png diff --git a/examples/opentracing/images/jaeger-trace-full.png b/docs/examples/opentracing/images/jaeger-trace-full.png similarity index 100% rename from examples/opentracing/images/jaeger-trace-full.png rename to docs/examples/opentracing/images/jaeger-trace-full.png diff --git a/examples/opentracing/main.py b/docs/examples/opentracing/main.py similarity index 100% rename from examples/opentracing/main.py rename to docs/examples/opentracing/main.py diff --git a/examples/opentracing/rediscache.py b/docs/examples/opentracing/rediscache.py similarity index 100% rename from examples/opentracing/rediscache.py rename to docs/examples/opentracing/rediscache.py diff --git a/examples/opentracing/requirements.txt b/docs/examples/opentracing/requirements.txt similarity index 100% rename from examples/opentracing/requirements.txt rename to docs/examples/opentracing/requirements.txt diff --git a/docs/ext/dbapi/dbapi.rst b/docs/ext/dbapi/dbapi.rst new file mode 100644 index 00000000000..dbe6dbbeabc --- /dev/null +++ b/docs/ext/dbapi/dbapi.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-dbapi/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.dbapi + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.flask.rst b/docs/ext/flask/flask.rst similarity index 63% rename from docs/opentelemetry.ext.flask.rst rename to docs/ext/flask/flask.rst index 87ad93b867f..e65323cc81f 100644 --- a/docs/opentelemetry.ext.flask.rst +++ b/docs/ext/flask/flask.rst @@ -1,5 +1,5 @@ -opentelemetry.ext.flask package -========================================== +.. include:: ../../../ext/opentelemetry-ext-flask/README.rst + Module contents --------------- diff --git a/docs/opentelemetry.ext.http_requests.rst b/docs/ext/http_requests/http_requests.rst similarity index 62% rename from docs/opentelemetry.ext.http_requests.rst rename to docs/ext/http_requests/http_requests.rst index fbc9bd2a630..779be3e0333 100644 --- a/docs/opentelemetry.ext.http_requests.rst +++ b/docs/ext/http_requests/http_requests.rst @@ -1,5 +1,4 @@ -opentelemetry.ext.http_requests package -========================================== +.. include:: ../../../ext/opentelemetry-ext-http-requests/README.rst Module contents --------------- diff --git a/docs/ext/jaeger/jaeger.rst b/docs/ext/jaeger/jaeger.rst new file mode 100644 index 00000000000..70b9c04205f --- /dev/null +++ b/docs/ext/jaeger/jaeger.rst @@ -0,0 +1,17 @@ +.. include:: ../../../ext/opentelemetry-ext-jaeger/README.rst + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.jaeger + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +.. automodule:: opentelemetry.ext.jaeger.gen.jaeger.ttypes + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/ext/mysql/mysql.rst b/docs/ext/mysql/mysql.rst new file mode 100644 index 00000000000..e2c01371cde --- /dev/null +++ b/docs/ext/mysql/mysql.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-mysql/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.mysql + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/ext/opentracing_shim/opentracing_shim.rst b/docs/ext/opentracing_shim/opentracing_shim.rst new file mode 100644 index 00000000000..f27974b9c07 --- /dev/null +++ b/docs/ext/opentracing_shim/opentracing_shim.rst @@ -0,0 +1,5 @@ +OpenTracing Shim for OpenTelemetry +================================== + +.. automodule:: opentelemetry.ext.opentracing_shim + :no-show-inheritance: diff --git a/docs/ext/otcollector/otcollector.rst b/docs/ext/otcollector/otcollector.rst new file mode 100644 index 00000000000..c940bfacaad --- /dev/null +++ b/docs/ext/otcollector/otcollector.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-otcollector/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.otcollector + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/ext/prometheus/prometheus.rst b/docs/ext/prometheus/prometheus.rst new file mode 100644 index 00000000000..7f331cb6dad --- /dev/null +++ b/docs/ext/prometheus/prometheus.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-prometheus/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.prometheus + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/ext/psycopg2/psycopg2.rst b/docs/ext/psycopg2/psycopg2.rst new file mode 100644 index 00000000000..89cebce345f --- /dev/null +++ b/docs/ext/psycopg2/psycopg2.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-psycopg2/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.psycopg2 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/opentelemetry.ext.pymongo.rst b/docs/ext/pymongo/pymongo.rst similarity index 63% rename from docs/opentelemetry.ext.pymongo.rst rename to docs/ext/pymongo/pymongo.rst index e5c262ac162..848c0dba253 100644 --- a/docs/opentelemetry.ext.pymongo.rst +++ b/docs/ext/pymongo/pymongo.rst @@ -1,5 +1,4 @@ -opentelemetry.ext.pymongo package -========================================== +.. include:: ../../../ext/opentelemetry-ext-pymongo/README.rst Module contents --------------- diff --git a/docs/opentelemetry.ext.wsgi.rst b/docs/ext/wsgi/wsgi.rst similarity index 63% rename from docs/opentelemetry.ext.wsgi.rst rename to docs/ext/wsgi/wsgi.rst index 506bc1efe43..be8194bdd6b 100644 --- a/docs/opentelemetry.ext.wsgi.rst +++ b/docs/ext/wsgi/wsgi.rst @@ -1,5 +1,5 @@ -opentelemetry.ext.wsgi package -========================================== +.. include:: ../../../ext/opentelemetry-ext-wsgi/README.rst + Module contents --------------- diff --git a/docs/ext/zipkin/zipkin.rst b/docs/ext/zipkin/zipkin.rst new file mode 100644 index 00000000000..8826178908c --- /dev/null +++ b/docs/ext/zipkin/zipkin.rst @@ -0,0 +1,10 @@ +.. include:: ../../../ext/opentelemetry-ext-zipkin/README.rst + + +Module contents +--------------- + +.. automodule:: opentelemetry.ext.zipkin + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/index.rst b/docs/index.rst index c597d4a681f..f52129829a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,47 +1,104 @@ -.. OpenTelemetry documentation master file, created by - sphinx-quickstart on Mon Jun 3 22:48:38 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +OpenTelemetry-Python +==================== -OpenTelemetry -============= +The Python `OpenTelemetry `_ client. -Welcome to OpenTelemetry's documentation! +.. image:: https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python + :target: https://gitter.im/open-telemetry/opentelemetry-python + :alt: Gitter Chat -This documentation describes the ``opentelemetry-api``, ``opentelemetry-sdk`` -and integration packages. -.. toctree:: - :maxdepth: 1 - :caption: OpenTelemetry API: +This documentation describes the :doc:`opentelemetry-api `, +:doc:`opentelemetry-sdk `, and several `integration packages <#integrations>`_. + +**Please note** that this library is currently in alpha, and shouldn't be +used in production environments. + +Installation +------------ + +The API and SDK packages are available on PyPI, and can installed via pip: + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + +In addition, there are several extension packages which can be installed separately as:: + + pip install opentelemetry-ext-{integration} + +The extension packages can be found in :scm_web:`ext/ directory of the repository `. + +In addition, third party exporters are available: + +* `Azure Monitor `_ + +Installing Cutting Edge Packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +While the project is pre-1.0, there may be significant functionality that +has not yet been released to PyPI. In that situation, you may want to +install the packages directly from the repo. This can be done by cloning the +repositry and doing an `editable +install `_: - opentelemetry.context - opentelemetry.metrics - opentelemetry.trace - opentelemetry.util.loader +.. code-block:: sh + + git clone https://github.com/open-telemetry/opentelemetry-python.git + cd opentelemetry-python + pip install -e ./opentelemetry-api + pip install -e ./opentelemetry-sdk + pip install -e ./ext/opentelemetry-ext-{integration} + + +Quick Start +----------- + +OpenTelemetry can be used to emit distributed traces and metrics from your application. +The following are two simple examples using the API and SDK, you can find more +elaborated examples in `Examples`_. + +.. TODO: Link to complete and better examples + +Tracing +~~~~~~~ + +.. literalinclude:: trace_example.py + :language: python + +Metrics +~~~~~~~ + +.. literalinclude:: metrics_example.py + :language: python .. toctree:: :maxdepth: 1 - :caption: OpenTelemetry SDK: + :caption: OpenTelemetry Python Packages + :name: packages - opentelemetry.sdk.context - opentelemetry.sdk.metrics - opentelemetry.sdk.trace + api/api + sdk/sdk + +.. toctree:: + :maxdepth: 1 + :caption: OpenTelemetry Integrations + :name: integrations + :glob: + ext/** .. toctree:: :maxdepth: 1 - :caption: OpenTelemetry Integrations: + :caption: Examples + :name: examples + :glob: - opentelemetry.ext.flask - opentelemetry.ext.http_requests - opentelemetry.ext.jaeger - opentelemetry.ext.opentracing_shim - opentelemetry.ext.pymongo - opentelemetry.ext.wsgi + examples/** Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/docs/metrics_example.py b/docs/metrics_example.py new file mode 100644 index 00000000000..8ae01f5e98a --- /dev/null +++ b/docs/metrics_example.py @@ -0,0 +1,23 @@ +from opentelemetry import metrics +from opentelemetry.sdk.metrics import Counter, MeterProvider +from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter +from opentelemetry.sdk.metrics.export.controller import PushController + +metrics.set_preferred_meter_provider_implementation(lambda _: MeterProvider()) +meter = metrics.get_meter(__name__) +exporter = ConsoleMetricsExporter() +controller = PushController(meter, exporter, 5) + +requests_counter = meter.create_metric( + name="requests", + description="number of requests", + unit="1", + value_type=int, + metric_type=Counter, + label_keys=("environment",), +) + +staging_label_set = meter.get_label_set({"environment": "staging"}) +requests_counter.add(25, staging_label_set) + +input("Press a key to finish...\n") diff --git a/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst b/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst deleted file mode 100644 index 8b69e013b42..00000000000 --- a/docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst +++ /dev/null @@ -1,11 +0,0 @@ -opentelemetry.ext.jaeger.gen.jaeger.ttypes -========================================== - - -Module contents ---------------- - -.. automodule:: opentelemetry.ext.jaeger.gen.jaeger.ttypes - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/opentelemetry.ext.jaeger.rst b/docs/opentelemetry.ext.jaeger.rst deleted file mode 100644 index 74a7fb399e6..00000000000 --- a/docs/opentelemetry.ext.jaeger.rst +++ /dev/null @@ -1,19 +0,0 @@ -opentelemetry.ext.jaeger package -========================================== - - -Submodules ----------- - -.. toctree:: - - opentelemetry.ext.jaeger.gen.jaeger.ttypes - - -Module contents ---------------- - -.. automodule:: opentelemetry.ext.jaeger - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/opentelemetry.ext.opentracing_shim.rst b/docs/opentelemetry.ext.opentracing_shim.rst deleted file mode 100644 index 921d6c290b3..00000000000 --- a/docs/opentelemetry.ext.opentracing_shim.rst +++ /dev/null @@ -1,8 +0,0 @@ -opentelemetry.ext.opentracing_shim package -========================================== - -Module contents ---------------- - -.. automodule:: opentelemetry.ext.opentracing_shim - :no-show-inheritance: diff --git a/docs/opentelemetry.sdk.context.rst b/docs/sdk/context.rst similarity index 100% rename from docs/opentelemetry.sdk.context.rst rename to docs/sdk/context.rst diff --git a/docs/opentelemetry.sdk.metrics.export.aggregate.rst b/docs/sdk/metrics.export.aggregate.rst similarity index 100% rename from docs/opentelemetry.sdk.metrics.export.aggregate.rst rename to docs/sdk/metrics.export.aggregate.rst diff --git a/docs/opentelemetry.sdk.metrics.export.batcher.rst b/docs/sdk/metrics.export.batcher.rst similarity index 85% rename from docs/opentelemetry.sdk.metrics.export.batcher.rst rename to docs/sdk/metrics.export.batcher.rst index 5dbd1d6e582..dab2dd3415b 100644 --- a/docs/opentelemetry.sdk.metrics.export.batcher.rst +++ b/docs/sdk/metrics.export.batcher.rst @@ -3,7 +3,7 @@ opentelemetry.sdk.metrics.export.batcher .. toctree:: - opentelemetry.sdk.metrics.export + metrics.export .. automodule:: opentelemetry.sdk.metrics.export.batcher :members: diff --git a/docs/opentelemetry.sdk.metrics.export.rst b/docs/sdk/metrics.export.rst similarity index 100% rename from docs/opentelemetry.sdk.metrics.export.rst rename to docs/sdk/metrics.export.rst diff --git a/docs/opentelemetry.sdk.metrics.rst b/docs/sdk/metrics.rst similarity index 61% rename from docs/opentelemetry.sdk.metrics.rst rename to docs/sdk/metrics.rst index 88612046c8a..7030285982e 100644 --- a/docs/opentelemetry.sdk.metrics.rst +++ b/docs/sdk/metrics.rst @@ -6,9 +6,9 @@ Submodules .. toctree:: - opentelemetry.sdk.metrics.export.aggregate - opentelemetry.sdk.metrics.export.batcher - opentelemetry.sdk.util.instrumentation + metrics.export.aggregate + metrics.export.batcher + util.instrumentation .. automodule:: opentelemetry.sdk.metrics :members: diff --git a/docs/sdk/sdk.rst b/docs/sdk/sdk.rst new file mode 100644 index 00000000000..b16a6f26508 --- /dev/null +++ b/docs/sdk/sdk.rst @@ -0,0 +1,11 @@ +OpenTelemetry Python SDK +======================== + +.. TODO: what is the SDK + +.. toctree:: + :maxdepth: 1 + + context + metrics + trace \ No newline at end of file diff --git a/docs/opentelemetry.sdk.trace.export.rst b/docs/sdk/trace.export.rst similarity index 100% rename from docs/opentelemetry.sdk.trace.export.rst rename to docs/sdk/trace.export.rst diff --git a/docs/opentelemetry.sdk.trace.rst b/docs/sdk/trace.rst similarity index 73% rename from docs/opentelemetry.sdk.trace.rst rename to docs/sdk/trace.rst index 1c0e9b6f61c..ce06fb4abb0 100644 --- a/docs/opentelemetry.sdk.trace.rst +++ b/docs/sdk/trace.rst @@ -6,8 +6,8 @@ Submodules .. toctree:: - opentelemetry.sdk.trace.export - opentelemetry.sdk.util.instrumentation + trace.export + util.instrumentation .. automodule:: opentelemetry.sdk.trace :members: diff --git a/docs/opentelemetry.sdk.util.instrumentation.rst b/docs/sdk/util.instrumentation.rst similarity index 100% rename from docs/opentelemetry.sdk.util.instrumentation.rst rename to docs/sdk/util.instrumentation.rst diff --git a/docs/trace_example.py b/docs/trace_example.py new file mode 100644 index 00000000000..8197dee156b --- /dev/null +++ b/docs/trace_example.py @@ -0,0 +1,18 @@ +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import ( + ConsoleSpanExporter, + SimpleExportSpanProcessor, +) + +trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider()) +trace.tracer_provider().add_span_processor( + SimpleExportSpanProcessor(ConsoleSpanExporter()) +) + +tracer = trace.get_tracer(__name__) + +with tracer.start_as_current_span("foo"): + with tracer.start_as_current_span("bar"): + with tracer.start_as_current_span("baz"): + print("Hello world from OpenTelemetry Python!") diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 7fcc3f7dc48..00000000000 --- a/examples/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Examples -This folder contains various examples to demonstrate using OpenTelemetry. - -##### basic_tracer -This example shows how to use OpenTelemetry to instrument an application - e.g. a batch job. - -##### http -This example shows how to use [OpenTelemetryMiddleware](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-wsgi) and [requests](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-http-requests) integrations to instrument a client and a server. - -##### opentelemetry-example-app -This package is a complete example of an application instrumented with OpenTelemetry. \ No newline at end of file diff --git a/examples/basic_tracer/README.md b/examples/basic_tracer/README.md deleted file mode 100644 index ae9e4ca8959..00000000000 --- a/examples/basic_tracer/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# Overview - -This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job. -It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io). - -## Installation - -```sh -$ pip install opentelemetry-api opentelemetry-sdk -``` - -Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one) - -## Run the Application - -### Console - -* Run the sample - -```bash -$ # from this directory -$ python tracer.py -``` - -The output will be displayed at the console - -```bash -AsyncRuntimeContext({'current_span': Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}))}) -Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={})), start_time=2019-11-07T21:26:45.934412Z, end_time=2019-11-07T21:26:45.934567Z) -Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={})), start_time=2019-11-07T21:26:45.934396Z, end_time=2019-11-07T21:26:45.934576Z) -Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z) -``` - - -### Jaeger - -* Run the sample - -```sh -$ pip install opentelemetry-ext-jaeger -$ # from this directory -$ EXPORTER=jaeger python tracer.py -``` - -#### Jaeger UI - -Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686) - -

-Select `basic-service` under *Service Name* and click on *Find Traces*. - -Click on the trace to view its details. - -

- -### Collector - -* Start Collector - -```sh -$ pip install docker-compose -$ cd docker -$ docker-compose up - -* Run the sample - -$ pip install opentelemetry-ext-otcollector -$ # from this directory -$ EXPORTER=collector python tracer.py -``` - -Collector is configured to export to Jaeger, follow Jaeger UI isntructions to find the traces. - - - -## Useful links -- For more information on OpenTelemetry, visit: -- For more information on tracing in Python, visit: - -## LICENSE - -Apache License 2.0 diff --git a/examples/basic_tracer/images/jaeger-ui-detail.png b/examples/basic_tracer/images/jaeger-ui-detail.png deleted file mode 100644 index 63491e132b5..00000000000 Binary files a/examples/basic_tracer/images/jaeger-ui-detail.png and /dev/null differ diff --git a/examples/basic_tracer/images/jaeger-ui.png b/examples/basic_tracer/images/jaeger-ui.png deleted file mode 100644 index 08e6718eef1..00000000000 Binary files a/examples/basic_tracer/images/jaeger-ui.png and /dev/null differ diff --git a/examples/http/README.md b/examples/http/README.md deleted file mode 100644 index 5e6f2d7efad..00000000000 --- a/examples/http/README.md +++ /dev/null @@ -1,80 +0,0 @@ -# Overview - -This example shows how to use [OpenTelemetryMiddleware](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-wsgi) and [requests](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-http-requests) integrations to instrument a client and a server in Python. -It supports exporting spans either to the console or to [Jaeger](https://www.jaegertracing.io). - -## Installation - -```sh -$ pip install opentelemetry-api opentelemetry-sdk opentelemetry-ext-wsgi opentelemetry-ext-http-requests -``` - -Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one) - -## Run the Application - -### Console - -* Run the server - -```bash -$ # from this directory -$ python server.py -``` - -* Run the client from a different terminal - -```bash -$ # from this directory -$ python tracer_client.py -``` - -The output will be displayed at the console on the client side - -```bash -Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), kind=SpanKind.CLIENT, parent=None, start_time=2019-11-07T21:52:59.591634Z, end_time=2019-11-07T21:53:00.386014Z) -``` - -And on the server - -```bash -127.0.0.1 - - [07/Nov/2019 13:53:00] "GET / HTTP/1.1" 200 - -Span(name="/wiki/Rabbit", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x4bf0be462b91d6ef, trace_state={}), kind=SpanKind.CLIENT, parent=Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={})), start_time=2019-11-07T21:52:59.601597Z, end_time=2019-11-07T21:53:00.380491Z) -Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={})), start_time=2019-11-07T21:52:59.601233Z, end_time=2019-11-07T21:53:00.384485Z) -Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={}), kind=SpanKind.SERVER, parent=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), start_time=2019-11-07T21:52:59.600816Z, end_time=2019-11-07T21:53:00.385322Z) -``` - -### Jaeger - -* Run the server - -```sh -$ pip install opentelemetry-ext-jaeger -$ # from this directory -$ EXPORTER=jaeger python server.py -``` - -* Run the client from a different terminal - -```bash -$ EXPORTER=jaeger python tracer_client.py -``` - -#### Jaeger UI - -Open the Jaeger UI in your browser [http://localhost:16686](http://localhost:16686) - -

-Select `http-server` under *Service Name* and click on *Find Traces*. - -Click on the trace to view its details. - -

- -## Useful links -- For more information on OpenTelemetry, visit: -- For more information on tracing in Python, visit: - -## LICENSE - -Apache License 2.0 diff --git a/examples/http/images/jaeger-ui-detail.png b/examples/http/images/jaeger-ui-detail.png deleted file mode 100644 index 50d1901de6c..00000000000 Binary files a/examples/http/images/jaeger-ui-detail.png and /dev/null differ diff --git a/examples/http/images/jaeger-ui.png b/examples/http/images/jaeger-ui.png deleted file mode 100644 index 02faad1de1e..00000000000 Binary files a/examples/http/images/jaeger-ui.png and /dev/null differ diff --git a/examples/opentracing/README.md b/examples/opentracing/README.md deleted file mode 100644 index 2f7a9264179..00000000000 --- a/examples/opentracing/README.md +++ /dev/null @@ -1,90 +0,0 @@ -# Overview - -This example shows how to use the [`opentelemetry-ext-opentracing-shim` -package](https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-opentracing-shim) -to interact with libraries instrumented with -[`opentracing-python`](https://github.com/opentracing/opentracing-python). - -The included `rediscache` library creates spans via the OpenTracing Redis -integration, -[`redis_opentracing`](https://github.com/opentracing-contrib/python-redis). -Spans are exported via the Jaeger exporter, which is attached to the -OpenTelemetry tracer. - -## Installation - -### Jaeger - -Install and run -[Jaeger](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one). -See the [basic tracer -example](https://github.com/open-telemetry/opentelemetry-python/tree/master/examples/basic-tracer) -for more detail. - -### Redis - -Install Redis following the [instructions](https://redis.io/topics/quickstart). - -Make sure that the Redis server is running by executing this: - -```sh -$ redis-server -``` - -### Python Dependencies - -Install the Python dependencies in [`requirements.txt`](requirements.txt): - -```sh -$ pip install -r requirements.txt -``` - -Alternatively, you can install the Python dependencies separately: - -```sh -$ pip install \ - opentelemetry-api \ - opentelemetry-sdk \ - opentelemetry-ext-jaeger \ - opentelemetry-opentracing-shim \ - redis \ - redis_opentracing -``` - -## Run the Application - -The example script calculates a few Fibonacci numbers and stores the results in -Redis. The script, the `rediscache` library, and the OpenTracing Redis -integration all contribute spans to the trace. - -To run the script: - -```sh -$ python main.py -``` - -After running, you can view the generated trace in the Jaeger UI. - -#### Jaeger UI - -Open the Jaeger UI in your browser at - and view traces for the -"OpenTracing Shim Example" service. - -Each `main.py` run should generate a trace, and each trace should include -multiple spans that represent calls to Redis. - -

- -Note that tags and logs (OpenTracing) and attributes and events (OpenTelemetry) -from both tracing systems appear in the exported trace. - -

- -## Useful links -- For more information on OpenTelemetry, visit: -- For more information on tracing in Python, visit: - -## LICENSE - -Apache License 2.0 diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py index 7f305dcc0d9..e256d9d3e6a 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py @@ -136,9 +136,9 @@ class Span(trace_api.Span): """ # Initialize these lazily assuming most spans won't have them. - empty_attributes = BoundedDict(MAX_NUM_ATTRIBUTES) - empty_events = BoundedList(MAX_NUM_EVENTS) - empty_links = BoundedList(MAX_NUM_LINKS) + _empty_attributes = BoundedDict(MAX_NUM_ATTRIBUTES) + _empty_events = BoundedList(MAX_NUM_EVENTS) + _empty_links = BoundedList(MAX_NUM_LINKS) def __init__( self, @@ -171,19 +171,19 @@ def __init__( self._lock = threading.Lock() if attributes is None: - self.attributes = Span.empty_attributes + self.attributes = Span._empty_attributes else: self.attributes = BoundedDict.from_map( MAX_NUM_ATTRIBUTES, attributes ) if events is None: - self.events = Span.empty_events + self.events = Span._empty_events else: self.events = BoundedList.from_seq(MAX_NUM_EVENTS, events) if links is None: - self.links = Span.empty_links + self.links = Span._empty_links else: self.links = BoundedList.from_seq(MAX_NUM_LINKS, links) @@ -227,7 +227,7 @@ def set_attribute(self, key: str, value: types.AttributeValue) -> None: return has_ended = self.end_time is not None if not has_ended: - if self.attributes is Span.empty_attributes: + if self.attributes is Span._empty_attributes: self.attributes = BoundedDict(MAX_NUM_ATTRIBUTES) if has_ended: logger.warning("Setting attribute on ended span.") @@ -274,7 +274,7 @@ def add_event( self.add_lazy_event( trace_api.Event( name, - Span.empty_attributes if attributes is None else attributes, + Span._empty_attributes if attributes is None else attributes, time_ns() if timestamp is None else timestamp, ) ) @@ -285,7 +285,7 @@ def add_lazy_event(self, event: trace_api.Event) -> None: return has_ended = self.end_time is not None if not has_ended: - if self.events is Span.empty_events: + if self.events is Span._empty_events: self.events = BoundedList(MAX_NUM_EVENTS) if has_ended: logger.warning("Calling add_event() on an ended span.") @@ -372,6 +372,7 @@ def __exit__( def generate_span_id() -> int: """Get a new random span ID. + Returns: A random 64-bit int for use as a span ID """ @@ -380,6 +381,7 @@ def generate_span_id() -> int: def generate_trace_id() -> int: """Get a new random trace ID. + Returns: A random 128-bit int for use as a trace ID """ @@ -404,7 +406,6 @@ def __init__( self.instrumentation_info = instrumentation_info def get_current_span(self): - """See `opentelemetry.trace.Tracer.get_current_span`.""" return self.source.get_current_span() def start_as_current_span( @@ -415,8 +416,6 @@ def start_as_current_span( attributes: Optional[types.Attributes] = None, links: Sequence[trace_api.Link] = (), ) -> Iterator[trace_api.Span]: - """See `opentelemetry.trace.Tracer.start_as_current_span`.""" - span = self.start_span(name, parent, kind, attributes, links) return self.use_span(span, end_on_exit=True) @@ -430,8 +429,6 @@ def start_span( # pylint: disable=too-many-locals start_time: Optional[int] = None, set_status_on_exception: bool = True, ) -> trace_api.Span: - """See `opentelemetry.trace.Tracer.start_span`.""" - if parent is Tracer.CURRENT_SPAN: parent = self.get_current_span() @@ -502,7 +499,6 @@ def start_span( # pylint: disable=too-many-locals def use_span( self, span: trace_api.Span, end_on_exit: bool = False ) -> Iterator[trace_api.Span]: - """See `opentelemetry.trace.Tracer.use_span`.""" try: token = context_api.attach(context_api.set_value(SPAN_KEY, span)) try: diff --git a/scripts/coverage.sh b/scripts/coverage.sh index 9b981b0817c..b9f9b6493e8 100755 --- a/scripts/coverage.sh +++ b/scripts/coverage.sh @@ -23,7 +23,7 @@ cov ext/opentelemetry-ext-jaeger cov ext/opentelemetry-ext-opentracing-shim cov ext/opentelemetry-ext-wsgi cov ext/opentelemetry-ext-zipkin -cov examples/opentelemetry-example-app +cov docs/examples/opentelemetry-example-app coverage report coverage xml diff --git a/tox.ini b/tox.ini index 0423a6cc7ea..52c82eba075 100644 --- a/tox.ini +++ b/tox.ini @@ -16,11 +16,11 @@ envlist = py3{4,5,6,7,8}-test-example-app pypy3-test-example-app - ; examples/basic_tracer + ; docs/examples/basic_tracer py3{4,5,6,7,8}-test-example-basic-tracer pypy3-test-example-basic-tracer - ; examples/http + ; docs/examples/http py3{4,5,6,7,8}-test-example-http pypy3-test-example-http @@ -112,9 +112,9 @@ changedir = test-ext-wsgi: ext/opentelemetry-ext-wsgi/tests test-ext-zipkin: ext/opentelemetry-ext-zipkin/tests test-ext-flask: ext/opentelemetry-ext-flask/tests - test-example-app: examples/opentelemetry-example-app/tests - test-example-basic-tracer: examples/basic_tracer/tests - test-example-http: examples/http/tests + test-example-app: docs/examples/opentelemetry-example-app/tests + test-example-basic-tracer: docs/examples/basic_tracer/tests + test-example-http: docs/examples/http/tests test-opentracing-shim: ext/opentelemetry-ext-opentracing-shim/tests commands_pre = @@ -126,14 +126,14 @@ commands_pre = example-app: pip install {toxinidir}/ext/opentelemetry-ext-http-requests example-app: pip install {toxinidir}/ext/opentelemetry-ext-wsgi example-app: pip install {toxinidir}/ext/opentelemetry-ext-flask - example-app: pip install {toxinidir}/examples/opentelemetry-example-app + example-app: pip install {toxinidir}/docs/examples/opentelemetry-example-app example-basic-tracer: pip install -e {toxinidir}/opentelemetry-api example-basic-tracer: pip install -e {toxinidir}/opentelemetry-sdk example-http: pip install -e {toxinidir}/opentelemetry-api example-http: pip install -e {toxinidir}/opentelemetry-sdk example-http: pip install -e {toxinidir}/ext/opentelemetry-ext-http-requests example-http: pip install -e {toxinidir}/ext/opentelemetry-ext-wsgi - example-http: pip install -r {toxinidir}/examples/http/requirements.txt + example-http: pip install -r {toxinidir}/docs/examples/http/requirements.txt ext: pip install {toxinidir}/opentelemetry-api wsgi,flask: pip install {toxinidir}/ext/opentelemetry-ext-testutil @@ -208,11 +208,14 @@ deps = thrift pymongo flask + mysql-connector-python + wrapt + psycopg2-binary changedir = docs commands = - sphinx-build -E -a -W --keep-going -b html -T . _build/html + sphinx-build -E -a --keep-going -b html -T . _build/html [testenv:py38-tracecontext] basepython: python3.8