zeek/src/script_opt/CPP

Compiling Zeek Scripts To C++: User's Guide

Overview - Workflows - Known Issues -

Overview

Zeek's script compiler is an experimental feature that translates Zeek scripts into C++, which is then compiled directly into the zeek binary in order to gain higher performance by removing the need for Zeek to use an interpreter to execute the scripts. Using this feature requires a somewhat complex workflow.

How much faster will your scripts run? There's no simple answer to that. It depends heavily on several factors:

• What proportion of the processing during execution is spent in Zeek's Event Engine rather than executing scripts.

• What proportion of the script's processing is spent executing built-in functions (BiFs). It might well be that most of your script processing actually occurs inside the Logging Framework, for example, and thus you won't see much improvement.

• Those two factors add up to gains often on the order of only 10-15%, rather than something a lot more dramatic. On the other hand, using this feature you can afford to put significantly more functionality in Zeek scripts without worrying as much about introducing performance bottlenecks.

That said, I'm very interested in situations where the performance gains appear unsatisfying. Also note that when using the compiler, you can analyze the performance of your scripts using C++-oriented tools - the translated C++ code generally bears a clear relationship with the original Zeek script.

If you want to know how the compiler itself works, see the sketch at the beginning of Compile.h.

Workflows

Before building Zeek, see the first of the Known Issues below regarding compilation times. If your aim is to exploration of the functionality rather than production use, you might want to build Zeek using ./configure --enable-debug, which can reduce compilation times by 50x (!). Once you've built it, the following sketches how to create and use compiled scripts.

The main code generated by the compiler is taken from build/CPP-gen.cc. An empty version of this is generated when first building Zeek.

As a user, the most common workflow is to build a version of Zeek that has a given target script (target.zeek) compiled into it. This means all of the code pulled in by target.zeek, including the base scripts (or the "bare" subset if you invoke the compiler when running zeek -b). The following workflow assumes you are in the build/ subdirectory:

1. ./src/zeek -O gen-C++ target.zeek
   The generated code is written to CPP-gen.cc.
2. ninja or make to recompile Zeek
3. ./src/zeek -O use-C++ target.zeek
   Executes with each function/hook/event handler pulled in by target.zeek replaced with its compiled version.

Instead of the last line above, you can use the following variants:

3. ./src/zeek -O report-C++ target.zeek
   For each function body in target.zeek, reports which ones have compiled-to-C++ bodies available, and also any compiled-to-C++ bodies present in the zeek binary that target.zeek does not use. Useful for debugging.

The above workflows require the subsequent zeek execution to include the target.zeek script. You can avoid this by replacing the first step with:

1. ./src/zeek -O gen-standalone-C++ --optimize-files=target.zeek target.zeek >target-stand-in.zeek

(and then building as in the 2nd step above). This option prints to stdout a (very short) "stand-in" Zeek script that you can load using target-stand-in.zeek to activate the compiled target.zeek without needing to include target.zeek in the invocation (nor the -O use-C++ option). After loading the stand-in script, you can still access types and functions declared in target.zeek.

Note: gen-standalone-C++ must be used with --optimize-files, as the compiler needs the latter to determine which global declarations the standalone code needs to initialize.

There are additional workflows relating to running the test suite: see src/script_opt/CPP/maint/README.

Known Issues

Here we list various known issues with using the compiler:

• Compilation of compiled code can be quite slow when the C++ compilation includes optimization, taking many minutes on a beefy laptop. This slowness complicates CI/CD approaches for always running compiled code against the test suite when merging changes.

• Run-time error messages generally lack location information and information about associated expressions/statements, making them hard to puzzle out. This could be fixed, but would add execution overhead in passing around the necessary strings / Location objects.

• To avoid subtle bugs, the compiler will refrain from compiling script elements (functions, hooks, event handlers) that include conditional code. In addition, when using --optimize-files it will not compile any functions appearing in a source file that includes conditional code (even if it's not in a function body). You can override this refusal with -O allow-cond.

• Code compiled with -O gen-standalone-C++ will not execute any global statements when invoked using the "stand-in" script. The right fix for this is to shift from encapsulating global statements in a pseudo-function, as currently done, to instead be in a pseudo-event handler.

• Code compiled with -O gen-standalone-C++ likely has bugs if that code requires initializing a global variable that specifies extending fields in an extensible record (i.e., fields added using redef).

• If a lambda generates an event that is not otherwise referred to, that event will not be registered upon instantiating the lambda. This is not particularly difficult to fix.

• A number of steps could be taken to increase the performance of the optimized code. These include:

  1. Switching the generated code to use the new ZVal-related interfaces, including for vector operations.
  2. Directly calling BiFs rather than using the Invoke() method to do so. This relates to the broader question of switching BiFs to be based on a notion of "inlined C++" code in Zeek functions, rather than using the standalone bifcl BiF compiler.
  3. Switching the Event Engine over to queuing events with ZVal arguments rather than ValPtr arguments.
  4. Making the compiler aware of certain BiFs that can be directly inlined (e.g., network_time()), a technique employed effectively by the ZAM compiler.
  5. Inspecting the generated code for inefficiencies that the compiler could avoid.