stats: Add universal stats tag from CLI

api/envoy/admin/v3/server_info.proto

@@ -58,7 +58,7 @@ message ServerInfo {
   config.core.v3.Node node = 7;
 }
 
-// [#next-free-field: 38]
+// [#next-free-field: 39]
 message CommandLineOptions {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.admin.v2alpha.CommandLineOptions";
@@ -189,4 +189,7 @@ message CommandLineOptions {
 
   // See :option:`--enable-core-dump` for details.
   bool enable_core_dump = 37;
+
+  // See :option:`--stats-tag` for details.
+  repeated string stats_tag = 38;
 }

docs/root/operations/cli.rst

@@ -359,3 +359,9 @@ following are the command line options that Envoy supports.
   It enables core dumps by invoking `prctl <https://man7.org/linux/man-pages/man2/prctl.2.html>`_ using the
   PR_SET_DUMPABLE option. This is useful for container environments when using capabilities, given that when
   Envoy has more capabilities than its base environment core dumping will be disabled by the kernel.
+
+.. option:: --stats-tag
+
+  *(optional)* This flag provides a universal tag for all stats generated by Envoy. The format is ``tag:value``. Only
+  alphanumeric values are allowed for tag names. For tag values all characters are permitted except for '.' (dot).
+  This flag can be repeated multiple times to set multiple universal tags. However, multiple stats with different values are not allowed.

envoy/server/options.h

@@ -8,6 +8,7 @@
 #include "envoy/common/pure.h"
 #include "envoy/config/bootstrap/v3/bootstrap.pb.h"
 #include "envoy/network/address.h"
+#include "envoy/stats/tag.h"
 
 #include "absl/types/optional.h"
 #include "spdlog/spdlog.h"
@@ -259,6 +260,12 @@ class Options {
    * @return the mode of socket file.
    */
   virtual mode_t socketMode() const PURE;
+
+  /**
+   * @return the stats tags provided by the cli. Tags may contain duplicates. It is the
+   * responsibility of the caller to handle the duplicates.
+   */
+  virtual const Stats::TagVector& statsTags() const PURE;
 };
 
 } // namespace Server

source/common/config/utility.cc

@@ -215,8 +215,9 @@ Utility::parseRateLimitSettings(const envoy::config::core::v3::ApiConfigSource&
 }
 
 Stats::TagProducerPtr
