From ca36ff84baec83237c0e0d5ca3ecd7461b55caf4 Mon Sep 17 00:00:00 2001 From: Xuan Wang Date: Fri, 23 Feb 2024 13:23:48 -0800 Subject: [PATCH] [Python o11y] Fix readme (#35988) Fix `readme.rst`. Tested locally by running `python setup.py doc`, no more errors from observability. Only error is related to grpc_status: ``` WARNING: autodoc: failed to import module 'rpc_status' from module 'grpc_status'; the following exception was raised: cannot import name 'status_pb2' from 'google.rpc' (unknown location) ``` Closes #35988 PiperOrigin-RevId: 609820414 --- doc/python/sphinx/grpc_observability.rst | 2 +- doc/python/sphinx/index.rst | 1 + src/python/grpcio/grpc/_observability.py | 54 +++++++++++----------- src/python/grpcio_observability/README.rst | 2 +- 4 files changed, 30 insertions(+), 29 deletions(-) diff --git a/doc/python/sphinx/grpc_observability.rst b/doc/python/sphinx/grpc_observability.rst index c0316f5d4f7..b79746d8fad 100644 --- a/doc/python/sphinx/grpc_observability.rst +++ b/doc/python/sphinx/grpc_observability.rst @@ -1,5 +1,5 @@ gRPC Python Observability -==================== +========================= Module Contents --------------- diff --git a/doc/python/sphinx/index.rst b/doc/python/sphinx/index.rst index 2bdd60b826d..04f190f1116 100644 --- a/doc/python/sphinx/index.rst +++ b/doc/python/sphinx/index.rst @@ -18,6 +18,7 @@ API Reference grpc_reflection grpc_status grpc_testing + grpc_observability glossary diff --git a/src/python/grpcio/grpc/_observability.py b/src/python/grpcio/grpc/_observability.py index 8bbbcd2bcea..3b365481922 100644 --- a/src/python/grpcio/grpc/_observability.py +++ b/src/python/grpcio/grpc/_observability.py @@ -74,11 +74,11 @@ class ObservabilityPlugin( interface and wrapped in a PyCapsule using `client_call_tracer` as name. Args: - method_name: The method name of the call in byte format. - target: The channel target of the call in byte format. + method_name: The method name of the call in byte format. + target: The channel target of the call in byte format. Returns: - A PyCapsule which stores a ClientCallTracer object. + A PyCapsule which stores a ClientCallTracer object. """ raise NotImplementedError() @@ -95,7 +95,7 @@ class ObservabilityPlugin( interface and wrapped in a PyCapsule using `client_call_tracer` as name. Args: - client_call_tracer: A PyCapsule which stores a ClientCallTracer object. + client_call_tracer: A PyCapsule which stores a ClientCallTracer object. """ raise NotImplementedError() @@ -111,12 +111,12 @@ class ObservabilityPlugin( This method can be used to propagate census context. Args: - trace_id: The identifier for the trace associated with the span as a - 32-character hexadecimal encoded string, - e.g. 26ed0036f2eff2b7317bccce3e28d01f - span_id: The identifier for the span as a 16-character hexadecimal encoded - string. e.g. 113ec879e62583bc - is_sampled: A bool indicates whether the span is sampled. + trace_id: The identifier for the trace associated with the span as a + 32-character hexadecimal encoded string, + e.g. 26ed0036f2eff2b7317bccce3e28d01f + span_id: The identifier for the span as a 16-character hexadecimal encoded + string. e.g. 113ec879e62583bc + is_sampled: A bool indicates whether the span is sampled. """ raise NotImplementedError() @@ -135,7 +135,7 @@ class ObservabilityPlugin( using `server_call_tracer_factory` as name. Returns: - A PyCapsule which stores a ServerCallTracerFactory object. + A PyCapsule which stores a ServerCallTracerFactory object. """ raise NotImplementedError() @@ -149,12 +149,12 @@ class ObservabilityPlugin( called at the end of each RPC. Args: - method: The fully-qualified name of the RPC method being invoked. - target: The target name of the RPC method being invoked. - rpc_latency: The latency for the RPC in seconds, equals to the time between - when the client invokes the RPC and when the client receives the status. - status_code: An element of grpc.StatusCode in string format representing the - final status for the RPC. + method: The fully-qualified name of the RPC method being invoked. + target: The target name of the RPC method being invoked. + rpc_latency: The latency for the RPC in seconds, equals to the time between + when the client invokes the RPC and when the client receives the status. + status_code: An element of grpc.StatusCode in string format representing the + final status for the RPC. """ raise NotImplementedError() @@ -162,7 +162,7 @@ class ObservabilityPlugin( """Enable or disable tracing. Args: - enable: A bool indicates whether tracing should be enabled. + enable: A bool indicates whether tracing should be enabled. """ self._tracing_enabled = enable @@ -170,7 +170,7 @@ class ObservabilityPlugin( """Enable or disable stats(metrics). Args: - enable: A bool indicates whether stats should be enabled. + enable: A bool indicates whether stats should be enabled. """ self._stats_enabled = enable @@ -192,7 +192,7 @@ def get_plugin() -> Generator[Optional[ObservabilityPlugin], None, None]: """Get the ObservabilityPlugin in _observability module. Returns: - The ObservabilityPlugin currently registered with the _observability + The ObservabilityPlugin currently registered with the _observability module. Or None if no plugin exists at the time of calling this method. """ with _plugin_lock: @@ -203,11 +203,11 @@ def set_plugin(observability_plugin: Optional[ObservabilityPlugin]) -> None: """Save ObservabilityPlugin to _observability module. Args: - observability_plugin: The ObservabilityPlugin to save. + observability_plugin: The ObservabilityPlugin to save. Raises: ValueError: If an ObservabilityPlugin was already registered at the - time of calling this method. + time of calling this method. """ global _OBSERVABILITY_PLUGIN # pylint: disable=global-statement with _plugin_lock: @@ -223,11 +223,11 @@ def observability_init(observability_plugin: ObservabilityPlugin) -> None: channels/servers are built. Args: - observability_plugin: The ObservabilityPlugin to use. + observability_plugin: The ObservabilityPlugin to use. Raises: ValueError: If an ObservabilityPlugin was already registered at the - time of calling this method. + time of calling this method. """ set_plugin(observability_plugin) try: @@ -256,7 +256,7 @@ def delete_call_tracer(client_call_tracer_capsule: Any) -> None: interface and wrapped in a PyCapsule using `client_call_tracer` as the name. Args: - client_call_tracer_capsule: A PyCapsule which stores a ClientCallTracer object. + client_call_tracer_capsule: A PyCapsule which stores a ClientCallTracer object. """ with get_plugin() as plugin: if not (plugin and plugin.observability_enabled): @@ -270,8 +270,8 @@ def maybe_record_rpc_latency(state: "_channel._RPCState") -> None: This method will be called at the end of each RPC. Args: - state: a grpc._channel._RPCState object which contains the stats related to the - RPC. + state: a grpc._channel._RPCState object which contains the stats related to the + RPC. """ # TODO(xuanwn): use channel args to exclude those metrics. for exclude_prefix in _SERVICES_TO_EXCLUDE: diff --git a/src/python/grpcio_observability/README.rst b/src/python/grpcio_observability/README.rst index 0e5df12528b..3db863b30e3 100644 --- a/src/python/grpcio_observability/README.rst +++ b/src/python/grpcio_observability/README.rst @@ -57,7 +57,7 @@ GCC-like stuff, but you may end up having a bad time. Dependencies -------------------------- +------------ gRPC Python Observability Depends on the following packages: ::