1gRPC Python Observability 2========================= 3 4Package for gRPC Python Observability. 5 6More details can be found in `OpenTelemetry Metrics gRFC <https://github.com/grpc/proposal/blob/master/A66-otel-stats.md#opentelemetry-metrics>`_. 7 8How gRPC Python Observability Works 9----------------------------------- 10 11gRPC Python is a wrapper layer built upon the gRPC Core (written in C/C++). Most of telemetry data 12is collected at core layer and then exported to Python layer. To optimize performance and reduce 13the overhead of acquiring the GIL too frequently, telemetry data is initially cached at the Core layer 14and then exported to the Python layer in batches. 15 16Note that while this approach enhances efficiency, it will introduce a slight delay between the 17time the data is collected and the time it becomes available through Python exporters. 18 19 20Supported Python Versions 21------------------------- 22Python >= 3.7 23 24Installation 25------------ 26 27Currently gRPC Python Observability is **only available for Linux**. 28 29Installing From PyPI 30~~~~~~~~~~~~~~~~~~~~ 31 32:: 33 34 $ pip install grpcio-observability 35 36 37Installing From Source 38~~~~~~~~~~~~~~~~~~~~~~ 39 40Building from source requires that you have the Python headers (usually a 41package named :code:`python-dev`) and Cython installed. It further requires a 42GCC-like compiler to go smoothly; you can probably get it to work without 43GCC-like stuff, but you may end up having a bad time. 44 45:: 46 47 $ export REPO_ROOT=grpc # REPO_ROOT can be any directory of your choice 48 $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $REPO_ROOT 49 $ cd $REPO_ROOT 50 $ git submodule update --init 51 52 $ cd src/python/grpcio_observability 53 $ python -m make_grpcio_observability 54 55 # For the next command do `sudo pip install` if you get permission-denied errors 56 $ GRPC_PYTHON_BUILD_WITH_CYTHON=1 pip install . 57 58 59Dependencies 60------------ 61gRPC Python Observability Depends on the following packages: 62 63:: 64 65 grpcio 66 opentelemetry-api==1.21.0 67 68 69Usage 70----- 71 72You can find example usage in `Python example folder <https://github.com/grpc/grpc/tree/master/examples/python/observability>`_. 73 74We also provide several environment variables to help you optimize gRPC python observability for your particular use. 75 761. GRPC_PYTHON_CENSUS_EXPORT_BATCH_INTERVAL 77 * This controls how frequently telemetry data collected within gRPC Core is sent to Python layer. 78 * Default value is 0.5 (Seconds). 79 802. GRPC_PYTHON_CENSUS_MAX_EXPORT_BUFFER_SIZE 81 * This controls the maximum number of telemetry data items that can be held in the buffer within gRPC Core before they are sent to Python. 82 * Default value is 10,000. 83 843. GRPC_PYTHON_CENSUS_EXPORT_THRESHOLD 85 * This setting acts as a trigger: When the buffer in gRPC Core reaches a certain percentage of its capacity, the telemetry data is sent to Python. 86 * Default value is 0.7 (Which means buffer will start export when it's 70% full). 87 884. GRPC_PYTHON_CENSUS_EXPORT_THREAD_TIMEOUT 89 * This controls the maximum time allowed for the exporting thread (responsible for sending data to Python) to complete. 90 * Main thread will terminate the exporting thread after this timeout. 91 * Default value is 10 (Seconds). 92