diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b6918ec30d..9c6e72244de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ This is the main repo for OpenTelemetry Python. Nevertheless, there are other re Please take a look at this list first, your contributions may belong in one of these repos better: 1. [OpenTelemetry Contrib](https://github.com/open-telemetry/opentelemetry-python-contrib): Instrumentations for third-party - libraries and frameworks. There is an ongoing effort to migrate into the Opentelemetry Contrib repo some of the existing + libraries and frameworks. There is an ongoing effort to migrate into the OpenTelemetry Contrib repo some of the existing programmatic instrumentations that are now in the `ext` directory in the main OpenTelemetry repo. Please ask in the Slack channel (see below) for guidance if you want to contribute with these instrumentations. diff --git a/dev-requirements.txt b/dev-requirements.txt index bcbc90148c1..2fb15652b4f 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -4,9 +4,9 @@ isort~=5.8 black~=20.8b1 httpretty~=1.0 mypy==0.812 -sphinx~=2.1 -sphinx-rtd-theme~=0.4 -sphinx-autodoc-typehints~=1.10.2 +sphinx~=3.5.4 +sphinx-rtd-theme~=0.5 +sphinx-autodoc-typehints pytest>=6.0 pytest-cov>=2.8 readme-renderer~=24.0 diff --git a/docs-requirements.txt b/docs-requirements.txt index f802674afd0..f60325f00b1 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -1,6 +1,8 @@ -sphinx~=2.4 -sphinx-rtd-theme~=0.4 +sphinx~=3.5.4 +sphinx-rtd-theme~=0.5 sphinx-autodoc-typehints +# used to generate docs for the website +sphinx-jekyll-builder # Need to install the api/sdk in the venv for autodoc. Modifying sys.path # doesn't work for pkg_resources. diff --git a/docs/conf.py b/docs/conf.py index 38a26e323fd..c1476acf177 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -125,7 +125,15 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "examples/fork-process-model/flask-gunicorn", + "examples/fork-process-model/flask-uwsgi", + "examples/error_handler/error_handler_0", + "examples/error_handler/error_handler_1", +] autodoc_default_options = { "members": True, diff --git a/docs/examples/auto-instrumentation/README.rst b/docs/examples/auto-instrumentation/README.rst index 9298c9bef2f..23fb47b3964 100644 --- a/docs/examples/auto-instrumentation/README.rst +++ b/docs/examples/auto-instrumentation/README.rst @@ -45,7 +45,7 @@ Manually instrumented server return "served" Server not instrumented manually -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``server_uninstrumented.py`` @@ -57,7 +57,7 @@ Server not instrumented manually return "served" Prepare ------------ +------- Execute the following example in a separate virtual environment. Run the following commands to prepare for auto-instrumentation: @@ -69,7 +69,7 @@ Run the following commands to prepare for auto-instrumentation: $ source auto_instrumentation/bin/activate Install ------------- +------- Run the following commands to install the appropriate packages. The ``opentelemetry-instrumentation`` package provides several @@ -90,7 +90,7 @@ a server as well as the process of executing an automatically instrumented server. Execute a manually instrumented server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Execute the server in two separate consoles, one to run each of the scripts that make up this example: @@ -145,7 +145,7 @@ similar to the following example: } Execute an automatically instrumented server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Stop the execution of ``server_instrumented.py`` with ``ctrl + c`` and run the following command instead: @@ -208,7 +208,7 @@ You can see that both outputs are the same because automatic instrumentation doe exactly what manual instrumentation does. Instrumentation while debugging -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The debug mode can be enabled in the Flask app like this: @@ -226,3 +226,11 @@ reloader. To run instrumentation while the debug mode is enabled, set the if __name__ == "__main__": app.run(port=8082, debug=True, use_reloader=False) + + +Additional resources +~~~~~~~~~~~~~~~~~~~~ + +In order to send telemetry to an OpenTelemetry Collector without doing any +additional configuration, read about the `OpenTelemetry Distro <../distro/README.html>`_ +package. diff --git a/docs/examples/basic_context/README.rst b/docs/examples/basic_context/README.rst index 361192b96fc..1499a4bf8e6 100644 --- a/docs/examples/basic_context/README.rst +++ b/docs/examples/basic_context/README.rst @@ -1,14 +1,11 @@ Basic Context ============= -These examples show how context is propagated through Spans in OpenTelemetry. - -There are three different examples: +These examples show how context is propagated through Spans in OpenTelemetry. There are three different +examples: * implicit_context: Shows how starting a span implicitly creates context. - * child_context: Shows how context is propagated through child spans. - * async_context: Shows how context can be shared in another coroutine. The source files of these examples are available :scm_web:`here `. diff --git a/docs/examples/basic_tracer/README.rst b/docs/examples/basic_tracer/README.rst index 618263b7a4f..572b4dc8704 100644 --- a/docs/examples/basic_tracer/README.rst +++ b/docs/examples/basic_tracer/README.rst @@ -1,12 +1,9 @@ Basic Trace =========== -These examples show how to use OpenTelemetry to create and export Spans. - -There are two different examples: +These examples show how to use OpenTelemetry to create and export Spans. There are two different examples: * basic_trace: Shows how to configure a SpanProcessor and Exporter, and how to create a tracer and span. - * resources: Shows how to add resource information to a Provider. The source files of these examples are available :scm_web:`here `. diff --git a/docs/examples/datadog_exporter/README.rst b/docs/examples/datadog_exporter/README.rst index 03f485da159..39e0798da30 100644 --- a/docs/examples/datadog_exporter/README.rst +++ b/docs/examples/datadog_exporter/README.rst @@ -1,5 +1,5 @@ -Datadog Exporter Example -======================== +Datadog Exporter +================ These examples show how to use OpenTelemetry to send tracing data to Datadog. diff --git a/docs/examples/distro/README.rst b/docs/examples/distro/README.rst new file mode 100644 index 00000000000..f58680609ab --- /dev/null +++ b/docs/examples/distro/README.rst @@ -0,0 +1,104 @@ +OpenTelemetry Distro +==================== + +In order to make using OpenTelemetry and auto-instrumentation as quick as possible without sacrificing flexibility, +OpenTelemetry distros provide a mechanism to automatically configure some of the more common options for users. By +harnessing their power, users of OpenTelemetry can configure the components as they need. The ``opentelemetry-distro`` +package provides some defaults to users looking to get started, it configures: + +- the SDK TracerProvider +- a BatchSpanProcessor +- the OTLP ``SpanExporter`` to send data to an OpenTelemetry collector + +The package also provides a starting point for anyone interested in producing an alternative distro. The +interfaces implemented by the package are loaded by the auto-instrumentation via the ``opentelemetry_distro`` +and ``opentelemetry_configurator`` entry points to configure the application before any other code is +executed. + +In order to automatically export data from OpenTelemetry to the OpenTelemetry collector, installing the +package will setup all the required entry points. + +.. code:: sh + + $ pip install opentelemetry-distro[otlp] opentelemetry-instrumentation + +Start the Collector locally to see data being exported. Write the following file: + +.. code-block:: yaml + + # /tmp/otel-collector-config.yaml + receivers: + otlp: + protocols: + grpc: + http: + exporters: + logging: + loglevel: debug + processors: + batch: + service: + pipelines: + traces: + receivers: [otlp] + exporters: [logging] + processors: [batch] + +Then start the Docker container: + +.. code-block:: sh + + docker run -p 4317:4317 \ + -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \ + otel/opentelemetry-collector:latest \ + --config=/etc/otel-collector-config.yaml + +The following code will create a span with no configuration. + +.. code:: python + + # no_configuration.py + from opentelemetry import trace + + with trace.get_tracer(__name__).start_as_current_span("foo"): + with trace.get_tracer(__name__).start_as_current_span("bar"): + print("baz") + +Lastly, run the ``no_configuration.py`` with the auto-instrumentation: + +.. code-block:: sh + + $ opentelemetry-instrument python no_configuration.py + +The resulting span will appear in the output from the collector and look similar to this: + +.. code-block:: sh + + Resource labels: + -> telemetry.sdk.language: STRING(python) + -> telemetry.sdk.name: STRING(opentelemetry) + -> telemetry.sdk.version: STRING(1.1.0) + -> service.name: STRING(unknown_service) + InstrumentationLibrarySpans #0 + InstrumentationLibrary __main__ + Span #0 + Trace ID : db3c99e5bfc50ef8be1773c3765e8845 + Parent ID : 0677126a4d110cb8 + ID : 3163b3022808ed1b + Name : bar + Kind : SPAN_KIND_INTERNAL + Start time : 2021-05-06 22:54:51.23063 +0000 UTC + End time : 2021-05-06 22:54:51.230684 +0000 UTC + Status code : STATUS_CODE_UNSET + Status message : + Span #1 + Trace ID : db3c99e5bfc50ef8be1773c3765e8845 + Parent ID : + ID : 0677126a4d110cb8 + Name : foo + Kind : SPAN_KIND_INTERNAL + Start time : 2021-05-06 22:54:51.230549 +0000 UTC + End time : 2021-05-06 22:54:51.230706 +0000 UTC + Status code : STATUS_CODE_UNSET + Status message : + diff --git a/docs/examples/django/README.rst b/docs/examples/django/README.rst index bd0b36940a6..656a07b6da8 100644 --- a/docs/examples/django/README.rst +++ b/docs/examples/django/README.rst @@ -1,5 +1,5 @@ -OpenTelemetry Django Instrumentation Example -============================================ +Django Instrumentation +====================== This shows how to use ``opentelemetry-instrumentation-django`` to automatically instrument a Django app. diff --git a/docs/examples/opencensus-exporter-tracer/README.rst b/docs/examples/opencensus-exporter-tracer/README.rst index d147f008d49..3047987c2c4 100644 --- a/docs/examples/opencensus-exporter-tracer/README.rst +++ b/docs/examples/opencensus-exporter-tracer/README.rst @@ -1,5 +1,5 @@ -OpenTelemetry Collector Tracer OpenCensus Exporter Example -========================================================== +OpenCensus Exporter +=================== This example shows how to use the OpenCensus Exporter to export traces to the OpenTelemetry collector. diff --git a/docs/examples/opentracing/README.rst b/docs/examples/opentracing/README.rst index da9c70e43b8..0bf5f8dca3d 100644 --- a/docs/examples/opentracing/README.rst +++ b/docs/examples/opentracing/README.rst @@ -1,5 +1,5 @@ -OpenTracing Shim Example -========================== +OpenTracing Shim +================ This example shows how to use the :doc:`opentelemetry-opentracing-shim package <../../shim/opentracing_shim/opentracing_shim>` diff --git a/docs/exporter/jaeger/jaeger.rst b/docs/exporter/jaeger/jaeger.rst index 5a49f72b5c8..1fc02948d8d 100644 --- a/docs/exporter/jaeger/jaeger.rst +++ b/docs/exporter/jaeger/jaeger.rst @@ -1,4 +1,4 @@ -Opentelemetry Jaeger Exporters +OpenTelemetry Jaeger Exporters ============================== .. automodule:: opentelemetry.exporter.jaeger diff --git a/docs/exporter/otlp/otlp.rst b/docs/exporter/otlp/otlp.rst index e4bfdd07a1d..471f2935fb7 100644 --- a/docs/exporter/otlp/otlp.rst +++ b/docs/exporter/otlp/otlp.rst @@ -1,4 +1,4 @@ -Opentelemetry OTLP Exporters +OpenTelemetry OTLP Exporters ============================ .. automodule:: opentelemetry.exporter.otlp diff --git a/docs/getting_started/otlpcollector_example.py b/docs/getting_started/otlpcollector_example.py index 48c0d32a594..71f9ed97541 100644 --- a/docs/getting_started/otlpcollector_example.py +++ b/docs/getting_started/otlpcollector_example.py @@ -24,7 +24,7 @@ span_exporter = OTLPSpanExporter( # optional - # endpoint:="myCollectorURL:4317", + # endpoint="myCollectorURL:4317", # credentials=ChannelCredentials(credentials), # headers=(("metadata", "metadata")), ) diff --git a/docs/index.rst b/docs/index.rst index 42969c058f5..fe1b2a85388 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,7 +72,7 @@ install .. toctree:: :maxdepth: 1 - :caption: OpenTelemetry Python Packages + :caption: Core Packages :name: packages api/api @@ -80,7 +80,7 @@ install .. toctree:: :maxdepth: 2 - :caption: OpenTelemetry Exporters + :caption: Exporters :name: exporters :glob: @@ -88,7 +88,7 @@ install .. toctree:: :maxdepth: 2 - :caption: OpenTelemetry Shims + :caption: Shims :name: Shims :glob: @@ -96,7 +96,7 @@ install .. toctree:: :maxdepth: 1 - :caption: OpenTelemetry Python Performance + :caption: Performance :name: performance-tests :glob: diff --git a/opentelemetry-api/src/opentelemetry/util/_time.py b/opentelemetry-api/src/opentelemetry/util/_time.py index aa61bc02aa4..0099d3dbb5c 100644 --- a/opentelemetry-api/src/opentelemetry/util/_time.py +++ b/opentelemetry-api/src/opentelemetry/util/_time.py @@ -18,7 +18,7 @@ if version_info.minor < 7: getLogger(__name__).warning( # pylint: disable=logging-not-lazy "You are using Python 3.%s. This version does not support timestamps " - "with nanosecond precision and the Opentelemetry SDK will use " + "with nanosecond precision and the OpenTelemetry SDK will use " "millisecond precision instead. Please refer to PEP 546 for more " "information. Please upgrade to Python 3.7 or newer to use nanosecond " "precision." % version_info.minor diff --git a/opentelemetry-distro/README.rst b/opentelemetry-distro/README.rst index 4189131fc26..80952839104 100644 --- a/opentelemetry-distro/README.rst +++ b/opentelemetry-distro/README.rst @@ -14,9 +14,10 @@ Installation pip install opentelemetry-distro -This package provides entrypoints to configure OpenTelemetry +This package provides entrypoints to configure OpenTelemetry. References ---------- * `OpenTelemetry Project `_ +* `Example using opentelemetry-distro `_