Skip to content

Applicative Administration Commands

Abstract

The punchplatform provides its users with very few concepts to understand, and a minimal set of commands. This chapter go through the essentials for everyday administration when you operate or troubleshoot your applicatios and punchlines. More "platform/component" oriented commands are documented in Components administration commands.

For most of commands operating on data processing punchlines/applications, you will need to specify the specific tenant on which you want to apply a change.

The file system configuration folder layout has a REST-like tree organisation starting with the tenant name, then have sub folders for channels and books. In channels and books folders are stored the application configuration files.

  • Platform services managed using the platformctl and kafkactl tools. For everyday operation, this is most helpful to provide easily a view of the platform framewor components health. For more commands related to the platform software framework components, refer to Components administration commands.
  • Channels contain your ever running applications. You act upon a channel using the channelctl commands : start, stop reload.
  • Books contain application worflows. You act upon a book using the bookctl commands : start, stop reload.
  • Applications can be individually started or stopped using the --application command option provided by channelctland bookctl.

Platform Commands

Your platform health can be in one of three states.

State Meaning
GREEN Your platform is in nominal condition. All its components are green as well.
YELLOW Some of the platform component(s) are in degraded condition yet can provide its service.
RED Some of the platform component(s) are not capable of ensuring its service.

Use the platformctl to query or act upon your platform. Note that on a secure platform, platformctl will automatically leverage the required credentials. The followings commands are available:

Platform Health Check

Refer to

platformctl health 

Platform Status

Simply type in

platformctl status 

Configuration Backup Restore

It is strongly advised to save your configuration files preferably using a git repository to ensure traceability and configuration rollback. You should then always commit and push the updated reference configuration of your platform to your central git repository for configuration management.

The punch provides an additional backup restore facility to back up restore all your tenants configuration files. This function requires a Kafka cluster. To back up your tenants configuration tree:

platformctl backup --cluster common

To restore your configuration :

platformctl restore --cluster common --destination /tmp

The restored tenants folder will be written in the provided output folder (here /tmp). If you want to restore it in your configuration folder type in:

platformctl restore --cluster common --destination $PUNCHPLATFORM_CONF_DIR

In which case the previous configuration will be moved to a tenants.<timestamp>.sav folder for you to ensure you did not make a mistake.

Backup-restore requires a topic be created upfront. On production platforms use for example the following command:

kafkactl create-topics --topic platform-tenants-backups --cluster common --replication-factor 3

The kafkactlcommand is described hereafter.

Kafka Commands

Kafka plays a key role both for administrative internal punch services and your applicative pipelines. The punch provides a dedicated kafkactlcommand to make it easy to check or manage the kafka topics used by these various services.

List Kafka Topics

kafkactl --list-topics

Describe Kafka Topics

kafkactl --describe-topics

Describe Consumer Groups

This command is useful to check who (i.e. which service or application) is listening to which topic. Refer to

kafkactl --describe-consumer-groups --help

Create Kafka Topics

Refer to

kafkactl --create-topics --help

Delete Kafka Topics

Refer to

kafkactl --delete-topics --help

Channel Commands

The runtime status of a channel is one of the following.

State Meaning
ACTIVE the channel or service is running in nominal condition.
STOPPED the channel or service is stopped.
PARTIAL this is a non nominal situation. One of your channel application is not running anymore, most probably because an operator stopped it using an external or cli command
OUT_OF_SYNC This indicates that one of the channel configuration file was changed after the channel was started.

The basic operations are to start stop or reload one or several channels.

Channel Status Check

channelctl --tenant yourtenant status
The status of a single channel can be queried using:
channelctl --tenant mytenant status --channel mychannel
The various configuration files can be edited using standard file editors. Changing a configuration file has no effect until you restart the corresponding channel(s).

The punch stores a snapshot of the runtime status channels in a configuration store. You can have a look at the configuration store for a tenant using the following command:

channelctl --tenant yourtenant describe

Info

The configuration store is either a filesystem (on development or one node punch) or Kafka (on distributed punch).

Channel Start

To start all the channels from a tenant:

channelctl --tenant yourtenant start
or
channelctl --tenant mytenant start --channel mychannel

Channel Stop

To stop a channel:

channelctl --tenant mytenant stop --channel apache_httpd

