Package: grokcli
Grok Command Line Interface===========================This repository contains the Grok Command line interface (CLI). `grokcli` allows you to easily interact with a Grok server through the command line including creating instances, etc.In addition you can use `grokcli` to integrate with third party applications.  Included in `grokcli` is an integration with Datadog (see [Grok Integration With Datadog](docs/Grok-Integration-with-DataDog.pdf) for full details). See more details by running `python -m grokcli.datadog --help`.Installation------------Requires: Python (2.6 or greater)- pip (recommended)`pip install grokcli`- easy_install`easy_install grokcli`- setup.py`python setup.py install`Usage-----Grok CLI tools provides a single, high-level `grok` command, from whicha number of sub-commands can be invoked:grok [command] [options]Each command takes `GROK_SERVER_URL` and `GROK_API_KEY` as the first two arguments after the command name. However, if you set those two environment variables, you can omit those arguments from the commands.- `grok credentials`Use the `grok credentials` sub-command to add your AWS credentials to arunning Grok server configuration:grok credentials GROK_SERVER_URL [options]The `GROK_SERVER_URL` positional argument is required and must be a url to arunning Grok server.  For example: https://ec2-AA-BB-CC-DD.us-west-2.compute.amazonaws.comYou can specify your credentials in one of three ways:- Specify `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` CLI options.```grok credentials GROK_SERVER_URL --AWS_ACCESS_KEY_ID=... --AWS_SECRET_ACCESS_KEY=...```- Read AWS credentials from a specific file using the `-d`, or `--data` CLIoptions.```grok credentials GROK_SERVER_URL -d PATH_TO_FILEgrok credentials GROK_SERVER_URL --data=PATH_TO_FILE```You can read from stdin using `-`:```grok credentials GROK_SERVER_URL -d - < PATH_TO_FILEgrok credentials GROK_SERVER_URL --data=- < PATH_TO_FILE```The credentials file should be formatted according to this template:```AWS_ACCESS_KEY_ID=Your AWS access key ID hereAWS_SECRET_ACCESS_KEY=Your AWS secret access key here```- Use existing boto configuration.```grok credentials GROK_SERVER_URL --use-boto```- `grok export`Export Grok model definitions to a file in JSON or YAML format.grok export [GROK_SERVER_URL GROK_API_KEY] [options]The `GROK_SERVER_URL` positional argument is required and must be a url to arunning Grok server.  For example: https://ec2-AA-BB-CC-DD.us-west-2.compute.amazonaws.comThe `GROK_API_KEY` positional argument is also required, and can be retrievedfrom the web interface of a running Grok server.By default, `grok export` prints output to stdout, which can be directed to afile:grok export [GROK_SERVER_URL GROK_API_KEY] > file.jsonHowever, you can optionally specify a file using the `-o` or `--output` CLIoption:grok export [GROK_SERVER_URL GROK_API_KEY] -o file.jsongrok export [GROK_SERVER_URL GROK_API_KEY] --output=file.jsonUse the `-y` or `--yaml` CLI flag to save output in YAML formatgrok export [GROK_SERVER_URL GROK_API_KEY] -ygrok export [GROK_SERVER_URL GROK_API_KEY] --yaml- `grok import`Import Grok model definitions into a Grok server from a local file.grok import [GROK_SERVER_URL GROK_API_KEY] [FILE] [options]The `GROK_SERVER_URL` positional argument is required and must be a url to arunning Grok server.  For example: https://ec2-AA-BB-CC-DD.us-west-2.compute.amazonaws.comThe `GROK_API_KEY` positional argument is also required, and can be retrievedfrom the web interface of a running Grok server. The API Key is synonymous with the mobilepassword.The `FILE` positional argument is optional, however if it is not specified,`grok import` will assume `STDIN` if `-d` or `--data` is not specified.  Thefollowing are equivalent:grok import [GROK_SERVER_URL GROK_API_KEY] file.jsongrok import [GROK_SERVER_URL GROK_API_KEY] < file.jsongrok import [GROK_SERVER_URL GROK_API_KEY] -d file.jsongrok import [GROK_SERVER_URL GROK_API_KEY] --data=file.json`grok import` supports files in YAML format, if pyyaml is installed andavailable on the system.- `grok (DELETE|GET|POST)`Included in the Grok CLI tool is a lower-level direct API which translatesCLI options to direct HTTP calls into the Grok web service.  For example, toget all available cloudwatch metrics:grok GET GROK_SERVER_URL/_metrics/cloudwatch GROK_API_KEYFor `grok POST` and `grok DELETE`, where request data may be required, suchdata can be specified either via the `-d`, or `--data` CLI option, orsupplied via STDIN:grok POST GROK_SERVER_URL/_models GROK_API_KEY < model-definition.jsongrok POST GROK_SERVER_URL/_models GROK_API_KEY -d model-definition.jsongrok POST GROK_SERVER_URL/_models GROK_API_KEY --data model-definition.json- `grok metrics`Manage monitored metrics.grok metrics (list|unmonitor) [GROK_SERVER_URL GROK_API_KEY] [options]To get a list of monitored metrics:grok metrics [GROK_SERVER_URL GROK_API_KEY]Limiting to monitored metrics for a specific AWS instance:grok metrics list [GROK_SERVER_URL GROK_API_KEY] --instance=INSTANCE_ID --region=REGION --namespace=NAMESPACETo unmonitor a metric:grok metrics unmonitor https://localhost CmHnD --id=METRIC_ID- `grok instances`Manage monitored instances.grok instances (list|unmonitor) [GROK_SERVER_URL GROK_API_KEY] [options]To get a list of all monitored instances:grok instances list [GROK_SERVER_URL GROK_API_KEY]To unmonitor an instance:grok instances unmonitor [GROK_SERVER_URL GROK_API_KEY] --id=INSTANCE_ID- `grok cloudwatch`Manage CloudWatch metrics.grok cloudwatch (metrics|instances) (list|monitor|unmonitor) [GROK_SERVER_URL GROK_API_KEY] [options]To list available cloudwatch metrics:grok cloudwatch metrics list [GROK_SERVER_URL GROK_API_KEY]To filter list of available cloudwatch metrics by instance id:grok cloudwatch metrics list [GROK_SERVER_URL GROK_API_KEY] --instance=INSTANCE_IDTo monitor a metric (example):grok cloudwatch metrics monitor [GROK_SERVER_URL GROK_API_KEY] \--metric=CPUUtilization \--namespace=AWS/EC2 \--region=us-west-2 \--dimensions InstanceId i-abc123To monitor an instance (example):grok cloudwatch instances monitor [GROK_SERVER_URL GROK_API_KEY] \--namespace=AWS/EC2 \--region=us-west-2 \--instance=i-abc123To unmonitor a metric (example):grok cloudwatch metrics unmonitor [GROK_SERVER_URL GROK_API_KEY] \--metric=CPUUtilization \--namespace=AWS/EC2 \--region=us-west-2 \--dimensions InstanceId i-abc123To unmonitor an instance (example):grok cloudwatch instances unmonitor [GROK_SERVER_URL GROK_API_KEY] \--namespace=AWS/EC2 \--region=us-west-2 \--instance=i-abc123- `grok custom`Manage custom metrics.To list available custom metrics:grok custom metrics list [GROK_SERVER_URL GROK_API_KEY]To monitor a custom metric:grok custom metrics monitor [GROK_SERVER_URL GROK_API_KEY] --id=METRIC_IDTo unmonitor a custom metric:grok custom metrics unmonitor [GROK_SERVER_URL GROK_API_KEY] --name=METRIC_NAME- `grok autostacks`Manage autostacks.To create an autostack:grok autostacks stacks create [GROK_SERVER_URL GROK_API_KEY] --name=NAME --region=REGION --filters='{"tag:FILTER_NAME": ["FILTER_VALUE"]}'You can use any AWS tag for FILTER_NAME. The FILTER_VALUE is an AWS-specificwildcard, not a full-fledged regular expression. * matches any number of charactersand ? matches any single character. The filter name and value are bothcase-sensitive.For example, "jenkins-*" and "jenkins-??????" both match "jenkins-master".You can use any AWS tag for the first component of a filter, though foroptimal performance we recommend that the first tag/value pair specified bethe one that eliminates the most instances. Because AWS only supports ORoperations at this time, we have to implement the AND (intersection) operationlocally. Our implementation sends the first tag/value to AWS, gets all thematching instances, and then filters them against the remaining tag/valuefilters locally.This does not create any metrics for the new autostack. You must create metricsfor the new autostack with grok autostacks metrics add (see below)To preview an autostack:grok autostacks stacks create [GROK_SERVER_URL GROK_API_KEY] --preview --region=REGION --filters='{"tag:FILTER_NAME": ["FILTER_VALUE"]}'To list AutoStacks:grok autostacks stacks list [GROK_SERVER_URL GROK_API_KEY]To delete an AutoStack:grok autostacks stacks delete [GROK_SERVER_URL GROK_API_KEY] --name=STACK_NAME --region=REGIONor:grok autostacks stacks delete [GROK_SERVER_URL GROK_API_KEY] --id=STACK_IDTo add metric type(s) monitored by an AutoStack:grok autostacks metrics add [GROK_SERVER_URL GROK_API_KEY] --name=STACK_NAME --region=REGION --metric_namespace=METRIC_NAMESPACE --metric_name=METRIC_NAMEor:grok autostacks metrics add [GROK_SERVER_URL GROK_API_KEY] --id=STACK_ID --metric_namespace=METRIC_NAMESPACE --metric_name=METRIC_NAMETo list metric type(s) monitored by an AutoStack:grok autostacks metrics list [GROK_SERVER_URL GROK_API_KEY] --name=STACK_NAME --region=REGIONor:grok autostacks metrics list [GROK_SERVER_URL GROK_API_KEY] --id=STACK_IDTo remove metric type(s) monitored by an AutoStack:grok autostacks metrics remove [GROK_SERVER_URL GROK_API_KEY] --name=STACK_NAME --region=REGION --metric_id=METRIC_IDor:grok autostacks metrics remove [GROK_SERVER_URL GROK_API_KEY] --id=STACK_ID --metric_id=METRIC_IDTo list EC2 Instances associated with an AutoStack(s):grok autostacks instances list [GROK_SERVER_URL GROK_API_KEY] --name=STACK_NAME --region=REGIONor:grok autostacks instances list [GROK_SERVER_URL GROK_API_KEY] --id=STACK_IDNote to developers------------------To add a command, create a python module in[grokcli/commands/](grokcli/commands) with a `handle()` function which acceptstwo arguments: `options`, and `args`.  Register the command by importing themodule in [grokcli/commands/\_\_init\_\_.py](grokcli/commands/__init__.py) andadding it to `__all__`.