devel: Add event metadata plugin example

devel/plugins.rst

@@ -490,3 +490,4 @@ Plugin Tutorials
    :maxdepth: 1
 
    plugins/connkey-plugin
+   plugins/event-metadata-plugin

devel/plugins/event-metadata-plugin-src/.gitignore

@@ -0,0 +1,3 @@
+build
+*.log
+.state

devel/plugins/event-metadata-plugin-src/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
+
+project(ZeekPluginEventLatency)
+
+include(ZeekPlugin)
+
+zeek_add_plugin(
+    Zeek
+    EventLatency
+    SOURCES
+    src/Plugin.cc
+    SCRIPT_FILES scripts/__load__.zeek
+)

devel/plugins/event-metadata-plugin-src/COPYING

@@ -0,0 +1,26 @@
+Copyright (c) 2025 by the Zeek Project. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

devel/plugins/event-metadata-plugin-src/Makefile

@@ -0,0 +1,23 @@
+#
+# Convenience Makefile providing a few common top-level targets.
+#
+
+cmake_build_dir=build
+arch=`uname -s | tr A-Z a-z`-`uname -m`
+
+all: build-it
+
+build-it:
+	( cd $(cmake_build_dir) && make )
+
+install:
+	( cd $(cmake_build_dir) && make install )
+
+clean:
+	( cd $(cmake_build_dir) && make clean )
+
+distclean:
+	rm -rf $(cmake_build_dir)
+
+test:
+	make -C tests

devel/plugins/event-metadata-plugin-src/VERSION

@@ -0,0 +1 @@
+0.1.0

devel/plugins/event-metadata-plugin-src/configure

