Merge remote-tracking branch 'origin/topic/christian/telemetry-editpass'

* origin/topic/christian/telemetry-editpass:
  Telemetry framework updates for the management framework & zeek-client
  Update code examples to new Telemetry API
  Edit pass over telemetry framework docs

frameworks/management.rst

@@ -633,11 +633,11 @@ All but the worker nodes in a Zeek cluster require a listening port, and you can
 specify one for each node as shown in the above configuration. If you'd rather
 not pick ports, the controller can auto-enumerate ports for you, as follows:
 
-* The :zeek:see:`Management::Controller::auto_assign_ports` Boolean, which defaults to
+* The :zeek:see:`Management::Controller::auto_assign_broker_ports` Boolean, which defaults to
   ``T``, controls whether port auto-enumeration is active. Redefining to ``F``
   disables the feature.
 
-* :zeek:see:`Management::Controller::auto_assign_start_port` defines the starting point
+* :zeek:see:`Management::Controller::auto_assign_broker_start_port` defines the starting point
   for port enumeration. This defaults to ``2200/tcp``.
 
 * Any nodes with explicitly configured ports will keep them.
@@ -655,6 +655,19 @@ not pick ports, the controller can auto-enumerate ports for you, as follows:
 By retrieving the deployed configuration from the controller (see the next two
 sections) you can examine which ports the controller selected.
 
+Configuration of the Telemetry framework
+----------------------------------------
+
+By default, the framework will enable Prometheus metrics exposition ports,
+including a service discovery endpoint on the mananger (refer to the
+:ref:`Telemetry Framework <framework-telemetry>` for details), and
+auto-assign them for you. Specifically, the controller will enumerate ports
+starting from
+:zeek:see:`Management::Controller::auto_assign_metrics_start_port`, which
+defaults to ``9000/tcp``. Any ports you define manually will be preserved.  To
+disable metrics port auto-assignment, redefine
+:zeek:see:`Management::Controller::auto_assign_metrics_ports` to ``F``.
+
 Staging and deploying configurations
 ------------------------------------
 

frameworks/management/full-config.ini

@@ -30,6 +30,12 @@ role = manager
 #
 # port = 1234
 
+# You can optionally specify explicit metrics exposition ports for each
+# node. If you omit these, the framework (specifically, the controller)
+# will define ports for you. Only give a number; TCP is implied.
+#
+# metrics_port = 9090
+
 # You can provide additional scripts that a node should run. These scripts
 # must be available on the instance. Space-separate multiple scripts.
 #

frameworks/telemetry/connection-durations.zeek

@@ -4,7 +4,7 @@ global conn_durations_hf = Telemetry::register_histogram_family([
 	$unit="seconds",
 	$help_text="Duration of monitored connections",
 	$bounds=vector(0.1, 1.0, 10.0, 30.0, 60.0),
-	$labels=vector("proto", "service")
+	$label_names=vector("proto", "service")
 ]);
 
 event connection_state_remove(c: connection)

frameworks/telemetry/log-writes-cached.zeek

@@ -3,7 +3,7 @@ global log_writes_cf = Telemetry::register_counter_family([
 	$name="log_writes",
 	$unit="1",
 	$help_text="Number of log writes per stream",
-	$labels=vector("log_id")
+	$label_names=vector("log_id")
 ]);
 
 # Cache for the Telemetry::Counter instances.

frameworks/telemetry/log-writes-immediate.zeek

@@ -3,7 +3,7 @@ global log_writes_cf = Telemetry::register_counter_family([
 	$name="log_writes",
 	$unit="1",
 	$help_text="Number of log writes per stream",
-	$labels=vector("log_id")
+	$label_names=vector("log_id")
 ]);
 
 hook Log::log_stream_policy(rec: any, id: Log::ID)

frameworks/telemetry/log-writes-sync.zeek

@@ -3,7 +3,7 @@ global log_writes_cf = Telemetry::register_counter_family([
 	$name="log_writes",
 	$unit="1",
 	$help_text="Number of log writes per stream",
-	$labels=vector("log_id")
+	$label_names=vector("log_id")
 ]);
 
 global log_writes: table[Log::ID] of count &default=0;

frameworks/telemetry/version.zeek

@@ -3,7 +3,7 @@ global version_gf = Telemetry::register_gauge_family([
 	$name="version_info",
 	$unit="1",
 	$help_text="The Zeek version",
-	$labels=vector("version_number", "major", "minor", "patch", "commit", "beta", "debug","version_string")
+	$label_names=vector("version_number", "major", "minor", "patch", "commit", "beta", "debug","version_string")
 ]);
 
 event zeek_init()