Engine Works
Under the hood of Alteryx: tips, tricks and how-tos.
Introduction
At the core of the Server is an executable called AlteryxService.exe (the “Service”), which acts as the Server's central nervous system. Its duties range from serving module interfaces and results to the Gallery, to rendering map tiles for the Map Input Tool in Designer, to orchestrating module execution with the Alteryx Engine for the Scheduler and Gallery.
By default, the Alteryx Service is installed as Windows Service, a type of process that typically starts when a computer is booted and remains active until the machine is stopped. These processes are managed by the Service Control Manager (SCM) in Windows, and common examples include Windows system processes, virus scanners, and drivers for “on demand” scanners/printers.
You can view the Windows Services currently installed on your system by opening Task manager (taskmgr.exe) and switching to the “Services” tab:
Although the Service is intended to run as a Windows Service, it also supports a rich command line interface which is exceedingly useful for automation, maintenance and troubleshooting. The purpose of this post is to introduce the Service command line with concrete examples demonstrating a few of its more interesting capabilities.
Follow-up posts will explore some of these capabilities in much greater detail. But, for now, let’s set the stage and start with some basics.
A word of caution
As with any sharp tool, the Service command line must be used with great care. When experimenting with the Service command line, work in a non-production (sandboxed) environment if possible, and take a few minutes to back up the system before making changes.
The Service command line
To access the Service command line, open a command shell (cmd.exe) and navigate to the Alteryx installation directory (by default, c:\Program Files\Alteryx\bin). Since most of the options require an Administrator-level login, when using the Service command line you’ll generally want to start the command shell as an Administrator.
To see the available command line options, type ‘AlteryxService /?’ at the command prompt:
Note that a default shell width of 130 columns is encouraged when using the Service command line
This post deliberately glosses over the self-explanatory command line options, but we’ll explore a few of the more interesting commands, including scheduling from the command line, Mongo dump/restore, and the service “test” mode.
Scheduling from the command line
One of my favorite options on the Service command line is addtoqueue, which schedules a module for immediate execution. The syntax of the command is straightforward, requiring the path to the module to be queued, the server (Controller) on which to schedule the module, and that Controller’s server secret:
addtoqueue=path,host[:port],secret
Functionally, this command is equivalent to scheduling a module from Designer using the “Run the workflow from its original location…” option selected:
But, what’s neat about this command line flag is it enables automation (the secret to the universe), and can be used as a quick command line smoke-test for a new Server installation or at the core of more sophisticated scripts. As a concrete example, consider the benchmarking app introduced in a previous post. That app uses a Run Command tool in Designer to call a batch (bat) script, which, in turn, queues a collection of modules to a particular Server instance using AlteryxService.exe addtoqueue:
:start_scheduling
set /a numIterations=numIterations-1
for %%m in (%workflowDir%\*.yxmd) do (
echo scheduling %%m
start /wait /d %alteryxBinPath% AlteryxService.exe addtoqueue="%%m",%server%,%serverSecret%
)
To use this command on your local system, fire up a command shell (preferably as an Administrator), and locate the module you want to schedule. You'll need the security token for the Server you're scheduling to, or if the target Controller is localhost, you can collect the token on the command line using the getsecret flag as shown here:
After scheduling the module on the command line, the module will be placed into the execution queue on that Controller, and processed by the next available worker.
Backing up and restoring Embedded Mongo
By default, the Service uses an “Embedded” Mongo instance for its data storage, which is a Mongo instance that the Service bootstraps on first run and uses thereafter. We encourage users to back up this Mongo instance regularly, and we provide a command line option on the Service to make it easier.
Using the emongodump option on the Service, we can safely dump the current Embedded Mongo database to a target folder on the filesystem. Before we can do so, however, we must stop the Service running as a System process.
We can stop the Service either from the command line, or via the task manager. To stop from the command line, open an Administrator command shell and ask the Service Control Manager to stop the service using sc stop AlteryxService:
sc start, sc stop and sc query are useful commands when working with system services
Or, from the task manager, right-click on the AlteryxService service and choose “Stop”:
Remember, stopping the AlteryxService means stopping the Server itself, so please tred lightly to avoid interrupting users.
emongodump
After stopping the Service, we can use the emongodump command to export the Mongo database. From the Administrator command shell, navigate to the Alteryx installation directory and execute the emongodump command, which requires the full path to an empty folder:
emongodump=TargetDirectory
Depending on the size of your database, this command may take a few seconds to a few minutes to complete:
If the path you're writing to contains spaces, remember to wrap the path in quotations on the command line
emongorestore
In the [unlikely] event of an unrecoverable Mongo failure, you can restore the Mongo database from a backup using the emongorestore command. This command requires the path to a folder containing a Mongo dump, and a path to which it should be restored:
emongorestore=SourcePath,TargetPath
In this example, we’ll restore from the backup we just created to the default Service persistence folder:
Note that the emongorestore command must be used with great caution as it will overwrite the contents of the target folder!
Service Test mode
Instead of executing in the background as a system service, the Service can run as an interactive, console-style application. In this "test" mode, the Service runs as the current Windows user (typically the Administrator), and supports exactly the same functionality as a Service running as a System Service. This mode is typically used for testing and troubleshooting, details of which we’ll cover in future blog posts.
As with the Embedded Mongo dump and restore (emongodump and emongorestore), we must ask the Service Control Manager to stop the Service prior to starting a new instance in test mode. After the system-level instance of the Service is stopped, start an interactive instance of the Service by navigating to your Alteryx installation directory in a command shell and adding the test flag to the Service command line:
The console shows the "logical services" the Alteryx Service starts to support the current configuration
Note that, depending on how your Server is configured, you may see two other console windows appear, one for the Mongo daemon and one for the Gallery. To exit the Alteryx Service running in test mode, activate the Service console window and press any key on the keyboard.
Note that closing the Gallery or Mongo window will not terminate the Service, and serves as a demonstration of some of the built-in resliency mechanisms in the Service itself.
Closing
This brief overview of the Service command line sets the stage for more advanced discussions about automation, setup and troubleshooting, so stay tuned for more Server-related posts. Thank you kindly for reading and feel free to reach out with comments and questions.
