From 253d73c46376fe0dbe24fa6c14405d79c478b4a1 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Wed, 2 Mar 2022 03:35:33 -0800 Subject: [PATCH] Normalize line lengths in python docs (#1182) --- .../en/docs/instrumentation/python/_index.md | 26 ++-- .../docs/instrumentation/python/automatic.md | 13 +- .../en/docs/instrumentation/python/distro.md | 3 +- .../instrumentation/python/getting-started.md | 127 +++++++++++------- 4 files changed, 109 insertions(+), 60 deletions(-) diff --git a/content/en/docs/instrumentation/python/_index.md b/content/en/docs/instrumentation/python/_index.md index 161fb0215..e230a3397 100644 --- a/content/en/docs/instrumentation/python/_index.md +++ b/content/en/docs/instrumentation/python/_index.md @@ -28,7 +28,8 @@ is as follows: [api/m]: https://opentelemetry-python.readthedocs.io/en/stable/api/metrics.html [api/t]: https://opentelemetry-python.readthedocs.io/en/stable/api/trace.html -[Experimental]: /docs/reference/specification/versioning-and-stability/#experimental +[Experimental]: + /docs/reference/specification/versioning-and-stability/#experimental [sdk/l]: https://opentelemetry-python.readthedocs.io/en/stable/sdk/logs.html [sdk/m]: https://opentelemetry-python.readthedocs.io/en/stable/sdk/metrics.html [sdk/t]: https://opentelemetry-python.readthedocs.io/en/stable/sdk/trace.html @@ -45,18 +46,23 @@ $ pip install opentelemetry-api $ pip install opentelemetry-sdk ``` -In addition, there are several extension packages which can be installed separately as: +In addition, there are several extension packages which can be installed +separately as: ```console $ pip install opentelemetry-exporter-{exporter} $ pip install opentelemetry-instrumentation-{instrumentation} ``` -These are for exporter and instrumentation packages respectively. -The Jaeger, Zipkin, OTLP and OpenCensus Exporters can be found in the [exporter](https://github.com/open-telemetry/opentelemetry-python/blob/main/exporter/) -directory of the repository. Instrumentations and additional exporters can be found in the -[Contrib repo instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation) -and [Contrib repo exporter](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/exporter) directories. +These are for exporter and instrumentation packages respectively. The Jaeger, +Zipkin, OTLP and OpenCensus Exporters can be found in the +[exporter](https://github.com/open-telemetry/opentelemetry-python/blob/main/exporter/) +directory of the repository. Instrumentations and additional exporters can be +found in the [Contrib repo +instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation) +and [Contrib repo +exporter](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/exporter) +directories. ## Extensions @@ -85,6 +91,8 @@ $ pip install -e ./opentelemetry-sdk - [Performance benchmarks][] [API reference]: https://opentelemetry-python.readthedocs.io/en/stable/ -[Contrib repository]: https://github.com/open-telemetry/opentelemetry-python-contrib +[Contrib repository]: + https://github.com/open-telemetry/opentelemetry-python-contrib [Examples]: https://opentelemetry-python.readthedocs.io/en/stable/examples/ -[Performance benchmarks]: https://open-telemetry.github.io/opentelemetry-python/benchmarks/ +[Performance benchmarks]: + https://open-telemetry.github.io/opentelemetry-python/benchmarks/ diff --git a/content/en/docs/instrumentation/python/automatic.md b/content/en/docs/instrumentation/python/automatic.md index 77c4de957..2303799e3 100644 --- a/content/en/docs/instrumentation/python/automatic.md +++ b/content/en/docs/instrumentation/python/automatic.md @@ -208,8 +208,8 @@ example: } ``` -You can see that both outputs are the same because automatic instrumentation does -exactly what manual instrumentation does. +You can see that both outputs are the same because automatic instrumentation +does exactly what manual instrumentation does. ### Instrumentation while debugging @@ -229,6 +229,9 @@ if __name__ == "__main__": app.run(port=8082, debug=True, use_reloader=False) ``` -[distro]: https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/distro -[OpenTracing example]: https://github.com/yurishkuro/opentracing-tutorial/tree/master/python -[source files]: https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/auto-instrumentation +[distro]: + https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/distro +[OpenTracing example]: + https://github.com/yurishkuro/opentracing-tutorial/tree/master/python +[source files]: + https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/auto-instrumentation diff --git a/content/en/docs/instrumentation/python/distro.md b/content/en/docs/instrumentation/python/distro.md index 8844c8ec4..341b0303e 100644 --- a/content/en/docs/instrumentation/python/distro.md +++ b/content/en/docs/instrumentation/python/distro.md @@ -28,7 +28,8 @@ collector, installing the package will setup all the required entry points. $ pip install opentelemetry-distro[otlp] opentelemetry-instrumentation ``` -Start the Collector locally to see data being exported. Write the following file: +Start the Collector locally to see data being exported. Write the following +file: ```yaml # /tmp/otel-collector-config.yaml diff --git a/content/en/docs/instrumentation/python/getting-started.md b/content/en/docs/instrumentation/python/getting-started.md index 0826f4671..ed865903e 100644 --- a/content/en/docs/instrumentation/python/getting-started.md +++ b/content/en/docs/instrumentation/python/getting-started.md @@ -4,9 +4,11 @@ weight: 1 code_block_from__path_base: content-modules/opentelemetry-python/docs/getting_started --- -This guide walks you through instrumenting a Python application with `opentelemetry-python`. +This guide walks you through instrumenting a Python application with +`opentelemetry-python`. -For more elaborate examples, see [examples](https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/). +For more elaborate examples, see +[examples](https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples/). ## Hello world: emit a trace to your console @@ -17,18 +19,21 @@ pip install opentelemetry-api pip install opentelemetry-sdk ``` -The API package provides the interfaces required by the application owner, as well -as some helper logic to load implementations. +The API package provides the interfaces required by the application owner, as +well as some helper logic to load implementations. -The SDK provides an implementation of those interfaces. The implementation is designed to be generic and extensible enough -that in many situations, the SDK is sufficient. +The SDK provides an implementation of those interfaces. The implementation is +designed to be generic and extensible enough that in many situations, the SDK is +sufficient. -Once installed, you can use the packages to emit spans from your application. A span -represents an action within your application that you want to instrument, such as an HTTP request -or a database call. Once instrumented, you can extract helpful information such as -how long the action took. You can also add arbitrary attributes to the span that provide more insight for debugging. +Once installed, you can use the packages to emit spans from your application. A +span represents an action within your application that you want to instrument, +such as an HTTP request or a database call. Once instrumented, you can extract +helpful information such as how long the action took. You can also add arbitrary +attributes to the span that provide more insight for debugging. -The following example script emits a trace containing three named spans: “foo”, “bar”, and “baz”: +The following example script emits a trace containing three named spans: “foo”, +“bar”, and “baz”: {{% code_block_from file="tracing_example.py" from="15" %}} @@ -92,20 +97,28 @@ $ python tracing_example.py } ``` -Each span typically represents a single operation or unit of work. -Spans can be nested, and have a parent-child relationship with other spans. -While a given span is active, newly-created spans inherit the active span’s trace ID, options, and other attributes of its context. -A span without a parent is called the root span, and a trace is comprised of one root span and its descendants. +Each span typically represents a single operation or unit of work. Spans can be +nested, and have a parent-child relationship with other spans. While a given +span is active, newly-created spans inherit the active span’s trace ID, options, +and other attributes of its context. A span without a parent is called the root +span, and a trace is comprised of one root span and its descendants. -In this example, the OpenTelemetry Python library creates one trace containing three spans and prints it to STDOUT. +In this example, the OpenTelemetry Python library creates one trace containing +three spans and prints it to STDOUT. ## Configure exporters to emit spans elsewhere -The previous example does emit information about all spans, but the output is a bit hard to read. -In most cases, you can instead *export* this data to an application performance monitoring backend to be visualized and queried. -It’s also common to aggregate span and trace information from multiple services into a single database, so that actions requiring multiple services can still all be visualized together. +The previous example does emit information about all spans, but the output is a +bit hard to read. In most cases, you can instead *export* this data to an +application performance monitoring backend to be visualized and queried. It’s +also common to aggregate span and trace information from multiple services into +a single database, so that actions requiring multiple services can still all be +visualized together. -This concept of aggregating span and trace information is known as distributed tracing. One such distributed tracing backend is known as Jaeger. The Jaeger project provides an all-in-one Docker container with a UI, database, and consumer. +This concept of aggregating span and trace information is known as distributed +tracing. One such distributed tracing backend is known as Jaeger. The Jaeger +project provides an all-in-one Docker container with a UI, database, and +consumer. Run the following command to start Jaeger: @@ -113,16 +126,20 @@ Run the following command to start Jaeger: docker run -p 16686:16686 -p 6831:6831/udp jaegertracing/all-in-one ``` -This command starts Jaeger locally on port 16686 and exposes the Jaeger thrift agent on port 6831. You can visit Jaeger at [http://localhost:16686](http://localhost:16686). +This command starts Jaeger locally on port 16686 and exposes the Jaeger thrift +agent on port 6831. You can visit Jaeger at +[http://localhost:16686](http://localhost:16686). -After you spin up the backend, your application needs to export traces to this system. Although `opentelemetry-sdk` doesn’t provide an exporter -for Jaeger, you can install it as a separate package with the following command: +After you spin up the backend, your application needs to export traces to this +system. Although `opentelemetry-sdk` doesn’t provide an exporter for Jaeger, you +can install it as a separate package with the following command: ```sh pip install opentelemetry-exporter-jaeger ``` -After you install the exporter, update your code to import the Jaeger exporter and use that instead: +After you install the exporter, update your code to import the Jaeger exporter +and use that instead: {{% code_block_from file="jaeger_example.py" from="15" %}} @@ -132,11 +149,14 @@ Finally, run the Python script: python jaeger_example.py ``` -You can then visit the Jaeger UI, see your service under “services”, and find your traces! +You can then visit the Jaeger UI, see your service under “services”, and find +your traces! ## Instrumentation example with Flask -While the example in the previous section is great, it’s very manual. The following are common actions you might want to track and include as part of your distributed tracing. +While the example in the previous section is great, it’s very manual. The +following are common actions you might want to track and include as part of your +distributed tracing. * HTTP responses from web services @@ -147,21 +167,28 @@ While the example in the previous section is great, it’s very manual. The foll * Database calls -To track these common actions, OpenTelemetry has the concept of instrumentations. Instrumentations are packages designed to interface -with a specific framework or library, such as Flask and psycopg2. You can find a list of the currently curated extension packages in the [Contrib repository](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation). +To track these common actions, OpenTelemetry has the concept of +instrumentations. Instrumentations are packages designed to interface with a +specific framework or library, such as Flask and psycopg2. You can find a list +of the currently curated extension packages in the [Contrib +repository](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation). -Instrument a basic Flask application that uses the requests library to send HTTP requests. First, install the instrumentation packages themselves: +Instrument a basic Flask application that uses the requests library to send HTTP +requests. First, install the instrumentation packages themselves: ```sh pip install opentelemetry-instrumentation-flask pip install opentelemetry-instrumentation-requests ``` -The following small Flask application sends an HTTP request and also activates each instrumentation during its initialization: +The following small Flask application sends an HTTP request and also activates +each instrumentation during its initialization: {{% code_block_from file="flask_example.py" from="15" %}} -Now run the script, hit the root URL ([http://localhost:5000/](http://localhost:5000/)) a few times, and watch your spans be emitted! +Now run the script, hit the root URL +([http://localhost:5000/](http://localhost:5000/)) a few times, and watch your +spans be emitted! ```sh python flask_example.py @@ -169,22 +196,27 @@ python flask_example.py ## Configure Your HTTP propagator (b3, Baggage) -A major feature of distributed tracing is the ability to correlate a trace across -multiple services. However, those services need to propagate information about a -trace from one service to the other. +A major feature of distributed tracing is the ability to correlate a trace +across multiple services. However, those services need to propagate information +about a trace from one service to the other. -To enable this propagation, OpenTelemetry has the concept of [propagators]({{< relref "/docs/reference/specification/context/api-propagators" >}}), -which provide a common method to encode and decode span information from a request and response, respectively. +To enable this propagation, OpenTelemetry has the concept of [propagators]({{< +relref "/docs/reference/specification/context/api-propagators" >}}), which +provide a common method to encode and decode span information from a request and +response, respectively. -By default, `opentelemetry-python` is configured to use the [W3C Trace Context](https://www.w3.org/TR/trace-context/) -and [W3C Baggage](https://www.w3.org/TR/baggage/) HTTP headers for HTTP requests, but you can configure it to leverage different propagators. Here’s -an example using Zipkin’s [b3 propagation](https://github.com/openzipkin/b3-propagation): +By default, `opentelemetry-python` is configured to use the [W3C Trace +Context](https://www.w3.org/TR/trace-context/) and [W3C +Baggage](https://www.w3.org/TR/baggage/) HTTP headers for HTTP requests, but you +can configure it to leverage different propagators. Here’s an example using +Zipkin’s [b3 propagation](https://github.com/openzipkin/b3-propagation): ```sh pip install opentelemetry-propagator-b3 ``` -Following the installation of the package containing the b3 propagator, configure the propagator as follows: +Following the installation of the package containing the b3 propagator, +configure the propagator as follows: ```python from opentelemetry.propagate import set_global_textmap @@ -195,18 +227,23 @@ set_global_textmap(B3Format()) ## Use the OpenTelemetry Collector for traces -Although it’s possible to directly export your telemetry data to specific backends, you might have more complex use cases such as the following: +Although it’s possible to directly export your telemetry data to specific +backends, you might have more complex use cases such as the following: -* A single telemetry sink shared by multiple services, to reduce overhead of switching exporters. +* A single telemetry sink shared by multiple services, to reduce overhead of + switching exporters. * Aggregating traces across multiple services, running on multiple hosts. -To enable a broad range of aggregation strategies, OpenTelemetry provides the [opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector). -The Collector is a flexible application that can consume trace data and export to multiple other backends, including to another instance of the Collector. +To enable a broad range of aggregation strategies, OpenTelemetry provides the +[opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector). +The Collector is a flexible application that can consume trace data and export +to multiple other backends, including to another instance of the Collector. -Start the Collector locally to see how the Collector works in practice. Write the following file: +Start the Collector locally to see how the Collector works in practice. Write +the following file: ```yaml # /tmp/otel-collector-config.yaml