grpcio-observability 1.71.0__cp310-cp310-musllinux_1_1_aarch64.whl

grpc_observability/_open_telemetry_plugin.py

@@ -0,0 +1,171 @@
+# Copyright 2023 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import AnyStr, Callable, Dict, Iterable, List, Optional
+
+# pytype: disable=pyi-error
+from grpc_observability import _open_telemetry_observability
+from grpc_observability._observability import OptionalLabelType
+from opentelemetry.metrics import MeterProvider
+
+GRPC_METHOD_LABEL = "grpc.method"
+GRPC_TARGET_LABEL = "grpc.target"
+GRPC_CLIENT_METRIC_PREFIX = "grpc.client"
+GRPC_OTHER_LABEL_VALUE = "other"
+
+
+class OpenTelemetryLabelInjector:
+    """
+    An interface that allows you to add additional labels on the calls traced.
+    """
+
+    def get_labels_for_exchange(self) -> Dict[str, AnyStr]:
+        """
+        Get labels used for metadata exchange.
+
+        Returns:
+          A dict of labels, with a string as key representing label name, string or bytes
+        as value representing label value.
+        """
+        raise NotImplementedError()
+
+    def get_additional_labels(
+        self, include_exchange_labels: bool
+    ) -> Dict[str, str]:
+        """
+        Get additional labels added by this injector.
+
+        The return value from this method will be added directly to metric data.
+
+        Args:
+          include_exchange_labels: Whether to add additional metadata exchange related labels.
+
+        Returns:
+          A dict of labels.
+        """
+        raise NotImplementedError()
+
+    # pylint: disable=no-self-use
+    def deserialize_labels(
+        self, labels: Dict[str, AnyStr]
+    ) -> Dict[str, AnyStr]:
+        """
+        Deserialize the labels if required.
+
+        If this injector added labels for metadata exchange, this method will be called to
+        deserialize the exchanged labels.
+
+        For example, if this injector added xds_peer_metadata_label for exchange:
+
+            labels: {"labelA": b"valueA", "xds_peer_metadata_label": b"exchanged_bytes"}
+
+        This method should deserialize xds_peer_metadata_label and return labels as:
+
+            labels: {"labelA": b"valueA", "xds_label_A": "xds_label_A",
+                     "xds_label_B": "xds_label_B"}
+
+        Returns:
+          A dict of deserialized labels.
+        """
+        return labels
+
+
+class OpenTelemetryPluginOption:
+    """
+    An interface that allows you to add additional function to OpenTelemetryPlugin.
+    """
+
+
+# pylint: disable=no-self-use
+class OpenTelemetryPlugin:
+    """Describes a Plugin for OpenTelemetry observability."""
+
+    plugin_options: Iterable[OpenTelemetryPluginOption]
+    meter_provider: Optional[MeterProvider]
+    target_attribute_filter: Callable[[str], bool]
+    generic_method_attribute_filter: Callable[[str], bool]
+    _plugins: List[_open_telemetry_observability._OpenTelemetryPlugin]
+
+    def __init__(
+        self,
+        *,
+        plugin_options: Iterable[OpenTelemetryPluginOption] = [],
+        meter_provider: Optional[MeterProvider] = None,
+        target_attribute_filter: Optional[Callable[[str], bool]] = None,
+        generic_method_attribute_filter: Optional[Callable[[str], bool]] = None,
+    ):
+        """
+        Args:
+          plugin_options: An Iterable of OpenTelemetryPluginOption which will be
+        enabled for this OpenTelemetryPlugin.
+          meter_provider: A MeterProvider which will be used to collect telemetry data,
+        or None which means no metrics will be collected.
+          target_attribute_filter: [DEPRECATED] This attribute is deprecated and should
+        not be used.
+        Once provided, this will be called per channel to decide whether to record the
+        target attribute on client or to replace it with "other".
+        This helps reduce the cardinality on metrics in cases where many channels
+        are created with different targets in the same binary (which might happen
+        for example, if the channel target string uses IP addresses directly).
+        Return True means the original target string will be used, False means target string
+        will be replaced with "other".
+          generic_method_attribute_filter: Once provided, this will be called with a generic
+        method type to decide whether to record the method name or to replace it with
+        "other". Note that pre-registered methods will always be recorded no matter what
+        this function returns.
+        Return True means the original method name will be used, False means method name will
+        be replaced with "other".
+        """
+        self.plugin_options = plugin_options
+        self.meter_provider = meter_provider
+        self.target_attribute_filter = target_attribute_filter or (
+            lambda target: True
+        )
+        self.generic_method_attribute_filter = (
+            generic_method_attribute_filter or (lambda target: False)
+        )
+        self._plugins = [
+            _open_telemetry_observability._OpenTelemetryPlugin(self)
+        ]
+
+    def register_global(self) -> None:
+        """
+        Registers a global plugin that acts on all channels and servers running on the process.
+
+        Raises:
+            RuntimeError: If a global plugin was already registered.
+        """
+        _open_telemetry_observability.start_open_telemetry_observability(
+            plugins=self._plugins
+        )
+
+    def deregister_global(self) -> None:
+        """
+        De-register the global plugin that acts on all channels and servers running on the process.
+
+        Raises:
+            RuntimeError: If no global plugin was registered.
+        """
+        _open_telemetry_observability.end_open_telemetry_observability()
+
+    def __enter__(self) -> None:
+        _open_telemetry_observability.start_open_telemetry_observability(
+            plugins=self._plugins
+        )
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        _open_telemetry_observability.end_open_telemetry_observability()
+
+    def _get_enabled_optional_labels(self) -> List[OptionalLabelType]:
+        return []

