API: Unready Targets Dump

api/envoy/admin/v3/init_dump.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package envoy.admin.v3;
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+
+option java_package = "io.envoyproxy.envoy.admin.v3";
+option java_outer_classname = "InitDumpProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: InitDump]
+
+// Dumps of unready targets of envoy init managers. Envoy's admin fills this message with init managers,
+// which provides the information of their unready targets.
+// The :ref:`/init_dump <operations_admin_interface_init_dump>` will dump all unready targets information.
+message UnreadyTargetsDumps {
+  // Message of unready targets information of an init manager.
+  message UnreadyTargetsDump {
+    // Name of the init manager. Example: "init_manager_xxx".
+    string name = 1;
+
+    // Names of unready targets of the init manager. Example: "target_xxx".
+    repeated string target_names = 2;
+  }
+
+  // You can choose specific component to dump unready targets with mask query parameter.
+  // See :ref:`/init_dump?mask={} <operations_admin_interface_init_dump_by_mask>` for more information.
+  // The dumps of unready targets of all init managers.
+  repeated UnreadyTargetsDump unready_targets_dumps = 1;
+}

docs/root/operations/admin.rst

@@ -212,6 +212,24 @@ modify different aspects of the server:
 
   See :option:`--hot-restart-version`.
 
+.. _operations_admin_interface_init_dump:
+
+.. http:get:: /init_dump
+
+  Dump currently information of unready targets of various Envoy components as JSON-serialized proto
+  messages. See the :ref:`response definition <envoy_v3_api_msg_admin.v3.UnreadyTargetsDumps>` for more
+  information.
+
+.. _operations_admin_interface_init_dump_by_mask:
+
+.. http:get:: /init_dump?mask={}
+
+  When mask query parameters is specified, the mask value is the desired component to dump unready targets.
+  The mask is parsed as a ``ProtobufWkt::FieldMask``.
+
+  For example, get the unready targets of all listeners with
+  ``/init_dump?mask=listener``
+
 .. _operations_admin_interface_listeners:
 
 .. http:get:: /listeners

docs/root/version_history/current.rst

@@ -65,6 +65,7 @@ New Features
 * access log: added support for :ref:`%DOWNSTREAM_PEER_FINGERPRINT_1% <config_access_log_format_response_flags>` as a response flag.
 * access log: added support for nested objects in :ref:`JSON logging mode <config_access_log_format_dictionaries>`.
 * access log: added :ref:`omit_empty_values<envoy_v3_api_field_config.core.v3.SubstitutionFormatString.omit_empty_values>` option to omit unset value from formatted log.
+* admin: added the ability to dump init manager unready targets information :ref:`/init_dump <operations_admin_interface_init_dump>` and :ref:`/init_dump?mask={} <operations_admin_interface_init_dump_by_mask>`.
 * build: enable building envoy :ref:`arm64 images <arm_binaries>` by buildx tool in x86 CI platform.
 * cluster: added new :ref:`connection_pool_per_downstream_connection <envoy_v3_api_field_config.cluster.v3.Cluster.connection_pool_per_downstream_connection>` flag, which enable creation of a new connection pool for each downstream connection.
 * decompressor filter: reports compressed and uncompressed bytes in trailers.

include/envoy/init/BUILD

@@ -27,5 +27,6 @@ envoy_cc_library(
     deps = [
         ":target_interface",
         ":watcher_interface",
+        "@envoy_api//envoy/admin/v3:pkg_cc_proto",
     ],
 )

include/envoy/init/manager.h

@@ -1,9 +1,12 @@
 #pragma once
 
+#include "envoy/admin/v3/init_dump.pb.h"
 #include "envoy/common/pure.h"
 #include "envoy/init/target.h"
 #include "envoy/init/watcher.h"
 
