dist/apex.1 - apex-core - Git at Google

 .\" 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 "May 2018 " 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
 apex> launch /path/to/apa/file
 .RS 0
 {"appId": "application_1455698907310_0001"}
 .RS 0
 apex (application_1455698907310_0001) >
 .RE
 .RE
 .RE

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

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

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

 .RS 4
 .B OR
 .RE

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

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

 .RS 4
 .B OR
 .RE

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


 .SH ENVIRONMENT

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

 .TP
 .BI APEX_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) 2018 The Apache Software Foundation. All rights reserved.
	.\" 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 "May 2018 " 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
	apex> launch /path/to/apa/file
	.RS 0
	{"appId": "application_1455698907310_0001"}
	.RS 0
	apex (application_1455698907310_0001) >
	.RE
	.RE
	.RE

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

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

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

	.RS 4
	.B OR
	.RE

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

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

	.RS 4
	.B OR
	.RE

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


	.SH ENVIRONMENT

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

	.TP
	.BI APEX_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) 2018 The Apache Software Foundation. All rights reserved.