or all of them:

channelctl --tenant mytenant stop

It is possible to force a channel to stop if the upper command didn't work :

channelctl --tenant mytenant stop --channel apache_httpd --force

Application Commands

The channelctl command provides you with the capability to start stop or status only a dedicated application. Here is an example:

channelctl --tenant mytenant start --application apache_httpd/main/single_topology

Refer to the channelctl online help for details.

Tip

You can use a '*' wilcard in any segment (channel, cluster, name) of an application.

E.g. channelctl --tenant mytenant start --application //parsing

Channel Audit

Before starting channels you can check if it is properly configured using the following command:

channelctl --tenant mytenant audit
Checkout the online documentation :
channelctl --tenant mytenant audit --help

Tip

A misconfigured channel cannot be started. Also these do not appear if you execute a status command. Misconfigured channels are not considered as valid hence startable channels.

Channel Shiva Application Check

This command provides useful additional information regarding shiva applications:

channelctl shiva-status

Channel Configuration File Quick View

It is handy to have a look to one of the channel configuration file without opening a separate text editor. Simply type in:

channelctl view

Book Commands

Books are very similar to channels. The difference is simply that a book Use bookctl instead of channelctl.

Administration Kibana GUI

Regular per tenant users are provided with a secured GUI. There, they can act only on their tenant configurations. The Kibana Gui let authorized users stop/start or reload channels and services.

Administration REST API

The punch exposes some resources as REST APIs, in particular the health status of the platform. This makes it very simple to monitor a punchplatform from an external monitoring tool.

Administrative Logging

All platform actions are recorded in a daily Elasticsearch index platform-logs-*. In particular the operator actions are recorded. Here is the log record format:

{
    # The content section contains the actual log. It can be:
    # - a log from punchtcl to trace the channel and job start stop commands
    # - a log from Shiva leader or workers to trace the shiva job start stop and 
    #     assignements events
    # - logs from Shiva jobs (i.e. subprocess)
    "content": {
        # level can be INFO WARN or ERROR.
        # ERRORs should be carefully watched for. 
        "level": "INFO",

        # the actual log message. 
        "message": "job started"

        # only for shiva jobs, the actual args command
        "args": "[/opt/data/punch-standalone-5.2.0/external/punchplatform-shiva-5.2.0/features/commands/logstash, -f, logstash.conf]",

        # whenever available the logger that generated the log. This
        # can be the child logger or the shiva worker logger. 
        "logger": "org.thales.punch.apps.shiva.worker.impl.WorkerTask",
    },
    # the target section relates to the target runtime environment.
    # I.e. a Storm|Shiva|Spark cluster in charge of the related event.
    "target": {
      "cluster": "main",
      "type": "storm"
    },
    # the init section relates to the event originator. 
    "init": {
      "process": {
          # the application name that generated the event
          "name": "channelctl",
          # a runtime id whenever available
          "id": "56605@server1.thales.com"
      },
      "host": {
        # the host name where the event was issued
        "name": "server1"
      },
      "user": {
          # the (unix) user name owning the application.
          # It can be a platform operator or a daemon user depending
          # on the application generating the event.
         "name": "operator"
      }
    },
    # the tenant
    "tenant": "mytenant",

    # the type is always 'punch'.
    "type": "punch",

    # the vendor is always 'thales'
    "vendor": "thales",

    # the channel name
    "channel": "logstash",

    # the job name, if available
    "job": "logstash",

    # the generation timestamp
    "@timestamp": "2019-05-16T03:54:36.949Z"

The important normalized message values are the following:

Message Description
"application started" indicate the start of a channel application. These messages are generated by the channelctl and shiva_worker applications.
"application stopped" indicate the stop of a channel application. These messages are generated by the channelctl and shiva_worker applications.
"assigned application to worker" Generated by the shiva_leader application. Indicate the assignment of a job to a shiva worker.
"scheduled ever running application" Generated by a shiva_worker application. Indicate the scheduling of a continuously running shiva job.
"scheduled periodic application" Generated by a shiva_worker application. Indicate the scheduling of a periodic shiva job. Typical a pml plan or any other job scheduled using a cron quartz schedule parameter.
"starting application on worker" Generated by a shiva_worker application. Indicate the effective start of a shiva job.