grpcio-observability 1.73.1__tar.gz → 1.74.0rc1__tar.gz

grpcio_observability-1.74.0rc1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.1
+Name: grpcio-observability
+Version: 1.74.0rc1
+Summary: gRPC Python observability package
+Home-page: https://grpc.io
+Author: The gRPC Authors
+Author-email: grpc-io@googlegroups.com
+License: Apache License 2.0
+Project-URL: Source Code, https://github.com/grpc/grpc/tree/master/src/python/grpcio_observability
+Project-URL: Bug Tracker, https://github.com/grpc/grpc/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: grpcio==1.74.0rc1
+Requires-Dist: setuptools>=59.6.0
+Requires-Dist: opentelemetry-api>=1.21.0
+
+gRPC Python Observability
+=========================
+
+Package for gRPC Python Observability.
+
+More details can be found in `OpenTelemetry Metrics gRFC <https://github.com/grpc/proposal/blob/master/A66-otel-stats.md#opentelemetry-metrics>`_.
+
+How gRPC Python Observability Works
+-----------------------------------
+
+gRPC Python is a wrapper layer built upon the gRPC Core (written in C/C++). Most of telemetry data
+is collected at core layer and then exported to Python layer. To optimize performance and reduce
+the overhead of acquiring the GIL too frequently, telemetry data is initially cached at the Core layer
+and then exported to the Python layer in batches.
+
+Note that while this approach enhances efficiency, it will introduce a slight delay between the
+time the data is collected and the time it becomes available through Python exporters.
+
+
+
+Installation
+------------
+
+Currently gRPC Python Observability is **only available for Linux**.
+
+Installing From PyPI
+~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  $ pip install grpcio-observability
+
+
+Installing From Source
+~~~~~~~~~~~~~~~~~~~~~~
+
+Building from source requires that you have the Python headers (usually a
+package named :code:`python-dev`) and Cython installed. It further requires a
+GCC-like compiler to go smoothly; you can probably get it to work without
+GCC-like stuff, but you may end up having a bad time.
+
+::
+
+  $ export REPO_ROOT=grpc  # REPO_ROOT can be any directory of your choice
+  $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $REPO_ROOT
+  $ cd $REPO_ROOT
+  $ git submodule update --init
+
+  $ cd src/python/grpcio_observability
+  $ python -m make_grpcio_observability
+
+  # For the next command do `sudo pip install` if you get permission-denied errors
+  $ GRPC_PYTHON_BUILD_WITH_CYTHON=1 pip install .
+
+
+Dependencies
+------------
+gRPC Python Observability Depends on the following packages:
+
+::
+
+  grpcio
+  opentelemetry-api
+
+
+Usage
+-----
+
+You can find example usage in `Python example folder <https://github.com/grpc/grpc/tree/master/examples/python/observability>`_.
+
+We also provide several environment variables to help you optimize gRPC python observability for your particular use.
+
+1. GRPC_PYTHON_CENSUS_EXPORT_BATCH_INTERVAL
+    * This controls how frequently telemetry data collected within gRPC Core is sent to Python layer.
+    * Default value is 0.5 (Seconds).
+
+2. GRPC_PYTHON_CENSUS_MAX_EXPORT_BUFFER_SIZE
+    * 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.
+    * Default value is 10,000.
+
+3. GRPC_PYTHON_CENSUS_EXPORT_THRESHOLD
+    * 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.
+    * Default value is 0.7 (Which means buffer will start export when it's 70% full).
+
+4. GRPC_PYTHON_CENSUS_EXPORT_THREAD_TIMEOUT
+    * This controls the maximum time allowed for the exporting thread (responsible for sending data to Python) to complete.
+    * Main thread will terminate the exporting thread after this timeout.
+    * Default value is 10 (Seconds).