Quickstart

Downloading the Executable

The latest version is available here:

Download Hotrod

Depending on your platform, the download will provide you with either a gzip or zip file, containing the executable.

See the installation guide for instructions on verifying and extracting the executable.

Running in Server

Once extracted and renamed, go to a terminal and start the Server. On Linux, Windows, and pre-M1 Macs, use:

$> ./hotrod run server

On Macs running a M1 or later CPU, use:

$> arch -x86_64 ./hotrod run server

Upon the first run, you'll be presented with the Panoptix EULA (End User License Agreement).

In the default configuration, the web-based UI and API will be served at http://localhost:3000. If the default port is already in use, change the port as required:

$> ./hotrod run server --bind-address localhost:3001

If you accepted the EULA, the Server will start with the following output:

In the log, you'll notice:

1. A randomly generated password, e.g., pHaII2r7vVVk.

2. The URL for the web-based UI.

Security

Remember your password. Change it as soon as possible!

Logging into the UI

In a browser, go to http://localhost:3000 (or the relevant port) to log in:

Use the following credentials:

1. The default username is admin.

2. The password that was previously generated.

The password must be changed thereafter.

Once logged in, the Dashboard will indicate one online Agent — the Server built-in Agent.

Creating your first Pipe

Click Pipes in the navbar:

Click NEW PIPE to create a new Pipe:

Name the new Pipe and click CREATE:

Thereafter, the Pipe editor appears.

The Pipe definition field, located on the lefthand side, features a minimal Pipe template, containing the standard elements of a Pipe definition:

1. A mandatory Pipe name.

name: new_pipe

2. An input.

input:
  echo:
    json: true
    ignore-linebreaks: true
    event: |
      {"input": "sample"}

3. A list of actions.

actions:
  - add:
      output-fields:
      - output: sample

4. An output.

output:
  print: STDOUT

Validating Pipe Definitions

Click Validate to check the Pipe definition. The validation function checks for YAML syntax errors and Pipe Language errors. A notification will appear in the Result field to indicate whether the Pipe definition is valid or if there any YAML or Pipe Language issues.

Evaluating Sample Input

To evaluate the Pipe against the input, click Play. If successful, you will receive a green notification with confirmation that the Pipe has been successfully evaluated.

The default Pipe template contains an echo input. The editor automatically copies the event data into the Evaluation input tab.

note

If there's an error, you will receive a red notification indicating, e.g., that the sample input for evaluation is blank. In this case, you will notice an error message in the Result field with a link to provide input.

Viewing Sample Output Against Input

To view a sample of the Pipe output, click Evaluation input.

Under the Evaluation input view, you can:

1. Type or paste a sample in the Input field.
2. Click Play.
3. Inspect the result in the Output field as shown below.

Hello World!

Let’s create a field named hello with the value of world. We do this by changing the echo input event field through using actions.

First, remove the two existing fields by adding a remove action to the bottom of the actions section in the Pipe definition:

  - remove: 
      fields:
       - input
       - output

Follow these steps:

1. Type or paste the remove action into the Pipe definition field.
2. Click Play.
3. Notice an empty event displayed in the Result field, indicating that the fields were successfully removed.

Finally, to add the hello field with the value world, create the following action in the Pipe definition:

  - add:
      output-fields:
      - hello: "world"

Follow these steps:

1. Type or paste the add action in the Pipe definition
2. Click Play.
3. Notice "hello": "world" being displayed in the Result field.

You are then able to:

1. Click Save.
2. Click Pipes to go back to the Pipes list.

Once back in the Pipes list, you'll notice Pipes (1) displayed along with data about the Pipe.

Click on the Pipe name to enter the Pipe view as indicated below:

Adding a Pipe to an Agent

Once in the Pipe view, you can view information about the Pipe.

You will notice the Built-in Agent under the Agents available (1) section. To add the new Pipe to the built-in Agent, click ADD next to the Agent name.

Then, go to the terminal where the Server is running. You should see the Pipe output towards the end of the output:

{"hello":"world"}

There are two reasons why we're seeing the Pipe output in the Server output:

1. The Pipe uses print output, to STDOUT.
2. The Pipe is executed by the built-in Agent within the running Server process.

Adding an Interval to the Pipe

Click EDIT to return to the Pipe editor.

Thereafter, add the interval field to the Pipe definition:

input:
  echo:
    interval: 1s

Follow these steps:

1. Type or paste the interval: 1s field.
2. Click Save.
3. Close the Pipe editor by clicking Close.

Within a few moments, {"hello":"world"} should appear in the terminal. This should appear every few seconds as per the specified execution interval: 1s that we have added.

note

When saving a Pipe definition, the Server automatically redeploys updated Pipe definitions to all Agents that the Pipe is attached to.

Take note of the following in the Pipe view:

1. Notice the Pipe Status displaying STARTED.
2. Click on Dashboard to view the Agent Status.

On the Dashboard, notice the Agent status. DEPLOYED PIPES has a count of 1. Click on the Agent name to view the Agent.

Running a Trace

In the Agent view, you will notice information such as Agent details, Pipes deployed to the Agent, and Pipe status etc. Since Metrics and Logging are disabled at this stage, click EDIT SETTINGS to enable them.

Inside Update Agent Settings:

1. Set Poll interval and Metrics interval values (in seconds) to 1.
2. Enable Metrics and Logging by setting their respective slider to on.
3. Click Save.

Once saved, you'll return to the Agent view where you can click on one of the Pipe links to go directly to the Pipe view again.

At the bottom of the page, in the Pipe view, click TRACE.

On the next page, set the amount of trace samples using the slider, then click START TRACE to run the trace.

This initiates a trace whereby the Agent starts collecting the given number of event samples and sends them to the Server.

The UI will wait until the Server has collected at least one sample and will then display the trace results:

Notice that trace output includes the input and output data for each input, action, and output in the Pipe.

Traces are an essential diagnostic feature that can be used to view what a Pipe is doing during execution.

Next, click on the Pipe link to return to the Pipe view.

Stopping a Pipe

In the Pipe view, stop the Pipe by clicking REMOVE:

Within a few moments, the Agent will stop the Pipe and notify the Server that it is no longer executing the Pipe in question.

A complete installation guide is available for deployment on the Ubuntu LTS distribution.