@@ -0,0 +1,193 @@
+#!/bin/sh
+#
+# Wrapper for viewing/setting options that the plugin's CMake
+# scripts will recognize.
+#
+# Don't edit this. Edit configure.plugin to add plugin-specific options.
+#
+
+set -e
+command="$0 $*"
+
+if [ -e $(dirname $0)/configure.plugin ]; then
+    # Include custom additions.
+    . $(dirname $0)/configure.plugin
+fi
+
+usage() {
+
+    cat 1>&2 <<EOF
+Usage: $0 [OPTIONS]
+
+  Plugin Options:
+    --cmake=PATH               Path to CMake binary
+    --zeek-dist=DIR            Path to Zeek source tree
+    --install-root=DIR         Path where to install plugin into
+    --with-binpac=DIR          Path to BinPAC installation root
+    --with-broker=DIR          Path to Broker installation root
+    --with-bifcl=PATH          Path to bifcl executable
+    --enable-debug             Compile in debugging mode
+    --disable-cpp-tests        Don't build C++ unit tests
+EOF
+
+    if type plugin_usage >/dev/null 2>&1; then
+        plugin_usage 1>&2
+    fi
+
+    echo
+
+    exit 1
+}
+
+# Function to append a CMake cache entry definition to the
+# CMakeCacheEntries variable
+#   $1 is the cache entry variable name
+#   $2 is the cache entry variable type
+#   $3 is the cache entry variable value
+append_cache_entry() {
+    CMakeCacheEntries="$CMakeCacheEntries -D $1:$2=$3"
+}
+
+# set defaults
+builddir=build
+zeekdist=""
+installroot="default"
+zeek_plugin_begin_opts=""
+CMakeCacheEntries=""
+
+while [ $# -ne 0 ]; do
+    case "$1" in
+        -*=*) optarg=$(echo "$1" | sed 's/[-_a-zA-Z0-9]*=//') ;;
+        *) optarg= ;;
+    esac
+
+    case "$1" in
+        --help | -h)
+            usage
+            ;;
+
+        --cmake=*)
+            CMakeCommand=$optarg
+            ;;
+
+        --zeek-dist=*)
+            zeekdist=$(cd $optarg && pwd)
+            ;;
+
+        --install-root=*)
+            installroot=$optarg
+            ;;
+
+        --with-binpac=*)
+            append_cache_entry BinPAC_ROOT_DIR PATH $optarg
+            binpac_root=$optarg
+            ;;
+
+        --with-broker=*)
+            append_cache_entry BROKER_ROOT_DIR PATH $optarg
+            broker_root=$optarg
+            ;;
+
+        --with-bifcl=*)
+            append_cache_entry BifCl_EXE PATH $optarg
+            ;;
+
+        --enable-debug)
+            append_cache_entry BRO_PLUGIN_ENABLE_DEBUG BOOL true
+            ;;
+
+        --disable-cpp-tests)
+            zeek_plugin_begin_opts="DISABLE_CPP_TESTS;$zeek_plugin_begin_opts"
+            ;;
+
+        *)
+            if type plugin_option >/dev/null 2>&1; then
+                plugin_option $1 && shift && continue
+            fi
+
+            echo "Invalid option '$1'.  Try $0 --help to see available options."
+            exit 1
+            ;;
+    esac
+    shift
+done
+
+if [ -z "$CMakeCommand" ]; then
+    # prefer cmake3 over "regular" cmake (cmake == cmake2 on RHEL)
+    if command -v cmake3 >/dev/null 2>&1; then
+        CMakeCommand="cmake3"
+    elif command -v cmake >/dev/null 2>&1; then
+        CMakeCommand="cmake"
+    else
+        echo "This plugin requires CMake, please install it first."
+        echo "Then you may use this script to configure the CMake build."
+        echo "Note: pass --cmake=PATH to use cmake in non-standard locations."
+        exit 1
+    fi
+fi
+
+if [ -z "$zeekdist" ]; then
+    if type zeek-config >/dev/null 2>&1; then
+        zeek_config="zeek-config"
+    else
+        echo "Either 'zeek-config' must be in PATH or '--zeek-dist=<path>' used"
+        exit 1
+    fi
+
+    append_cache_entry BRO_CONFIG_PREFIX PATH $(${zeek_config} --prefix)
+    append_cache_entry BRO_CONFIG_INCLUDE_DIR PATH $(${zeek_config} --include_dir)
+    append_cache_entry BRO_CONFIG_PLUGIN_DIR PATH $(${zeek_config} --plugin_dir)
+    append_cache_entry BRO_CONFIG_LIB_DIR PATH $(${zeek_config} --lib_dir)
+    append_cache_entry BRO_CONFIG_CMAKE_DIR PATH $(${zeek_config} --cmake_dir)
+    append_cache_entry CMAKE_MODULE_PATH PATH $(${zeek_config} --cmake_dir)
+
+    build_type=$(${zeek_config} --build_type)
+
+    if [ "$build_type" = "debug" ]; then
+        append_cache_entry BRO_PLUGIN_ENABLE_DEBUG BOOL true
+    fi
+
+    if [ -z "$binpac_root" ]; then
+        append_cache_entry BinPAC_ROOT_DIR PATH $(${zeek_config} --binpac_root)
+    fi
+
+    if [ -z "$broker_root" ]; then
+        append_cache_entry BROKER_ROOT_DIR PATH $(${zeek_config} --broker_root)
+    fi
+else
+    if [ ! -e "$zeekdist/zeek-path-dev.in" ]; then
+        echo "$zeekdist does not appear to be a valid Zeek source tree."
+        exit 1
+    fi
+
+    # BRO_DIST is the canonical/historical name used by plugin CMake scripts
+    # ZEEK_DIST doesn't serve a function at the moment, but set/provided anyway
+    append_cache_entry BRO_DIST PATH $zeekdist
+    append_cache_entry ZEEK_DIST PATH $zeekdist
+    append_cache_entry CMAKE_MODULE_PATH PATH $zeekdist/cmake
+fi
+
+if [ "$installroot" != "default" ]; then
+    mkdir -p $installroot
+    append_cache_entry BRO_PLUGIN_INSTALL_ROOT PATH $installroot
+fi
+
+if [ -n "$zeek_plugin_begin_opts" ]; then
+    append_cache_entry ZEEK_PLUGIN_BEGIN_OPTS STRING "$zeek_plugin_begin_opts"
+fi
+
+if type plugin_addl >/dev/null 2>&1; then
+    plugin_addl
+fi
+
+echo "Build Directory        : $builddir"
+echo "Zeek Source Directory   : $zeekdist"
+
+mkdir -p $builddir
+cd $builddir
+
+"$CMakeCommand" $CMakeCacheEntries ..
+
+echo "# This is the command used to configure this build" >config.status
+echo $command >>config.status
+chmod u+x config.status

devel/plugins/event-metadata-plugin-src/scripts/__load__.zeek

