README.rst
1gRPC Python CSM Observability
2=============================
3
4Package for gRPC Python CSM Observability.
5
6
7Installation
8------------
9
10Currently gRPC Python CSM Observability is **only available for Linux**.
11
12Installing From PyPI
13~~~~~~~~~~~~~~~~~~~~
14
15::
16
17 $ pip install grpcio-csm-observability
18
19
20Installing From Source
21~~~~~~~~~~~~~~~~~~~~~~
22
23::
24
25 $ export REPO_ROOT=grpc # REPO_ROOT can be any directory of your choice
26 $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $REPO_ROOT
27 $ cd $REPO_ROOT
28 $ git submodule update --init
29
30 $ cd src/python/grpcio_csm_observability
31
32 # For the next command do `sudo pip install` if you get permission-denied errors
33 $ pip install .
34
35
36Dependencies
37------------
38gRPC Python CSM Observability Depends on the following packages:
39
40::
41
42 grpcio
43 grpcio-observability
44 opentelemetry-sdk
45
46
47Usage
48-----
49
50Example usage is similar to `the example here <https://github.com/grpc/grpc/tree/master/examples/python/observability>`_, instead of importing from ``grpc_observability``, you should import from ``grpc_csm_observability``:
51
52.. code-block:: python
53
54 import grpc_csm_observability
55
56 csm_otel_plugin = grpc_csm_observability.CsmOpenTelemetryPlugin(
57 meter_provider=provider
58 )
59
60
61We also provide several environment variables to help you optimize gRPC python observability for your particular use.
62
63* Note: The term "Census" here is just for historical backwards compatibility reasons and does not imply any dependencies.
64
651. GRPC_PYTHON_CENSUS_EXPORT_BATCH_INTERVAL
66 * This controls how frequently telemetry data collected within gRPC Core is sent to Python layer.
67 * Default value is 0.5 (Seconds).
68
692. GRPC_PYTHON_CENSUS_MAX_EXPORT_BUFFER_SIZE
70 * 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.
71 * Default value is 10,000.
72
733. GRPC_PYTHON_CENSUS_EXPORT_THRESHOLD
74 * 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.
75 * Default value is 0.7 (Which means buffer will start export when it's 70% full).
76
774. GRPC_PYTHON_CENSUS_EXPORT_THREAD_TIMEOUT
78 * This controls the maximum time allowed for the exporting thread (responsible for sending data to Python) to complete.
79 * Main thread will terminate the exporting thread after this timeout.
80 * Default value is 10 (Seconds).
81