.\" Licensed to the Apache Software Foundation (ASF) under one or more
.\" contributor license agreements.  See the NOTICE file distributed with
.\" this work for additional information regarding copyright ownership.
.\" The ASF licenses this file to You under the Apache License, Version 2.0
.\" (the "License"); you may not use this file except in compliance with
.\" the License.  You may obtain a copy of the License at
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.\"
.\" Process this file with
.\" groff -man -Tascii apex.1
.\"
.TH apex 1 "August 2015 " Linux "User Manuals"

.SH NAME
Apex \- Unified streaming and batch processing engine

.SH SYNOPSIS

.B apex 
[options] [-efhpr] [-kp] [-kt] [-v|vv|vvv|vvvv]

.SH DESCRIPTION

Apache Apex command line interface can be used to launch, monitor, and manage Apache Apex applications. It enables easy integration with existing enterprise toolsets for automated application monitoring and management. Currently the following high level tasks are supported:

.IP \[bu] 2
Launch or kill applications
.IP \[bu] 2
View system metrics including load, throughput, latency, etc.
.IP \[bu] 2
Start or stop tuple recording
.IP \[bu] 2
Read operator, stream, port properties and attributes
.IP \[bu] 2
Write to operator properties
.IP \[bu] 2
Dynamically change the application logical plan
.IP \[bu] 2
Create custom macros

.RS 0
For more information about Apache Apex, see http://apex.apache.org/


.SH OPTIONS

.TP
.BI \-e " arg"
Commands are read from the argument
.TP
.BI \-f " arg"
Use the specified prompt at all time
.TP
.BI \-h
Print this help
.TP
.BI \-kp " arg"
Use the specified kerberos principal
.TP
.BI \-kt " arg"
Use the specified kerberos keytab
.TP
.BI \-p " arg"
JSONP padding function
.TP
.BI \-r
JSON Raw mode
.TP
.BI \-v[v|vv|vvv]
Verbose mode level 1-4


.SH COMMANDS
.SS Global command except when changing logical plan:

.TP
.BI alias " alias-name command" 
Create a command alias

.TP
.BI begin-macro " name"
Begin Macro Definition ($1...$9 to access parameters and type 'end' to end the definition)

.TP
.BI connect " app-id"
Connect to an app

.TP
.BI dump-properties-file " out-file jar-file class-name"
Dump the properties file of an app class

.TP
.BI echo " args"
Echo the arguments

.TP
.BI exit
Exit the CLI

.TP
.BI get-app-info " app-id"
Get the information of an app

.TP
.BI get-app-package-info " app-package-file"
Get info on the app package file

.TP
.BI get-app-package-operator-properties " app-package-file operator-class"
Get operator properties within the given app package

.TP
.BI get-app-package-operators " [options] app-package-file [search-term]"
Get operators within the given app package. Options are:
.RS 8
.TP
.BI \-parent
Specify the parent class for the operators
.RE

.TP
.BI get-config-parameter " [parameter-name]"
Get the configuration parameter

.TP
.BI get-jar-operator-classes " [options] jar-files-comma-separated [search-term]"
List operators in a jar list. Options are:
.RS 8
.TP
.BI \-parent    
Specify the parent class for the operators
.RE

.TP
.BI get-jar-operator-properties " jar-files-comma-separated operator-class-name"
List properties in specified operator

.TP
.BI help " [command]"
Show help

.TP
.BI kill-app " app-id [app-id ...]"
Kill an app

.TP
.BI launch " [options] jar-file/json-file/properties-file/app-package-file [matching-app-name]"
Launch an app. Options are:
.RS 8
.TP
.BI \-apconf " <app_package_configuration_file>"
Specify an application configuration file within the app package if launching an app package.
.TP
.BI \-archives " <comma_separated_list_of_archives>"
Specify comma separated archives to be unarchived on the compute machines.
.TP
.BI \-conf " <configuration_file>"
Specify an application configuration file.
.TP
.BI \-D " <property=value>"
Use value for given property.
.TP
.BI \-exactMatch
Only consider applications with exact app name
.TP
.BI \-files " <comma_separated_list_of_files>"
Specify comma separated files to be copied on the compute machines.
.TP
.BI \-force
Force launch the application. Do not check for compatibility
.TP
.BI \-ignorepom
Do not run maven to find the dependency.
.TP
.BI \-libjars "<comma_separated_list_of_libjars>"
Specify comma separated jar files or other resource files to include in the classpath.
.TP
.BI \-local
Run application in local mode.
.TP
.BI \-originalAppId "<application_id>"
Specify original application identifier for restart.
.TP
.BI \-queue "<queue_name>"
Specify the queue to launch the application.
.RE

.TP
.BI list-application-attributes
Lists the application attributes

.TP
.BI list-apps " [pattern]"
List applications

.TP
.BI list-operator-attributes
Lists the operator attributes

.TP
.BI list-port-attributes
Lists the port attributes

.TP
.BI set-pager " on|off"
Set the pager program for output

.TP
.BI show-logical-plan " [options] jar-file/app-package-file [class-name]"
List apps in a jar or show logical plan of an app class. Options are:
.RS 8
.TP
.BI \-exactMatch
Only consider exact match for app name
.TP
.BI \-ignorepom
Do not run maven to find the dependency
.TP
.BI \-libjars " <comma_separated_list_of_jars>"
Specify comma separated jar/resource files to include in the classpath.
.RE

.TP
.BI "shutdown-app app-id [app-id ...]"
Shutdown an app

