feat grpc: add client QoS configuration validation

mvkab · mvkab · commit 1eac120e7c1d · 2025-12-11T14:59:19.000+03:00
Add validation for methods in client QoS config to catch typos and invalid configs early:

\- validate RPC path format (\`package.ServiceName/MethodName\`)

\- check method existence against service metadata

Add \`grpc\_client\_qos\_invalid\_configuration\` alert that fires on invalid methods and clears when config is fixed.
commit_hash:ceeecd02ed6fc69552fed8040f61767acc5bcbf9
diff --git a/.mapping.json b/.mapping.json
@@ -2340,6 +2340,7 @@
   "grpc/include/userver/ugrpc/client/impl/client_data.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/client_data.hpp",
   "grpc/include/userver/ugrpc/client/impl/client_data_accessor.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/client_data_accessor.hpp",
   "grpc/include/userver/ugrpc/client/impl/client_internals.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/client_internals.hpp",
+  "grpc/include/userver/ugrpc/client/impl/client_qos_errors_reporter.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/client_qos_errors_reporter.hpp",
   "grpc/include/userver/ugrpc/client/impl/codegen_declarations.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/codegen_declarations.hpp",
   "grpc/include/userver/ugrpc/client/impl/codegen_definitions.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/codegen_definitions.hpp",
   "grpc/include/userver/ugrpc/client/impl/compat/channel_arguments_builder.hpp":"taxi/uservices/userver/grpc/include/userver/ugrpc/client/impl/compat/channel_arguments_builder.hpp",
@@ -2485,6 +2486,9 @@
   "grpc/src/ugrpc/client/impl/client_factory_config.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_factory_config.cpp",
   "grpc/src/ugrpc/client/impl/client_factory_config.hpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_factory_config.hpp",
   "grpc/src/ugrpc/client/impl/client_qos.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_qos.cpp",
+  "grpc/src/ugrpc/client/impl/client_qos_errors_reporter.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_qos_errors_reporter.cpp",
+  "grpc/src/ugrpc/client/impl/client_qos_validation.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_qos_validation.cpp",
+  "grpc/src/ugrpc/client/impl/client_qos_validation.hpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/client_qos_validation.hpp",
   "grpc/src/ugrpc/client/impl/compat/channel_arguments_builder.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/compat/channel_arguments_builder.cpp",
   "grpc/src/ugrpc/client/impl/compat/retry_policy.cpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/compat/retry_policy.cpp",
   "grpc/src/ugrpc/client/impl/compat/retry_policy.hpp":"taxi/uservices/userver/grpc/src/ugrpc/client/impl/compat/retry_policy.hpp",
@@ -2605,6 +2609,7 @@
   "grpc/tests/client_factory_test.cpp":"taxi/uservices/userver/grpc/tests/client_factory_test.cpp",
   "grpc/tests/client_middleware_hooks_test.cpp":"taxi/uservices/userver/grpc/tests/client_middleware_hooks_test.cpp",
   "grpc/tests/client_qos_test.cpp":"taxi/uservices/userver/grpc/tests/client_qos_test.cpp",
+  "grpc/tests/client_qos_validation_test.cpp":"taxi/uservices/userver/grpc/tests/client_qos_validation_test.cpp",
   "grpc/tests/compat/channel_arguments_builder_test.cpp":"taxi/uservices/userver/grpc/tests/compat/channel_arguments_builder_test.cpp",
   "grpc/tests/congestion_control_test.cpp":"taxi/uservices/userver/grpc/tests/congestion_control_test.cpp",
   "grpc/tests/datetime_utils_test.cpp":"taxi/uservices/userver/grpc/tests/datetime_utils_test.cpp",
diff --git a/core/include/userver/components/statistics_storage.hpp b/core/include/userver/components/statistics_storage.hpp
@@ -47,6 +47,11 @@ class StatisticsStorage final : public RawComponentBase {
 
     utils::statistics::MetricsStoragePtr GetMetricsStorage() { return metrics_storage_; }
 
+    utils::statistics::MetricsStorage& GetMetricsStorageRef() {
+        UASSERT(metrics_storage_ != nullptr);
+        return *metrics_storage_;
+    }
+
     static yaml_config::Schema GetStaticConfigSchema();
 
 private:
diff --git a/grpc/functional_tests/metrics/tests/static/metrics_values.txt b/grpc/functional_tests/metrics/tests/static/metrics_values.txt
@@ -1,3 +1,4 @@
+alerts.grpc_client_qos_invalid_configuration:	GAUGE
 grpc.client.by-destination.abandoned-error: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService	RATE
 grpc.client.by-destination.active: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService	GAUGE
 grpc.client.by-destination.cancelled-by-deadline-propagation: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService	RATE
diff --git a/grpc/functional_tests/metrics/tests/test_metrics.py b/grpc/functional_tests/metrics/tests/test_metrics.py
@@ -16,8 +16,12 @@ def _normalize_metrics(metrics: str) -> str:
 def _drop_non_grpc_metrics(metrics: list[str]) -> list[str]:
     result = []
     for line in metrics:
-        if line.startswith(('grpc.server', 'grpc.client')):
-            result.append(line)
+        try:
+            path = line.split(':')[0]
+            if 'grpc' in path:
+                result.append(line)
+        except IndexError:
+            continue
 
     return result
 
diff --git a/grpc/include/userver/ugrpc/client/client_factory.hpp b/grpc/include/userver/ugrpc/client/client_factory.hpp
@@ -14,6 +14,7 @@
 #include <userver/ugrpc/client/client_settings.hpp>
 #include <userver/ugrpc/client/fwd.hpp>
 #include <userver/ugrpc/client/impl/client_internals.hpp>
+#include <userver/ugrpc/client/impl/client_qos_errors_reporter.hpp>
 #include <userver/ugrpc/client/middlewares/pipeline.hpp>
 #include <userver/ugrpc/impl/static_service_metadata.hpp>
 
@@ -58,6 +59,7 @@ class ClientFactory final {
         impl::MiddlewarePipelineCreator& middleware_pipeline_creator,
         ugrpc::impl::CompletionQueuePoolBase& completion_queues,
         ugrpc::impl::StatisticsStorage& statistics_storage,
+        utils::statistics::MetricsStorage& metrics_storage,
         testsuite::GrpcControl& testsuite_grpc,
         dynamic_config::Source config_source
     );
@@ -74,6 +76,7 @@ class ClientFactory final {
     impl::MiddlewarePipelineCreator& middleware_pipeline_creator_;
     ugrpc::impl::CompletionQueuePoolBase& completion_queues_;
     ugrpc::impl::StatisticsStorage& client_statistics_storage_;
+    impl::ClientQosErrorsReporter client_qos_errors_reporter_;
     const dynamic_config::Source config_source_;
     testsuite::GrpcControl& testsuite_grpc_;
 };
diff --git a/grpc/include/userver/ugrpc/client/impl/client_data.hpp b/grpc/include/userver/ugrpc/client/impl/client_data.hpp
@@ -16,6 +16,7 @@
 #include <userver/ugrpc/client/client_qos.hpp>
 #include <userver/ugrpc/client/impl/channel_argument_utils.hpp>
 #include <userver/ugrpc/client/impl/client_internals.hpp>
+#include <userver/ugrpc/client/impl/client_qos_errors_reporter.hpp>
 #include <userver/ugrpc/client/impl/compat/channel_arguments_builder.hpp>
 #include <userver/ugrpc/client/impl/stub_handle.hpp>
 #include <userver/ugrpc/client/impl/stub_state.hpp>
@@ -153,7 +154,12 @@ class ClientData final {
 
     template <typename Service>
     void OnConfigUpdate(const dynamic_config::Snapshot& config) {
-        auto client_qos = internals_.qos ? config[*internals_.qos] : ClientQos{};
+        const auto& client_qos = internals_.qos ? config[*internals_.qos] : ClientQos{};
+
+        if (metadata_.has_value() && internals_.qos) {
+            internals_.client_qos_error_reporter
+                .ValidateAndReportClientQosErrors(client_qos, internals_.qos->GetName(), *metadata_);
+        }
 
         std::string target = internals_.endpoint;
 
diff --git a/grpc/include/userver/ugrpc/client/impl/client_internals.hpp b/grpc/include/userver/ugrpc/client/impl/client_internals.hpp
@@ -13,6 +13,7 @@
 #include <userver/ugrpc/client/middlewares/fwd.hpp>
 #include <userver/ugrpc/client/proxy_settings.hpp>
 #include <userver/ugrpc/client/retry_config.hpp>
+#include <userver/utils/statistics/fwd.hpp>
 
 USERVER_NAMESPACE_BEGIN
 
@@ -23,13 +24,16 @@ class CompletionQueuePoolBase;
 
 namespace ugrpc::client::impl {
 
+class ClientQosErrorsReporter;
+
 /// Contains all non-code-generated dependencies for creating a gRPC client
 struct ClientInternals final {
     std::string client_name;
     std::string endpoint;
     Middlewares middlewares;
     ugrpc::impl::CompletionQueuePoolBase& completion_queues;
     ugrpc::impl::StatisticsStorage& statistics_storage;
+    ClientQosErrorsReporter& client_qos_error_reporter;
     dynamic_config::Source config_source;
     testsuite::GrpcControl& testsuite_grpc;
     const dynamic_config::Key<ClientQos>* qos{nullptr};
diff --git a/grpc/include/userver/ugrpc/client/impl/client_qos_errors_reporter.hpp b/grpc/include/userver/ugrpc/client/impl/client_qos_errors_reporter.hpp
@@ -0,0 +1,35 @@
+#pragma once
+
+#include <userver/ugrpc/impl/static_service_metadata.hpp>
+#include <userver/utils/statistics/metrics_storage.hpp>
+
+USERVER_NAMESPACE_BEGIN
+
+namespace ugrpc::client {
+struct ClientQos;
+}  // namespace ugrpc::client
+
+namespace ugrpc::client::impl {
+
+class ClientQosErrorsReporter final {
+public:
+    explicit ClientQosErrorsReporter(utils::statistics::MetricsStorage& metrics_storage);
+
+    /// @brief Validates client QOS configuration and synchronizes validity alert state.
+    /// @details Performs validation using @ref ValidateClientQosMethodsExistence and:
+    /// - Fires `grpc_client_qos_invalid_configuration` alert if errors are found
+    /// - Stops the alert if configuration is valid
+    /// Logs warnings for each detected issue.
+    void ValidateAndReportClientQosErrors(
+        const ClientQos& client_qos,
+        std::string_view config_name,
+        const ugrpc::impl::StaticServiceMetadata& metadata
+    );
+
+private:
+    utils::statistics::MetricsStorage& metrics_storage_;
+};
+
+}  // namespace ugrpc::client::impl
+
+USERVER_NAMESPACE_END
diff --git a/grpc/include/userver/ugrpc/tests/service.hpp b/grpc/include/userver/ugrpc/tests/service.hpp
@@ -11,6 +11,7 @@
 #include <userver/dynamic_config/storage_mock.hpp>
 #include <userver/dynamic_config/test_helpers.hpp>
 #include <userver/testsuite/grpc_control.hpp>
+#include <userver/utils/statistics/metrics_storage.hpp>
 #include <userver/utils/statistics/storage.hpp>
 
 #include <userver/ugrpc/client/client_factory.hpp>
@@ -92,6 +93,8 @@ class ServiceBase {
     server::ServiceConfig MakeServiceConfig();
 
     utils::statistics::Storage statistics_storage_;
+    utils::statistics::MetricsStorage metrics_storage_;
+    std::vector<utils::statistics::Entry> metrics_storage_registration_;
     dynamic_config::StorageMock config_storage_;
     std::optional<std::string> unix_socket_path_;
     server::Server server_;
diff --git a/grpc/include/userver/ugrpc/tests/standalone_client.hpp b/grpc/include/userver/ugrpc/tests/standalone_client.hpp
@@ -8,6 +8,7 @@
 #include <userver/dynamic_config/test_helpers.hpp>
 #include <userver/engine/io/sockaddr.hpp>
 #include <userver/testsuite/grpc_control.hpp>
+#include <userver/utils/statistics/metrics_storage.hpp>
 #include <userver/utils/statistics/storage.hpp>
 
 #include <userver/ugrpc/client/client_factory.hpp>
@@ -44,6 +45,8 @@ class StandaloneClientFactory final {
 
 private:
     utils::statistics::Storage statistics_storage_;
+    utils::statistics::MetricsStorage metrics_storage_;
+    std::vector<utils::statistics::Entry> metrics_storage_registration_;
     ugrpc::impl::StatisticsStorage
         client_statistics_storage_{statistics_storage_, ugrpc::impl::StatisticsDomain::kClient};
     dynamic_config::StorageMock config_storage_{dynamic_config::MakeDefaultStorage({})};
diff --git a/grpc/src/ugrpc/client/client_factory.cpp b/grpc/src/ugrpc/client/client_factory.cpp
@@ -15,6 +15,7 @@ ClientFactory::ClientFactory(
     impl::MiddlewarePipelineCreator& middleware_pipeline_creator,
     ugrpc::impl::CompletionQueuePoolBase& completion_queues,
     ugrpc::impl::StatisticsStorage& statistics_storage,
+    utils::statistics::MetricsStorage& metrics_storage,
     testsuite::GrpcControl& testsuite_grpc,
     dynamic_config::Source config_source
 )
@@ -23,6 +24,7 @@ ClientFactory::ClientFactory(
       middleware_pipeline_creator_(middleware_pipeline_creator),
       completion_queues_(completion_queues),
       client_statistics_storage_(statistics_storage),
+      client_qos_errors_reporter_(metrics_storage),
       config_source_(config_source),
       testsuite_grpc_(testsuite_grpc)
 {}
@@ -64,6 +66,7 @@ impl::ClientInternals ClientFactory::MakeClientInternals(
         std::move(middlewares),
         completion_queues_,
         client_statistics_storage_,
+        client_qos_errors_reporter_,
         config_source_,
         testsuite_grpc_,
         client_settings.client_qos,
diff --git a/grpc/src/ugrpc/client/client_factory_component.cpp b/grpc/src/ugrpc/client/client_factory_component.cpp
@@ -2,6 +2,7 @@
 
 #include <userver/components/component_config.hpp>
 #include <userver/components/component_context.hpp>
+#include <userver/components/statistics_storage.hpp>
 #include <userver/dynamic_config/storage/component.hpp>
 #include <userver/logging/log.hpp>
 #include <userver/storages/secdist/component.hpp>
@@ -73,6 +74,8 @@ ClientFactoryComponent::ClientFactoryComponent(
     : impl::MiddlewareRunnerComponentBase(config, context, MiddlewarePipelineComponent::kName) {
     auto& client_common_component = context.FindComponent<CommonComponent>();
 
+    auto& metrics_storage = context.FindComponent<components::StatisticsStorage>().GetMetricsStorageRef();
+
     const auto config_source = context.FindComponent<components::DynamicConfig>().GetSource();
 
     auto& testsuite_grpc = context.FindComponent<components::TestsuiteSupport>().GetGrpcControl();
@@ -103,6 +106,7 @@ ClientFactoryComponent::ClientFactoryComponent(
         *this,  // impl::PipelineCreatorInterface&
         client_common_component.completion_queues_,
         client_common_component.client_statistics_storage_,
+        metrics_storage,
         testsuite_grpc,
         config_source
     );
diff --git a/grpc/src/ugrpc/client/impl/client_qos_errors_reporter.cpp b/grpc/src/ugrpc/client/impl/client_qos_errors_reporter.cpp
@@ -0,0 +1,72 @@
+#include <userver/ugrpc/client/impl/client_qos_errors_reporter.hpp>
+
+#include <boost/range/adaptor/transformed.hpp>
+#include <boost/range/irange.hpp>
+
+#include <ugrpc/client/impl/client_qos_validation.hpp>
+#include <userver/alerts/source.hpp>
+#include <userver/dynamic_config/source.hpp>
+#include <userver/logging/log.hpp>
+#include <userver/utils/statistics/metrics_storage.hpp>
+
+USERVER_NAMESPACE_BEGIN
+
+namespace ugrpc::client::impl {
+
+namespace {
+
+const alerts::Source kGrpcClientQosInvalidConfiguration("grpc_client_qos_invalid_configuration");
+
+void UpdateAlertState(utils::statistics::MetricsStorage& metrics_storage, QosValidationResult validation_result) {
+    switch (validation_result) {
+        case QosValidationResult::kOk:
+            kGrpcClientQosInvalidConfiguration.StopAlertNow(metrics_storage);
+            break;
+        case QosValidationResult::kHasErrors:
+            kGrpcClientQosInvalidConfiguration.FireAlert(metrics_storage, alerts::Source::kInfiniteDuration);
+            break;
+        default:
+            UINVARIANT(false, "Unexpected QosValidationResult");
+            break;
+    }
+}
+
+}  // namespace
+
+ClientQosErrorsReporter::ClientQosErrorsReporter(utils::statistics::MetricsStorage& metrics_storage)
+    : metrics_storage_(metrics_storage)
+{}
+
+void ClientQosErrorsReporter::ValidateAndReportClientQosErrors(
+    const ClientQos& client_qos,
+    std::string_view config_name,
+    const ugrpc::impl::StaticServiceMetadata& metadata
+) {
+    auto log_error = [&](std::string_view method_path, RpcPathValidationError error) {
+        if (error == RpcPathValidationError::kNotFound) {
+            LOG_WARNING(
+                "Method '{}' specified in '{}' config does not exist in service '{}'. This QOS "
+                "configuration will be ignored. Available methods: {}",
+                method_path,
+                config_name,
+                metadata.service_full_name,
+                boost::irange(static_cast<std::size_t>(0), GetMethodsCount(metadata)) |
+                    boost::adaptors::transformed([&](std::size_t i) { return GetMethodFullName(metadata, i); })
+            );
+        } else {
+            LOG_WARNING(
+                "Invalid RPC method path format in GRPC_CLIENT_QOS config: '{}'. Reason: {}. Expected format: "
+                "'path.to.ServiceName/MethodName' (without leading slash). This QOS configuration will be "
+                "ignored.",
+                method_path,
+                ToString(error)
+            );
+        }
+    };
+
+    UpdateAlertState(metrics_storage_, ValidateClientQosMethodsExistence(client_qos, metadata, std::move(log_error)));
+}
+
+}  // namespace ugrpc::client::impl
+
+USERVER_NAMESPACE_END
diff --git a/grpc/src/ugrpc/client/impl/client_qos_validation.cpp b/grpc/src/ugrpc/client/impl/client_qos_validation.cpp
diff --git a/grpc/src/ugrpc/client/impl/client_qos_validation.hpp b/grpc/src/ugrpc/client/impl/client_qos_validation.hpp
diff --git a/grpc/src/ugrpc/tests/service.cpp b/grpc/src/ugrpc/tests/service.cpp
diff --git a/grpc/src/ugrpc/tests/standalone_client.cpp b/grpc/src/ugrpc/tests/standalone_client.cpp
diff --git a/grpc/tests/client_qos_test.cpp b/grpc/tests/client_qos_test.cpp
diff --git a/grpc/tests/client_qos_validation_test.cpp b/grpc/tests/client_qos_validation_test.cpp

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+alerts.grpc_client_qos_invalid_configuration: GAUGE`
`1`	`2`	`grpc.client.by-destination.abandoned-error: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService RATE`
`2`	`3`	`grpc.client.by-destination.active: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService GAUGE`
`3`	`4`	`grpc.client.by-destination.cancelled-by-deadline-propagation: grpc_destination=samples.api.GreeterService/SayHello, grpc_destination_full=greeter/samples.api.GreeterService/SayHello, grpc_method=SayHello, grpc_service=samples.api.GreeterService RATE`