+#include "absl/container/flat_hash_map.h"
+
 namespace Envoy {
 namespace Init {
 
@@ -73,6 +76,16 @@ struct Manager {
    * @param watcher the watcher to notify when initialization is complete.
    */
   virtual void initialize(const Watcher& watcher) PURE;
+
+  /**
+   * @return the unready targets of the manager.
+   */
+  virtual const absl::flat_hash_map<std::string, uint32_t>& unreadyTargets() const PURE;
+
+  /**
+   * Add unready targets information into the config dump.
+   */
+  virtual void dumpUnreadyTargets(envoy::admin::v3::UnreadyTargetsDumps& dumps) PURE;
 };
 
 } // namespace Init

include/envoy/network/BUILD

@@ -170,6 +170,7 @@ envoy_cc_library(
         ":udp_packet_writer_handler_interface",
         "//include/envoy/access_log:access_log_interface",
         "//include/envoy/common:resource_interface",
+        "//include/envoy/init:manager_interface",
         "//include/envoy/stats:stats_interface",
         "@envoy_api//envoy/config/core/v3:pkg_cc_proto",
     ],

include/envoy/network/listener.h

@@ -9,6 +9,7 @@
 #include "envoy/common/exception.h"
 #include "envoy/common/resource.h"
 #include "envoy/config/core/v3/base.pb.h"
+#include "envoy/init/manager.h"
 #include "envoy/network/connection.h"
 #include "envoy/network/connection_balancer.h"
 #include "envoy/network/listen_socket.h"
@@ -166,6 +167,11 @@ class ListenerConfig {
    * @return pending connection backlog for TCP listeners.
    */
   virtual uint32_t tcpBacklogSize() const PURE;
+
+  /**
+   * @return init manager of the listener.
+   */
+  virtual Init::Manager& initManager() PURE;
 };
 
 /**

include/envoy/server/listener_manager.h

@@ -235,6 +235,11 @@ class ListenerManager {
    * @return the server's API Listener if it exists, nullopt if it does not.
    */
   virtual ApiListenerOptRef apiListener() PURE;
+
+  /*
+   * @return TRUE if the worker has started or FALSE if not.
+   */
+  virtual bool isWorkerStarted() PURE;
 };
 
 // overload operator| to allow ListenerManager::listeners(ListenerState) to be called using a

source/common/init/manager_impl.cc

@@ -67,6 +67,14 @@ const absl::flat_hash_map<std::string, uint32_t>& ManagerImpl::unreadyTargets()
   return target_names_count_;
 }
 
