Skip to content

Quick Start

Use Padas to perform streaming event data transformations and apply specific rules to filter out sample data. This quick start guide assumes all components (Confluent Kafka and Padas) will be installed on the same machine. In production, it is recommended to separate out these components on different nodes/hosts.

Prerequisites

  • Internet connectivity
  • Review System Requirements
  • Kafka (Apache, Confluent Community, etc.) must be installed and running (locally) (e.g. Quick Start for Confluent Platform).
  • You should have at least Kafka Broker and Controller (or Zookeeper) services up and running. 
    confluent local services status
...
Kafka is [UP]
ZooKeeper is [UP]
...


Overview of Quickstart

Below diagram shows what will be accomplished with this quick start guide.

We will play with some mock data such as the following. Our goal will be to transform sample event data and apply a set of rules to generate alerts.

Sample input: 

{
  "user": "user_1",
  "group_id": 5,
  "action": "success"
}

We will have a couple of simple rules that will trigger when group_name (soon to be enriched field) matches "evil*" or when action results in failure.

NOTE: For the purposes of demo, the goal is carried with multiple tasks, where as a simple FILTER function can be utilized as well.

Step 1: Acquiring Padas

  1. Contact with us to get the latest version of Padas Engine and UI components applicable to your platform. 

    padas-engine-1.0.0.tgz
padas-ui-1.0.0-linux-x64.tgz (or darwin)

  2. Use the tar command to decompress the archive file

    tar -xzf padas-engine-1.0.0.tgz
tar -xzf padas-ui-1.0.0-linux-x64.tgz (or darwin)

  3. After extraction, combine the two padas folders. By default, two padas directories are created:
    One containing the ui folder
    The other containing the engine folder

    To organize them into a single padas directory, use the following structure:

    padas/
├── engine/    # Contents of padas-engine
└── ui/        # Contents of padas-ui

  4. By default, Padas Engine expects Kafka to be running on localhost. If that's not the case, edit padas/engine/etc/padas.properties accordingly. If the padas.properties file does not exist, copy the padas.properties.example file to create it.

Step 2: Start Engine

At this stage, make sure you have Confluent Kafka is running as mentioned in prerequisites.

  1. Start engine node on the console. The script will ask you to accept the license agreement (enter y or yes) 

    cd padas/engine

    bin/padas start-console
PADAS SOFTWARE LICENSE AGREEMENT
...
Displayed Padas Software License Agreement contents can also be found at https://padas.io/legal/eula.html OR in file /<YOUR INSTALL DIR>/padas/etc/license.txt
Do you agree with this license? [y/n]: y
INFO  Verifying Kafka broker connection...
INFO  Successfully verified Kafka Cluster connection.
INFO  Successfully verified existence of all required topics.
INFO  Starting web interface at https://<HOSTNAME>:8999 ...


  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@:**@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@@@@:****:@@@@@@@@@@@**:****@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@@**********:::**********@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@:***********************@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@************************:@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@**************************@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@*****************************@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@********************************&@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@#***********************************::@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@**:************************************@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@******************************@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@&*@@@@@@@@@@*************************@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@:**********@@@@@@@@@@@***********************@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@***********:@@@@@@@@@@@@********************o@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@***********@@@@@@@@@@@@@*******************:@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  **************o@@@@@@@@@@@@@*******************:@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  **************@@@@@@@@@@@@@********************:@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @:::o:********@@@@@@@@@@@@:********************:@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@o*******@@@@@@@@@@**************o@@@#****8@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@*******:@@@@@@@:***********@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@8
  @@@@@@@@**********:@**************@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*
  @@@@@@@:*****************************:8@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&
  @@@@@@:***********************************@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@:@
  @@@@@@o****************************************@@@@@@@@@@@@@@@@@@@@@@@@@:*@@
  @@@@@@o********************************************:*@@@@@@@@@@@@@@@@@:**@@@
  @@@@@@@@@******************************@::****************************:@@@@@
  @@@@@@@@@@*@@:******#@@@@@@@@@*********@@@@@@@@8**:****************@@@@@@@@@
  @@@@@@@@@*****@@*****:8@@@@@@@@@8*********@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@*****@@@:******@@@@@@@@@@@@:*****@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@****&@@@@@@*****@@@@@@@@@@@@@@****@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@**@@@****@@@@@@@@#***#@@@@@@@@@@@@@@****@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@******:***@@@@@@@@***@@@@@@@@@@@@@@@****@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@:&@@@@@@@@@@::@@*****:o@@@@@@@o***********@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@:*****8#@:*#@@@@@@8*@*8@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@&@*@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

  ____   _    ____    _    ____
 |  _ \ / \  |  _ \  / \  / ___|
 | |_) / _ \ | | | |/ _ \ \___ \
 |  __/ ___ \| |_| / ___ \ ___) |
 |_| /_/   \_\____/_/   \_\____/

INFO  Starting App using Java 11.0.10 on <HOSTNAME> with PID 32965 (/<YOUR INSTALL DIR>/padas/libs/padas-0.0.1.jar started by selim in /<YOUR INSTALL DIR>/padas)
INFO  No active profile set, falling back to default profiles: default
INFO  Started App in 12.536 seconds (JVM running for 66.174)

    NOTE: If Padas is configured to utilize Kafka (padas.config.store=kafka in properties file) to store configurations you will need to create the required topics (configuration namespaces). If not, you will receive a warning as following on the console. 

    ...