.TP
.BI "source file"
Execute the commands in a file

.SS Commands when connected to an app (via connect <appid>) except when changing logical plan:

.TP
.BI begin-logical-plan-change
Begin Logical Plan Change

.TP
.BI dump-properties-file " out-file [jar-file] [class-name]"
Dump the properties file of an app class

.TP
.BI get-app-attributes " [attribute-name]"
Get attributes of the connected app

.TP
.BI get-app-info " [app-id]"
Get the information of an app

.TP
.BI get-operator-attributes " operator-name [attribute-name]"
Get attributes of an operator

.TP
.BI get-operator-properties " operator-name [property-name]"
Get properties of a logical operator

.TP
.BI get-physical-operator-properties " [options] operator-id"
Get properties of a physical operator. Options are:
.RS 8
.TP
.BI \-propertyName " <property_name>"
The name of the property whose value needs to be retrieved
.TP
.BI \-waitTime " <wait_time>"
How long to wait to get the result
.RE

.TP
.BI get-port-attributes " operator-name port-name [attribute-name]"
Get attributes of a port

.TP
.BI get-recording-info " [operator-id] [start-time]"
Get tuple recording info

.TP
.BI kill-app " [app-id ...]"
Kill an app

.TP
.BI kill-container " container-id [container-id ...]"
Kill a container

.TP
.BI list-containers
List containers

.TP
.BI list-operators " [pattern]"
List operators

.TP
.BI set-operator-property " operator-name property-name property-value"
Set a property of an operator

.TP
.BI set-physical-operator-property " operator-id property-name property-value"
Set a property of an operator

.TP
.BI show-logical-plan " [options] [jar-file/app-package-file] [class-name]"
Show logical plan of an app class. Options are:
.RS 8
.TP
.BI \-exactMatch
Only consider exact match for app name
.TP
.BI \-ignorepom
Do not run maven to find the dependency
.TP
.BI \-libjars "<comma_separated_list_of_jars>"
Specify comma separated jar/resource files to include in the classpath.
.RE

.TP
.BI show-physical-plan
Show physical plan

.TP
.BI shutdown-app " [app-id ...]"
Shutdown an app

.TP
.BI start-recording " operator-id [port-name] [num-windows]"
Start recording

.TP
.BI stop-recording " operator-id [port-name]"
Stop recording

.TP
.BI wait " timeout"
Wait for completion of current application

.SS Commands when changing logical plan (via begin-logical-plan-change):

.TP
.BI abort
Abort the plan change

.TP
.BI add-stream-sink " stream-name to-operator-name to-port-name"
Add a sink to an existing stream

.TP
.BI create-operator " operator-name class-name"
Create an operator

.TP
.BI create-stream " stream-name from-operator-name from-port-name to-operator-name to-port-name"
Create a stream

.TP
.BI help " [command]"
Show help

.TP
.BI remove-operator " operator-name"
Remove an operator

.TP
.BI remove-stream " stream-name"
Remove a stream

.TP
.BI set-operator-attribute " operator-name attr-name attr-value"
Set an attribute of an operator

.TP
.BI set-operator-property " operator-name property-name property-value"
Set a property of an operator

.TP
.BI set-port-attribute " operator-name port-name attr-name attr-value"
Set an attribute of a port

.TP
.BI set-stream-attribute " stream-name attr-name attr-value"
Set an attribute of a stream

.TP
.BI show-queue
Show the queue of the plan change

.TP
.BI submit
Submit the plan change

.SH EXAMPLES

.B Launching Apex Application
.RS 4
dt> launch /path/to/apa/file
.RS 0
{"appId": "application_1455698907310_0001"}
.RS 0
dt (application_1455698907310_0001) >
.RE
.RE
.RE

.B Launch Apex Application with external conf file
.RS 4
dt> launch /path/to/apa/file -conf /path/to/xml/conf/file
.RS 0
{"appId": "application_1455698907310_0001"}
.RS 0
dt (application_1455698907310_0001) >
.RE
.RE
.RE

.B Launch Apex Application with properties
.RS 4
dt> launch /path/to/apa/file -Dprop1=value1 -Dprop2=val2
.RS 0
{"appId": "application_1455698907310_0001"}
.RS 0
dt (application_1455698907310_0001) >
.RE
.RE
.RE

.B Shutdown application
.RS 4
dt> shutdown-app application_1455698907310_0001
.RS 0
Shutdown requested: {}
.RS 0
dt>
.RE
.RE
.RE

.RS 4
.B OR 
.RE

.RS 4
dt (application_1455698907310_0001) > shutdown-app
.RS 0
Shutdown requested: {}
.RS 0
dt>
.RE
.RE
.RE

.B Kill application (force shutdown)
.RS 4
dt> kill-app application_1455698907310_0001
.RS 0
Kill app requested
.RS 0
dt>
.RE
.RE
.RE

.RS 4
.B OR 
.RE

.RS 4
dt (application_1455698907310_0001) > kill-app
.RS 0
Kill app requested
.RS 0
dt>
.RE
.RE
.RE


.SH ENVIRONMENT

.TP
.BI JAVA_HOME
The java implementation to use.  Overrides JAVA_HOME.

.TP
.BI DT_CLIENT_OPTS
Extra Java runtime options. Default is "-Xmx1024m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled"

.TP
.BI HADOOP_HOME
Optionally, the Hadoop home to run with.

.SH COPYRIGHT
Copyright (C) 2015 The Apache Software Foundation. All rights reserved.