+void ManagerImpl::dumpUnreadyTargets(envoy::admin::v3::UnreadyTargetsDumps& unready_targets_dumps) {
+  auto& message = *unready_targets_dumps.mutable_unready_targets_dumps()->Add();
+  message.set_name(name_);
+  for (const auto& [target_name, count] : target_names_count_) {
+    message.add_target_names(target_name);
+  }
+}
+
 void ManagerImpl::onTargetReady(absl::string_view target_name) {
   // If there are no remaining targets and one mysteriously calls us back, this manager is haunted.
   ASSERT(count_ != 0,

source/common/init/manager_impl.h

@@ -36,9 +36,8 @@ class ManagerImpl : public Manager, Logger::Loggable<Logger::Id::init> {
   State state() const override;
   void add(const Target& target) override;
   void initialize(const Watcher& watcher) override;
-
-  // Expose the const reference of target_names_count_ hash map to public.
-  const absl::flat_hash_map<std::string, uint32_t>& unreadyTargets() const;
+  const absl::flat_hash_map<std::string, uint32_t>& unreadyTargets() const override;
+  void dumpUnreadyTargets(envoy::admin::v3::UnreadyTargetsDumps& dumps) override;
 
 private:
   // Callback function with an additional target_name parameter, decrease unready targets count by

source/server/admin/BUILD

@@ -17,6 +17,7 @@ envoy_cc_library(
         ":clusters_handler_lib",
         ":config_dump_handler_lib",
         ":config_tracker_lib",
+        ":init_dump_handler_lib",
         ":listeners_handler_lib",
         ":logs_handler_lib",
         ":profiling_handler_lib",
@@ -63,6 +64,7 @@ envoy_cc_library(
         "//source/common/router:scoped_config_lib",
         "//source/common/stats:isolated_store_lib",
         "//source/extensions/access_loggers/file:file_access_log_lib",
+        "//source/server:listener_manager_lib",
     ],
 )
 
@@ -259,6 +261,21 @@ envoy_cc_library(
     ],
 )
 
+envoy_cc_library(
+    name = "init_dump_handler_lib",
+    srcs = ["init_dump_handler.cc"],
+    hdrs = ["init_dump_handler.h"],
+    deps = [
+        ":handler_ctx_lib",
+        ":utils_lib",
+        "//include/envoy/server:admin_interface",
+        "//include/envoy/server:instance_interface",
+        "//source/common/http:codes_lib",
+        "//source/common/http:header_map_lib",
+        "@envoy_api//envoy/admin/v3:pkg_cc_proto",
+    ],
+)
+
 envoy_cc_library(
     name = "utils_lib",
     srcs = ["utils.cc"],

source/server/admin/admin.cc

@@ -35,6 +35,7 @@
 #include "common/router/config_impl.h"
 
 #include "server/admin/utils.h"
+#include "server/listener_impl.h"
 
 #include "extensions/access_loggers/file/file_access_log_impl.h"
 
@@ -154,9 +155,10 @@ AdminImpl::AdminImpl(const std::string& profile_path, Server::Instance& server)
           Http::ConnectionManagerImpl::generateTracingStats("http.admin.", no_op_store_)),
       route_config_provider_(server.timeSource()),
       scoped_route_config_provider_(server.timeSource()), clusters_handler_(server),
-      config_dump_handler_(config_tracker_, server), stats_handler_(server), logs_handler_(server),
-      profiling_handler_(profile_path), runtime_handler_(server), listeners_handler_(server),
-      server_cmd_handler_(server), server_info_handler_(server),
+      config_dump_handler_(config_tracker_, server), init_dump_handler_(server),
+      stats_handler_(server), logs_handler_(server), profiling_handler_(profile_path),
+      runtime_handler_(server), listeners_handler_(server), server_cmd_handler_(server),
+      server_info_handler_(server),
       // TODO(jsedgwick) add /runtime_reset endpoint that removes all admin-set values
       handlers_{
           {"/", "Admin home page", MAKE_ADMIN_HANDLER(handlerAdminHome), false, false},
@@ -166,6 +168,8 @@ AdminImpl::AdminImpl(const std::string& profile_path, Server::Instance& server)
            MAKE_ADMIN_HANDLER(clusters_handler_.handlerClusters), false, false},
           {"/config_dump", "dump current Envoy configs (experimental)",
            MAKE_ADMIN_HANDLER(config_dump_handler_.handlerConfigDump), false, false},
+          {"/init_dump", "dump current Envoy init manager information (experimental)",
+           MAKE_ADMIN_HANDLER(init_dump_handler_.handlerInitDump), false, false},
           {"/contention", "dump current Envoy mutex contention stats (if enabled)",
            MAKE_ADMIN_HANDLER(stats_handler_.handlerContention), false, false},
           {"/cpuprofiler", "enable/disable the CPU profiler",

source/server/admin/admin.h

@@ -39,6 +39,7 @@
 #include "server/admin/clusters_handler.h"
 #include "server/admin/config_dump_handler.h"
 #include "server/admin/config_tracker_impl.h"
+#include "server/admin/init_dump_handler.h"
 #include "server/admin/listeners_handler.h"
 #include "server/admin/logs_handler.h"
 #include "server/admin/profiling_handler.h"
@@ -287,6 +288,7 @@ class AdminImpl : public Admin,
   Http::Code handlerAdminHome(absl::string_view path_and_query,
                               Http::ResponseHeaderMap& response_headers, Buffer::Instance& response,
                               AdminStream&);
+
   Http::Code handlerHelp(absl::string_view path_and_query,
                          Http::ResponseHeaderMap& response_headers, Buffer::Instance& response,
                          AdminStream&);
@@ -320,7 +322,8 @@ class AdminImpl : public Admin,
   public:
     AdminListener(AdminImpl& parent, Stats::ScopePtr&& listener_scope)
         : parent_(parent), name_("admin"), scope_(std::move(listener_scope)),
-          stats_(Http::ConnectionManagerImpl::generateListenerStats("http.admin.", *scope_)) {}
+          stats_(Http::ConnectionManagerImpl::generateListenerStats("http.admin.", *scope_)),
+          init_manager_(nullptr) {}
 
     // Network::ListenerConfig
     Network::FilterChainManager& filterChainManager() override { return parent_; }
@@ -351,6 +354,7 @@ class AdminImpl : public Admin,
       return empty_access_logs_;
     }
     uint32_t tcpBacklogSize() const override { return ENVOY_TCP_BACKLOG_SIZE; }
+    Init::Manager& initManager() override { return *init_manager_; }
 
     AdminImpl& parent_;
     const std::string name_;
@@ -361,6 +365,7 @@ class AdminImpl : public Admin,
 
   private:
     const std::vector<AccessLog::InstanceSharedPtr> empty_access_logs_;
+    std::unique_ptr<Init::Manager> init_manager_;
   };
   using AdminListenerPtr = std::unique_ptr<AdminListener>;
 
@@ -398,6 +403,7 @@ class AdminImpl : public Admin,
   NullScopedRouteConfigProvider scoped_route_config_provider_;
   Server::ClustersHandler clusters_handler_;
   Server::ConfigDumpHandler config_dump_handler_;
+  Server::InitDumpHandler init_dump_handler_;
   Server::StatsHandler stats_handler_;
   Server::LogsHandler logs_handler_;
   Server::ProfilingHandler profiling_handler_;