WARN  Unable to describe required topics for Padas.  Please create these topics in order to run the engine.
...

Step 3: Start UI

  1. Start UI component on the console. Default configuration connects to localhost for Padas Engine. 

    cd padas/ui

    bin/padas-ui start-console
[HPM] Proxy created: /api  -> https://<PADAS ENGINE HOST>:8999

  2. Initialize User: Go to https://localhost:9000 and since this is the first time, click the link below and create an administrator user.

  3. Login: After initial user creation you will be redirected to Login screen; Login with the newly created user credentials.

Step 4: Configuration & Namespaces

By default, all configuration is stored locally and the user does not have to take any action other than editing desired configuation from Padas UI.

Step 5: Configure Padas

Option 1: Configure Padas Using Stream Configs JSON File

For Stream Configs upload PadasQuickStartStreamConfigurations.json

To configure the stream settings, follow the steps below:

  1. Navigate to Stream Configs.
  2. Click on the Upload button. This will open a dialog window.

3. In the dialog, select the file PadasQuickStartStreamConfigurations.json from your local system.

4. Once selected, click the Upload button.

Upon a successful upload, the following components will be configured automatically:
- Rules
- Tasks
- Pipeline
- Topology

Option 2: Configure Padas Manually

The following steps will guide you on how to manually create the necessary configuration items instead of uploading a JSON file.

1. Create Rules

  • Click on the Create New dropdown and select Rule.
  • Fill in the fields in the dialog as shown in the examples below.

  • Click on Create Rule.
  • Repeat this process to create 2 rules.

2. Create Tasks

  • Click on the Create New dropdown and select Task.
  • Fill in the fields in the dialog as shown in the examples below.

  • Click on Create Task.
  • Repeat this process to create 2 tasks.

First one will simply perform some enrichment and add a new field group_name based on a condition. The second one will run all selected PDL rules.

3. Create a Pipeline

  • Click on the Create New dropdown and select Pipeline.
  • Fill in the fields in the dialog as shown in the example below.

  • Click on Create Pipeline.

Note that the output of a task becomes an input for the following task in the pipeline.

4. Create a Topology

Create a topology with the above pipeline that reads from test_input topic and writes to test_output topic.

  • Click on the Create New dropdown and select Topology.
  • Fill in the fields in the dialog as shown in the example below.

  • Click on Create Topology.

    keySerde: topic key SerDe, if not specified default is "org.apache.kafka.common.serialization.Serdes$StringSerde".

    valueSerde: topic value SerDe, if not specified default is "org.apache.kafka.common.serialization.Serdes$StringSerde".

5. Restart Node

Option 1: From Console

Once a new topology is created we need to let Padas Engine know about it by restarting the node. You can do this from the console (CTRL-C and start, or stop/start the service, etc.)

Option 2: From UI

You can also do this from the UI from Engines menu, click Start button and you should see the state change to RUNNING for this node.

Step 6: Test & Play

Option 1: Testing with Padas UI

  1. Navigate to the Test Page: Open your web browser and access the Padas UI. Once logged in, locate and click on the "Test" option in the navigation to open the Test page.

  2. Configure and Run Your Test: On the Test page, locate the dropdown menu for selecting a Test Function and choose "pipeline" as it pertains to our example. In the provided field, paste the sample event data that corresponds to the pipeline function you are testing. Click the "Test" button.

    {"user": "user_1","group_id": 5,"action": "success", "user": "user_1","group_id": 1,"action": "success", "user": "user_1","group_id": 1,"action": "failure"}

Option 2: Testing using Kafka CLI Tools

  1. Generate Data: Let's generate a few sample event with a simple JSON message. Note that the last 2 events will match the rules specified above. 

    echo '{"user": "user_1","group_id": 5,"action": "success"}' |  kafka-console-producer --bootstrap-server localhost:9092 --topic test_input
echo '{"user": "user_1","group_id": 1,"action": "success"}' |  kafka-console-producer --bootstrap-server localhost:9092 --topic test_input
echo '{"user": "user_1","group_id": 1,"action": "failure"}' |  kafka-console-producer --bootstrap-server localhost:9092 --topic test_input

  2. View output: Once the sample event is ingested, rules for matching datamodels in real-time and populate padas_alerts topic with matching event and alert information. You can simply view this alert with the following command:

    kafka-console-consumer --bootstrap-server localhost:9092 --topic test_output --from-beginning | jq

    Output will be similar to the following, this example output is from the last input from above. Note the use of jq above for pretty display of JSON data. 

    {
  "user": "user_1",
  "group_id": 1,
  "action": "failure",
  "group_name": "evil group",
  "padasRule":
  {
    "id": "test_rule_for_evil",
    "name": "Test Rule for Evil",
    "description": "Match for group name that starts with evil",
    "pdl": "group_name=\"evil*\"",
    "datamodel": "mydata",
    "annotations": [
      "T1234",
      "T2345"
    ]
  }
}

{
  "user": "user_1",
  "group_id": 1,
  "action": "failure",
  "group_name": "evil group",
  "padasRule":
  {
    "id": "test_rule_for_failure",
    "name": "Test Rule for Failure",
    "description": "Match when action is failure",
    "pdl": "action=\"failure\"",
    "datamodel": "mydata",
    "annotations": [
      "T9876"
    ]
  }
}

Next Steps