grpc_observability/_views.py

@@ -0,0 +1,287 @@
+# Copyright 2023 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Mapping
+
+from grpc_observability import _measures
+from grpc_observability._cyobservability import MetricsName
+from opencensus.stats import aggregation
+from opencensus.stats import view as view_module
+from opencensus.tags.tag_key import TagKey
+
+METRICS_NAME_TO_MEASURE = {
+    MetricsName.CLIENT_STARTED_RPCS: _measures.CLIENT_STARTED_RPCS_MEASURE,
+    MetricsName.CLIENT_ROUNDTRIP_LATENCY: _measures.CLIENT_ROUNDTRIP_LATENCY_MEASURE,
+    MetricsName.CLIENT_COMPLETED_RPC: _measures.CLIENT_COMPLETED_RPCS_MEASURE,
+    MetricsName.CLIENT_API_LATENCY: _measures.CLIENT_API_LATENCY_MEASURE,
+    MetricsName.CLIENT_SEND_BYTES_PER_RPC: _measures.CLIENT_SEND_BYTES_PER_RPC_MEASURE,
+    MetricsName.CLIENT_RECEIVED_BYTES_PER_RPC: _measures.CLIENT_RECEIVED_BYTES_PER_RPC_MEASURE,
+    MetricsName.SERVER_STARTED_RPCS: _measures.SERVER_STARTED_RPCS_MEASURE,
+    MetricsName.SERVER_SENT_BYTES_PER_RPC: _measures.SERVER_SENT_BYTES_PER_RPC_MEASURE,
+    MetricsName.SERVER_RECEIVED_BYTES_PER_RPC: _measures.SERVER_RECEIVED_BYTES_PER_RPC_MEASURE,
+    MetricsName.SERVER_SERVER_LATENCY: _measures.SERVER_SERVER_LATENCY_MEASURE,
+    MetricsName.SERVER_COMPLETED_RPC: _measures.SERVER_COMPLETED_RPCS_MEASURE,
+}
+
+
+# These measure definitions should be kept in sync across opencensus
+# implementations--see
+# https://github.com/census-instrumentation/opencensus-java/blob/master/contrib/grpc_metrics/src/main/java/io/opencensus/contrib/grpc/metrics/RpcMeasureConstants.java.
+def client_method_tag_key():
+    return TagKey("grpc_client_method")
+
+
+def client_status_tag_key():
+    return TagKey("grpc_client_status")
+
+
+def server_method_tag_key():
+    return TagKey("grpc_server_method")
+
+
+def server_status_tag_key():
+    return TagKey("server_status_tag_key")
+
+
+def count_distribution_aggregation() -> aggregation.DistributionAggregation:
+    exponential_boundaries = _get_exponential_boundaries(17, 1.0, 2.0)
+    return aggregation.DistributionAggregation(exponential_boundaries)
+
+
+def bytes_distribution_aggregation() -> aggregation.DistributionAggregation:
+    return aggregation.DistributionAggregation(
+        [
+            1024,
+            2048,
+            4096,
+            16384,
+            65536,
+            262144,
+            1048576,
+            4194304,
+            16777216,
+            67108864,
+            268435456,
+            1073741824,
+            4294967296,
+        ]
+    )
+
+
+def millis_distribution_aggregation() -> aggregation.DistributionAggregation:
+    return aggregation.DistributionAggregation(
+        [
+            0.01,
+            0.05,
+            0.1,
+            0.3,
+            0.6,
+            0.8,
+            1,
+            2,
+            3,
+            4,
+            5,
+            6,
+            8,
+            10,
+            13,
+            16,
+            20,
+            25,
+            30,
+            40,
+            50,
+            65,
+            80,
+            100,
+            130,
+            160,
+            200,
+            250,
+            300,
+            400,
+            500,
+            650,
+            800,
+            1000,
+            2000,
+            5000,
+            10000,
+            20000,
+            50000,
+            100000,
+        ]
+    )
+
+
+# Client
+def client_started_rpcs(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/started_rpcs",
+        "The count of RPCs ever received at the server, including RPCs"
+        + " that have not completed.",
+        [TagKey(key) for key in labels.keys()] + [client_method_tag_key()],
+        _measures.CLIENT_STARTED_RPCS_MEASURE,
+        aggregation.CountAggregation(),
+    )
+    return view
+
+
+def client_completed_rpcs(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/completed_rpcs",
+        "The total count of RPCs completed, for example, when a response"
+        + " is sent by the server.",
+        [TagKey(key) for key in labels.keys()]
+        + [client_method_tag_key(), client_status_tag_key()],
+        _measures.CLIENT_COMPLETED_RPCS_MEASURE,
+        aggregation.CountAggregation(),
+    )
+    return view
+
+
+def client_roundtrip_latency(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/roundtrip_latency",
+        "End-to-end time taken to complete an RPC attempt including the time"
+        + " it takes to pick a subchannel.",
+        [TagKey(key) for key in labels.keys()] + [client_method_tag_key()],
+        _measures.CLIENT_ROUNDTRIP_LATENCY_MEASURE,
+        millis_distribution_aggregation(),
+    )
+    return view
+
+
+def client_api_latency(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/api_latency",
+        "The total time taken by the gRPC library to complete an RPC from"
+        + " the application's perspective.",
+        [TagKey(key) for key in labels.keys()]
+        + [client_method_tag_key(), client_status_tag_key()],
+        _measures.CLIENT_API_LATENCY_MEASURE,
+        millis_distribution_aggregation(),
+    )
+    return view
+
+
+def client_sent_compressed_message_bytes_per_rpc(
+    labels: Mapping[str, str]
+) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/sent_compressed_message_bytes_per_rpc",
+        "The total bytes (compressed, not encrypted) sent across all"
+        + " request messages per RPC attempt.",
+        [TagKey(key) for key in labels.keys()]
+        + [client_method_tag_key(), client_status_tag_key()],
+        _measures.CLIENT_SEND_BYTES_PER_RPC_MEASURE,
+        bytes_distribution_aggregation(),
+    )
+    return view
+
+
+def client_received_compressed_message_bytes_per_rpc(
+    labels: Mapping[str, str]
+) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/client/received_compressed_message_bytes_per_rpc",
+        "The total bytes (compressed, not encrypted) received across"
+        + " all response messages per RPC attempt.",
+        [TagKey(key) for key in labels.keys()]
+        + [client_method_tag_key(), client_status_tag_key()],
+        _measures.CLIENT_RECEIVED_BYTES_PER_RPC_MEASURE,
+        bytes_distribution_aggregation(),
+    )
+    return view
+
+
+# Server
+def server_started_rpcs(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/server/started_rpcs",
+        "The count of RPCs ever received at the server, including RPCs"
+        + " that have not completed.",
+        [TagKey(key) for key in labels.keys()] + [server_method_tag_key()],
+        _measures.SERVER_STARTED_RPCS_MEASURE,
+        aggregation.CountAggregation(),
+    )
+    return view
+
+
+def server_completed_rpcs(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/server/completed_rpcs",
+        "The total count of RPCs completed, for example, when a response"
+        + " is sent by the server.",
+        [TagKey(key) for key in labels.keys()]
+        + [server_method_tag_key(), server_status_tag_key()],
+        _measures.SERVER_COMPLETED_RPCS_MEASURE,
+        aggregation.CountAggregation(),
+    )
+    return view
+
+
+def server_sent_compressed_message_bytes_per_rpc(
+    labels: Mapping[str, str]
+) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/server/sent_compressed_message_bytes_per_rpc",
+        "The total bytes (compressed not encrypted) sent across all response"
+        + " messages per RPC.",
+        [TagKey(key) for key in labels.keys()]
+        + [server_method_tag_key(), server_status_tag_key()],
+        _measures.SERVER_SENT_BYTES_PER_RPC_MEASURE,
+        bytes_distribution_aggregation(),
+    )
+    return view
+
+
+def server_received_compressed_message_bytes_per_rpc(
+    labels: Mapping[str, str]
+) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/server/received_compressed_message_bytes_per_rpc",
+        "The total bytes (compressed not encrypted) received across all"
+        + " request messages per RPC.",
+        [TagKey(key) for key in labels.keys()]
+        + [server_method_tag_key(), server_status_tag_key()],
+        _measures.SERVER_RECEIVED_BYTES_PER_RPC_MEASURE,
+        bytes_distribution_aggregation(),
+    )
+    return view
+
+
+def server_server_latency(labels: Mapping[str, str]) -> view_module.View:
+    view = view_module.View(
+        "grpc.io/server/server_latency",
+        "The total time taken by an RPC from server transport's"
+        + " (HTTP2 / inproc / cronet) perspective.",
+        [TagKey(key) for key in labels.keys()]
+        + [server_method_tag_key(), server_status_tag_key()],
+        _measures.SERVER_SERVER_LATENCY_MEASURE,
+        millis_distribution_aggregation(),
+    )
+    return view
+
+
+def _get_exponential_boundaries(
+    num_finite_buckets: int, scale: float, grrowth_factor: float
+) -> list:
+    boundaries = []
+    upper_bound = scale
+    for _ in range(num_finite_buckets):
+        boundaries.append(upper_bound)
+        upper_bound *= grrowth_factor
+    return boundaries