Skip to content

PLANCTL

NAME

1
planctl : start or stop you plans

SYNOPSIS

1
 planctl start --plan myplan.hjson --template punchline.template

DESCRIPTION

The planctl command is used internally by the shiva application scheduler to start or stop plans. Plans are applications that are scheduled periodically, refer to the punch reference guide for details.

planctl is also available as a command line tool to let you run a plan in foreground from a terminal. This is mainly useful on a standalone for developping your plans. It is alse available from the punch operator terminals on production platforms.

This command works in two ways. To start an interactive shell, simply launch

planctl --tenant <tenant_name>

Where <tenant_name> is a tenant name. From there, follow the documented commands. Use the TAB character to get auto-completion.

Alternatively you can execute commands in non interactive mode using the following syntax:

planctl start --plan myplan.hjson --template punchline.template

Plans are resilient and internally save so-called cursors. Cursors keep track of the progress of the executed application. Should a server crash, the plan will resume from another one, and the application will be scheduled again from the last saved cursor. Think of a cursor much the same way as a kafka offset. Instead of keep track of an offset in a queue, plans keep track of the last time of a succesful application execution.

OPTIONS

  • start

    • Restart a plan.
  • reset_cursor

    • Use an inline punchlet code, Start channels and jobs.
  • list_cursor

    • Stop channels or jobs.

EXAMPLES

Here are some self explanatory examples. To list the current cursors:

planctl list-cursor --plan-id my_plan \
                   --es_cluster es_search \
                   --index-name-pattern platform-plan-cursor

To manually reset a cursor:

planctl reset-cursor --plan-id my_plan \
                   --es_cluster es_search \
                   --index-name-pattern platform-plan-cursor \
                   --restart-date XXXX-YY-ZZT16:28:14.702Z

An example of plan executing other things than a punchline:

Plan can now run any kind of application:

planctl start \
    --runtime user_defined \
    --plan plan.hjson \
    --template template.hjson \
    --user-defined argument1 \
    --user-defined argument2

# note: interpreter that will be used if not specified will be -> /bin/sh
# for various reason, in case you wish to modify the interpreter that will be used for executing your
# templated file, you may add the --intepreter $ABSOLUTE_PATH_TO_EXECUTABLE or make use of SHEBANG header

planctl start \
    --runtime user_defined \
    --plan plan.hjson \
    --template template.hjson \
    --user-defined argument1 \
    --user-defined argument2 \
  --interpreter /bin/sh

With:

plan.hjson

{
  version: "6.0"
  name: basic_user
  model:{
    metric_index: mytenant-metrics
    plan_logs_index: platform-plan-logs*
    input_index: mytenant-events-*
    dates: {
       day: {
         offset: -PT1m
         format: yyyy.MM.dd
       }
       from: {
         offset: -PT1m
         format: yyyy-MM-dd'T'HH:mmZ
       }
       to: {
         format: yyyy-MM-dd'T'HH:mmZ
       }
    }
  }
  settings: {
    cron: "*/1 * * * *"
    persistence: [
      {
        type: elasticsearch
        index_name: mytenant-plan-cursor
      }
    ]
  }
  metrics: {
    reporters: [
      {
        type: kafka
      }
    ]
  }
}

template.hjson

#!/bin/sh -

echo "HELLO WORLD FROM={{from}} TO={{to}} $@"

Using a python interpreter

Your template may look like this:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-


if __name__ == "__main__":
    print(f"HELLO WORLD python :) FROM={{from}} TO={{to}}")

New command to use:

planctl start \
    --runtime user_defined \
    --plan plan.hjson \
    --template template.hjson \
    --user-defined argument1 \
    --user-defined argument2 \
  --interpreter /usr/bin/python3

LIBRARIES

planctl uses the library located :

  • $PUNCHPLATFORM_INSTALL_DIR/lib/punch-command-app-*with-dependencies.jar

LOGGERS

The logging verbosity of planctl is controlled by the following two files:

  • $PUNCHPLATFORM_LOG4J_CONF_DIR/log4j2-punchline.xml
  • $PUNCHPLATFORM_LOG4J_CONF_DIR/log4j2.properties

ENVIRONMENT

planctl is only executed in the context of the operator terminal environment.

SEE ALSO

punchlinectl channeltcl environment