@@ -0,0 +1,11 @@
+module EventLatency;
+
+redef enum EventMetadata::ID += {
+	## Identifier for the absolute time at which Zeek published this event.
+	WALLCLOCK_TIMESTAMP = 10001000,
+};
+
+event zeek_init()
+	{
+	assert EventMetadata::register(WALLCLOCK_TIMESTAMP, time);
+	}

devel/plugins/event-metadata-plugin-src/scripts/__preload__.zeek

@@ -0,0 +1 @@
+# Empty

devel/plugins/event-metadata-plugin-src/src/Plugin.cc

@@ -0,0 +1,65 @@
+
+#include "Plugin.h"
+
+#include <zeek/Event.h>
+#include <zeek/Val.h>
+#include <zeek/cluster/Backend.h>
+#include <zeek/plugin/Plugin.h>
+#include <zeek/telemetry/Manager.h>
+
+namespace plugin {
+namespace Zeek_EventLatency {
+Plugin plugin;
+}
+} // namespace plugin
+
+using namespace plugin::Zeek_EventLatency;
+
+zeek::plugin::Configuration Plugin::Configure() {
+    zeek::plugin::Configuration config;
+    config.name = "Zeek::EventLatency";
+    config.description = "Track remote event latencies";
+    config.version = {0, 1, 0};
+    EnableHook(zeek::plugin::HOOK_PUBLISH_EVENT);
+    EnableHook(zeek::plugin::HOOK_QUEUE_EVENT);
+    return config;
+}
+
+void Plugin::InitPostScript() {
+    double bounds[] = {0.0002, 0.0004, 0.0006, 0.0008, 0.0010, 0.0012, 0.0014, 0.0016, 0.0018, 0.0020};
+    histogram =
+        zeek::telemetry_mgr->HistogramInstance("zeek", "cluster_event_latency_seconds", {}, bounds, "event latency");
+}
+
+bool Plugin::HookPublishEvent(zeek::cluster::Backend& backend, const std::string& topic,
+                              zeek::cluster::detail::Event& event) {
+    static const auto& wallclock_id = zeek::id::find_val<zeek::EnumVal>("EventLatency::WALLCLOCK_TIMESTAMP");
+
+    auto now_val = zeek::make_intrusive<zeek::TimeVal>(zeek::util::current_time(/*real=*/true));
+
+    if ( ! event.AddMetadata(wallclock_id, now_val) )
+        zeek::reporter->FatalError("failed to add wallclock timestamp metadata");
+
+    return true;
+}
+
+bool Plugin::HookQueueEvent(zeek::Event* event) {
+    static const auto& wallclock_id = zeek::id::find_val<zeek::EnumVal>("EventLatency::WALLCLOCK_TIMESTAMP");
+
+    if ( event->Source() == zeek::util::detail::SOURCE_LOCAL )
+        return false;
+
+    auto timestamps = event->MetadataValues(wallclock_id);
+
+    if ( timestamps->Size() > 0 ) {
+        double remote_ts = timestamps->ValAt(0)->AsTime();
+        auto now = zeek::util::current_time(/*real=*/true);
+        auto latency = std::max(0.0, now - remote_ts);
+
+        histogram->Observe(latency);
+    }
+    else
+        zeek::reporter->Warning("missing wallclock timestamp metadata");
+
+    return false;
+}

devel/plugins/event-metadata-plugin-src/src/Plugin.h

@@ -0,0 +1,29 @@
+
+#pragma once
+
+#include <zeek/plugin/Plugin.h>
+#include <zeek/telemetry/Histogram.h>
+
+namespace plugin {
+namespace Zeek_EventLatency {
+
+class Plugin : public zeek::plugin::Plugin {
+protected:
+    // Overridden from zeek::plugin::Plugin.
+    zeek::plugin::Configuration Configure() override;
+
+    void InitPostScript() override;
+
+    bool HookPublishEvent(zeek::cluster::Backend& backend, const std::string& topic,
+                          zeek::cluster::detail::Event& event) override;
+
+    bool HookQueueEvent(zeek::Event* event) override;
+
+private:
+    zeek::telemetry::HistogramPtr histogram;
+};
+
+extern Plugin plugin;
+
+} // namespace Zeek_EventLatency
+} // namespace plugin