-Utility::createTagProducer(const envoy::config::bootstrap::v3::Bootstrap& bootstrap) {
-  return std::make_unique<Stats::TagProducerImpl>(bootstrap.stats_config());
+Utility::createTagProducer(const envoy::config::bootstrap::v3::Bootstrap& bootstrap,
+                           const Stats::TagVector& cli_tags) {
+  return std::make_unique<Stats::TagProducerImpl>(bootstrap.stats_config(), cli_tags);
 }
 
 Stats::StatsMatcherPtr

source/common/config/utility.h

@@ -420,10 +420,12 @@ class Utility {
    * Create TagProducer instance. Check all tag names for conflicts to avoid
    * unexpected tag name overwriting.
    * @param bootstrap bootstrap proto.
+   * @param cli_tags tags that are provided by the cli
    * @throws EnvoyException when the conflict of tag names is found.
    */
   static Stats::TagProducerPtr
-  createTagProducer(const envoy::config::bootstrap::v3::Bootstrap& bootstrap);
+  createTagProducer(const envoy::config::bootstrap::v3::Bootstrap& bootstrap,
+                    const Stats::TagVector& cli_tags);
 
   /**
    * Create StatsMatcher instance.

source/common/config/well_known_names.cc

@@ -18,7 +18,7 @@ std::string expandRegex(const std::string& regex) {
               // underscores.
               {"<CIPHER>", R"([\w-]+)"},
               // A generic name can contain any character except dots.
-              {"<NAME>", R"([^\.]+)"},
+              {"<NAME>", NAME_REGEX},
               // Route names may contain dots in addition to alphanumerics and
               // dashes with underscores.
               {"<ROUTE_CONFIG_NAME>", R"([\w-\.]+)"}});

source/common/config/well_known_names.h

@@ -12,6 +12,8 @@
 namespace Envoy {
 namespace Config {
 
+const std::string NAME_REGEX = R"([^\.]+)";
+
 /**
  * Well-known address resolver names.
  */

source/common/stats/BUILD

@@ -90,6 +90,7 @@ envoy_cc_library(
         ":symbol_table_lib",
         "//envoy/stats:stats_interface",
         "//envoy/stats:symbol_table_interface",
+        "//source/common/config:well_known_names",
     ],
 )
 

source/common/stats/tag_producer_impl.cc

@@ -11,11 +11,22 @@
 namespace Envoy {
 namespace Stats {
 
-TagProducerImpl::TagProducerImpl(const envoy::config::metrics::v3::StatsConfig& config) {
+TagProducerImpl::TagProducerImpl(const envoy::config::metrics::v3::StatsConfig& config)
+    : TagProducerImpl(config, {}) {}
+
+TagProducerImpl::TagProducerImpl(const envoy::config::metrics::v3::StatsConfig& config,
+                                 const Stats::TagVector& cli_tags) {
   // To check name conflict.
   reserveResources(config);
   absl::node_hash_set<std::string> names = addDefaultExtractors(config);
 
+  for (const auto& cli_tag : cli_tags) {
+    if (!names.emplace(cli_tag.name_).second) {
+      throw EnvoyException(fmt::format("Tag name '{}' specified twice.", cli_tag.name_));
+    }
+    default_tags_.emplace_back(cli_tag);
+  }
+
   for (const auto& tag_specifier : config.stats_tags()) {
     const std::string& name = tag_specifier.tag_name();
     if (!names.emplace(name).second) {

source/common/stats/tag_producer_impl.h

@@ -28,7 +28,11 @@ namespace Stats {
  */
 class TagProducerImpl : public TagProducer {
 public:
+  TagProducerImpl(const envoy::config::metrics::v3::StatsConfig& config,
+                  const Stats::TagVector& cli_tags);
+
   TagProducerImpl(const envoy::config::metrics::v3::StatsConfig& config);
+
   TagProducerImpl() = default;
 
   /**

source/common/stats/tag_utility.cc

@@ -1,5 +1,8 @@
 #include "source/common/stats/tag_utility.h"
 
+#include <regex>
+
+#include "source/common/config/well_known_names.h"
 #include "source/common/stats/symbol_table_impl.h"
 
 namespace Envoy {
@@ -48,6 +51,29 @@ SymbolTable::StoragePtr TagStatNameJoiner::joinNameAndTags(StatName name,
 
   return symbol_table.join(stat_names);
 }
+
+bool isTagValueValid(absl::string_view name) {
+  std::regex regex{Config::NAME_REGEX, std::regex::optimize};
+  int cntr = 0;
+  for (auto i = std::regex_iterator<absl::string_view::iterator>(name.begin(), name.end(), regex);
+       i != std::regex_iterator<absl::string_view::iterator>(); ++i) {
+    cntr++;
+    if (cntr > 1) {
+      return false;
+    }
+  }
+  return true;
+}
+
+bool isTagNameValid(absl::string_view value) {
+  for (const auto& token : value) {
+    if (!absl::ascii_isalnum(token)) {
+      return false;
+    }
+  }
+  return true;
+}
+
 } // namespace TagUtility
 } // namespace Stats
 } // namespace Envoy

source/common/stats/tag_utility.h

@@ -54,6 +54,12 @@ class TagStatNameJoiner {
   SymbolTable::StoragePtr joinNameAndTags(StatName name, const StatNameTagVector& stat_name_tags,
                                           SymbolTable& symbol_table);
 };
+
+
+bool isTagNameValid(absl::string_view name);
+
+bool isTagValueValid(absl::string_view value);
+
 } // namespace TagUtility
 } // namespace Stats
 } // namespace Envoy

source/server/BUILD

@@ -388,6 +388,7 @@ envoy_cc_library(
         "//source/common/common:macros",
         "//source/common/protobuf:utility_lib",
         "//source/common/stats:stats_lib",
+        "//source/common/stats:tag_utility_lib",
         "//source/common/version:version_lib",
     ],
 )

source/server/config_validation/server.cc

@@ -82,7 +82,7 @@ void ValidationInstance::initialize(const Options& options,
   InstanceUtil::loadBootstrapConfig(bootstrap_, options,
                                     messageValidationContext().staticValidationVisitor(), *api_);
 
-  Config::Utility::createTagProducer(bootstrap_);
+  Config::Utility::createTagProducer(bootstrap_, options_.statsTags());
   if (!bootstrap_.node().user_agent_build_version().has_version()) {
     *bootstrap_.mutable_node()->mutable_user_agent_build_version() = VersionInfo::buildVersion();
   }

source/server/options_impl.cc

@@ -11,6 +11,7 @@
 #include "source/common/common/logger.h"
 #include "source/common/common/macros.h"
 #include "source/common/protobuf/utility.h"
+#include "source/common/stats/tag_utility.h"
 #include "source/common/version/version.h"
 #include "source/server/options_impl_platform.h"
 
@@ -151,6 +152,14 @@ OptionsImpl::OptionsImpl(std::vector<std::string> args,
                                            "600", "string", cmd);
   TCLAP::SwitchArg enable_core_dump("", "enable-core-dump", "Enable core dumps", cmd, false);
 
+  TCLAP::MultiArg<std::string> stats_tag(
+      "", "stats-tag",
+      "This flag provides a universal tag for all stats generated by Envoy. The format is "
+      "``tag:value``. Only alphanumeric values are allowed for tag names. For tag values all "
+      "characters are permitted except for '.' (dot). This flag can be repeated multiple times to "
+      "set multiple universal tags. However, multiple stats with different values are not allowed.",
+      false, "string", cmd);
+
   cmd.setExceptionHandling(false);
   TRY_ASSERT_MAIN_THREAD {
     cmd.parse(args);
@@ -282,6 +291,33 @@ OptionsImpl::OptionsImpl(std::vector<std::string> args,
   if (!disable_extensions.getValue().empty()) {
     disabled_extensions_ = absl::StrSplit(disable_extensions.getValue(), ',');
   }
+
+  if (!stats_tag.getValue().empty()) {
+    for (const auto& cli_tag_pair : stats_tag.getValue()) {
+
+      absl::string_view::size_type colon = cli_tag_pair.find(':');
+      if (colon == absl::string_view::npos) {
+        throw MalformedArgvException(
+            fmt::format("error: misformatted stats-tag '{}'", cli_tag_pair));
+      }
+
+      auto name = cli_tag_pair.substr(0, colon);
+      if (!Stats::TagUtility::isTagNameValid(name)) {
+        throw MalformedArgvException(
+            fmt::format("error: misformatted stats-tag '{}' contains invalid char in '{}'",
+                        cli_tag_pair, name));
+      }
+
+      auto value = cli_tag_pair.substr(colon + 1);
+      if (!Stats::TagUtility::isTagValueValid(value)) {
+        throw MalformedArgvException(
+            fmt::format("error: misformatted stats-tag '{}' contains invalid char in '{}'",
+                        cli_tag_pair, value));
+      }
+
+      stats_tags_.emplace_back(Stats::Tag{std::string(name), std::string(value)});
+    }
+  }
 }
 
 spdlog::level::level_enum OptionsImpl::parseAndValidateLogLevel(absl::string_view log_level) {
@@ -396,6 +432,9 @@ Server::CommandLineOptionsPtr OptionsImpl::toCommandLineOptions() const {
   }
   command_line_options->set_socket_path(socketPath());
   command_line_options->set_socket_mode(socketMode());
+  for (const auto& tag : statsTags()) {
+    command_line_options->add_stats_tag(fmt::format("{}:{}", tag.name_, tag.value_));
+  }
   return command_line_options;
 }
 

source/server/options_impl.h

@@ -104,6 +104,8 @@ class OptionsImpl : public Server::Options, protected Logger::Loggable<Logger::I
 
   void setSocketMode(mode_t socket_mode) { socket_mode_ = socket_mode; }
 
+  void setStatsTags(const Stats::TagVector& stats_tags) { stats_tags_ = stats_tags; }
+
   // Server::Options
   uint64_t baseId() const override { return base_id_; }
   bool useDynamicBaseId() const override { return use_dynamic_base_id_; }
@@ -146,6 +148,7 @@ class OptionsImpl : public Server::Options, protected Logger::Loggable<Logger::I
   bool signalHandlingEnabled() const override { return signal_handling_enabled_; }
   bool mutexTracingEnabled() const override { return mutex_tracing_enabled_; }
   bool coreDumpEnabled() const override { return core_dump_enabled_; }
+  const Stats::TagVector& statsTags() const override { return stats_tags_; }
   Server::CommandLineOptionsPtr toCommandLineOptions() const override;
   void parseComponentLogLevels(const std::string& component_log_levels);
   bool cpusetThreadsEnabled() const override { return cpuset_threads_; }
@@ -207,6 +210,7 @@ class OptionsImpl : public Server::Options, protected Logger::Loggable<Logger::I
   bool core_dump_enabled_{false};
   bool cpuset_threads_{false};
   std::vector<std::string> disabled_extensions_;
+  Stats::TagVector stats_tags_;
   uint32_t count_{0};
 
   // Initialization added here to avoid integration_admin_test failure caused by uninitialized

source/server/server.cc

@@ -395,7 +395,7 @@ void InstanceImpl::initialize(Network::Address::InstanceConstSharedPtr local_add
 
   // Needs to happen as early as possible in the instantiation to preempt the objects that require
   // stats.
-  stats_store_.setTagProducer(Config::Utility::createTagProducer(bootstrap_));
+  stats_store_.setTagProducer(Config::Utility::createTagProducer(bootstrap_, options_.statsTags()));
   stats_store_.setStatsMatcher(
       Config::Utility::createStatsMatcher(bootstrap_, stats_store_.symbolTable()));
   stats_store_.setHistogramSettings(Config::Utility::createHistogramSettings(bootstrap_));

test/common/config/utility_test.cc

@@ -98,14 +98,24 @@ TEST(UtilityTest, TranslateApiConfigSource) {
 
 TEST(UtilityTest, createTagProducer) {
   envoy::config::bootstrap::v3::Bootstrap bootstrap;
-  auto producer = Utility::createTagProducer(bootstrap);
-  ASSERT(producer != nullptr);
-  std::vector<Stats::Tag> tags;
+  auto producer = Utility::createTagProducer(bootstrap, {});
+  ASSERT_TRUE(producer != nullptr);
+  Stats::TagVector tags;
   auto extracted_name = producer->produceTags("http.config_test.rq_total", tags);
   ASSERT_EQ(extracted_name, "http.rq_total");
   ASSERT_EQ(tags.size(), 1);
 }
 
+TEST(UtilityTest, createTagProducerWithDefaultTgs) {
+  envoy::config::bootstrap::v3::Bootstrap bootstrap;
+  auto producer = Utility::createTagProducer(bootstrap, {{"foo", "bar"}});
+  ASSERT_TRUE(producer != nullptr);
+  Stats::TagVector tags;
+  auto extracted_name = producer->produceTags("http.config_test.rq_total", tags);
+  EXPECT_EQ(extracted_name, "http.rq_total");
+  EXPECT_EQ(tags.size(), 2);
+}
+
 TEST(UtilityTest, CheckFilesystemSubscriptionBackingPath) {
   Api::ApiPtr api = Api::createApiForTest();
 

test/common/stats/tag_producer_impl_test.cc

@@ -17,22 +17,33 @@ TEST(TagProducerTest, CheckConstructor) {
   auto& tag_specifier1 = *stats_config.mutable_stats_tags()->Add();
   tag_specifier1.set_tag_name("test.x");
   tag_specifier1.set_fixed_value("xxx");
-  EXPECT_NO_THROW(TagProducerImpl{stats_config});
+  EXPECT_NO_THROW(TagProducerImpl(stats_config, {}));
+  EXPECT_NO_THROW(TagProducerImpl(stats_config, {{"test.y", "yyy"}}));
+
+  // Should raise an error when duplicate tag names between cli and config.
+  EXPECT_THROW_WITH_MESSAGE(TagProducerImpl(stats_config, {{"test.x", "yyy"}}), EnvoyException,
+                            fmt::format("Tag name '{}' specified twice.", "test.x"));
 
   // Should raise an error when duplicate tag names are specified.
   auto& tag_specifier2 = *stats_config.mutable_stats_tags()->Add();
   tag_specifier2.set_tag_name("test.x");
   tag_specifier2.set_fixed_value("yyy");
-  EXPECT_THROW_WITH_MESSAGE(TagProducerImpl{stats_config}, EnvoyException,
+  EXPECT_THROW_WITH_MESSAGE(TagProducerImpl(stats_config, {{"test.y", "yyy"}}), EnvoyException,
                             fmt::format("Tag name '{}' specified twice.", "test.x"));
 
+  // Should raise an error when a cli tag names conflicts with Envoy's default tag names.
+  EXPECT_THROW_WITH_MESSAGE(
+      TagProducerImpl(stats_config, {{Config::TagNames::get().CLUSTER_NAME, "yyy"}}),
+      EnvoyException,
+      fmt::format("Tag name '{}' specified twice.", Config::TagNames::get().CLUSTER_NAME));
+
   // Also should raise an error when user defined tag name conflicts with Envoy's default tag names.
   stats_config.clear_stats_tags();
   stats_config.mutable_use_all_default_tags()->set_value(true);
   auto& custom_tag_extractor = *stats_config.mutable_stats_tags()->Add();
   custom_tag_extractor.set_tag_name(Config::TagNames::get().CLUSTER_NAME);
   EXPECT_THROW_WITH_MESSAGE(
-      TagProducerImpl{stats_config}, EnvoyException,
+      TagProducerImpl(stats_config, {}), EnvoyException,
       fmt::format("Tag name '{}' specified twice.", Config::TagNames::get().CLUSTER_NAME));
 
   // Non-default custom name without regex should throw
@@ -41,7 +52,7 @@ TEST(TagProducerTest, CheckConstructor) {
   custom_tag_extractor = *stats_config.mutable_stats_tags()->Add();
   custom_tag_extractor.set_tag_name("test_extractor");
   EXPECT_THROW_WITH_MESSAGE(
-      TagProducerImpl{stats_config}, EnvoyException,
+      TagProducerImpl(stats_config, {}), EnvoyException,
       "No regex specified for tag specifier and no default regex for name: 'test_extractor'");
 
   // Also empty regex should throw
@@ -51,7 +62,7 @@ TEST(TagProducerTest, CheckConstructor) {
   custom_tag_extractor.set_tag_name("test_extractor");
   custom_tag_extractor.set_regex("");
   EXPECT_THROW_WITH_MESSAGE(
-      TagProducerImpl{stats_config}, EnvoyException,
+      TagProducerImpl(stats_config, {}), EnvoyException,
       "No regex specified for tag specifier and no default regex for name: 'test_extractor'");
 }
 

test/mocks/server/options.cc

@@ -45,6 +45,7 @@ MockOptions::MockOptions(const std::string& config_path) : config_path_(config_p
   }));
   ON_CALL(*this, socketPath()).WillByDefault(ReturnRef(socket_path_));
   ON_CALL(*this, socketMode()).WillByDefault(ReturnPointee(&socket_mode_));
+  ON_CALL(*this, statsTags()).WillByDefault(ReturnRef(stats_tags_));
 }
 
 MockOptions::~MockOptions() = default;