Genie Telemetry User Guide¶
Installation
Support
Genie Telemetry Launcher
Standard Arguments
Testbed File
Installation¶
genie.telemetry comes in two parts. The core package and the libraries.
First install the core package via pip.
bash$ pip install genie.telemetry
Secondly install the library package via pip.
bash$ pip install genie.libs.telemetry
Note
Officially released genie.telemetry plugins are automatically made
available by the above command and can be imported from
genie.libs.telemtery.
Ex: Plugins are accessed as “genie.libs.telemtery.plugins.tracebackcheck”
The Genie Telemetry Libraries are user-community owned and developed. To contribute to the library, clone the genie.libs.telemetry repo and do the following:
cd genietelemetrylibs
make develop
Support¶
Reach out to contact us for any questions or issues
related to the genie.abstract package.
You can also post questions to the community forum - the support team patrols these forums daily.
Genie Telemetry Launcher¶
Genie Telemetry comes with its own launcher: the genietelemetry executable.
This launcher is installed into your pyATS instance automatically, and is
accessible directly as part of the user PATH after activating your instance.
# activate your pyats instance, eg:
[tony@jarvis:~]$ cd /ws/tony-stark/pyats
[tony@jarvis:pyats]$ source env.sh
Activating the pyATS instance @ /ws/tony-stark/pyats
--------------------------------------------------------------------
PYTHONPATH=/ws/tony-stark/pyats:
LD_LIBRARY_PATH=/auto/ttsw/ActiveTcl/8.4.19/lib:/usr/X11R6/lib
--------------------------------------------------------------------
# genietelemetry is now part of your path
(pyats) [tony@jarvis:pyats]$ which genietelemetry
/ws/tony-stark/pyats/bin/genietelemetry
genietelemetry comes natively with built-in help information:
[tony@jarvis:~]$ genietelemetry -h
usage: genietelemetry [TESTBEDFILE]
[-h] [-loglevel] [-configuration FILE] [-uid UID]
[-runinfo_dir RUNINFO_DIR]
[-callback_notify CALLBACK_NOTIFY] [-timeout TIMEOUT]
[-connection_timeout CONNECTION_TIMEOUT] [-no_mail]
[-no_notify] [-mailto] [-mail_subject]
[-notify_subject] [-email_domain] [-smtp_host]
[-smtp_port] [-smtp_username] [-smtp_password]
genie telemetry command line arguments.
Example
-------
genietelemetry /path/to/testbed.yaml
----------------------------------------------------------------------------
Positional Arguments:
TESTBEDFILE testbed file to be monitored
Help:
-h, -help show this help message and exit
Logging:
-loglevel genie telemetry logging level
eg: -loglevel="INFO"
Configuration:
-configuration FILE configuration yaml file for plugins and settings
-uid UID Specify monitoring job uid
-runinfo_dir RUNINFO_DIR
Specify directory to store execution logs
-callback_notify CALLBACK_NOTIFY
Specify Liveview callback notify URI
-timeout TIMEOUT Specify plugin maximum execution length
Default to 300 seconds
-connection_timeout CONNECTION_TIMEOUT
Specify connection timeout
Mailing:
-no_mail disable final email report
-no_notify disable notification on device health status other
than "ok"
-mailto list of email recipients
-mail_subject report email subject header
-notify_subject notification email subject header
-email_domain default email domain
-smtp_host specify smtp host
-smtp_port specify smtp server port
-smtp_username specify smtp username
-smtp_password specify smtp password
Tip
The built-in help information of genietelemetry automatically finds and
lists all arguments available from each genie telemetry plugin if
configuration file is provided.
For example, the following config file contains tracebackcheck plugin with 3 arguments.
plugins:
tracebackcheck:
interval: 30
module: genie.libs.telemtery.plugins.tracebackcheck
[tony@jarvis:~]$ genietelemetry -h /path/to/config.yaml
usage: genietelemetry [TESTBEDFILE]
[-h] [-loglevel] [-configuration FILE] [-uid UID]
[-runinfo_dir RUNINFO_DIR]
[-callback_notify CALLBACK_NOTIFY] [-timeout TIMEOUT]
[-connection_timeout CONNECTION_TIMEOUT] [-no_mail]
[-no_notify] [-mailto] [-mail_subject]
[-notify_subject] [-email_domain] [-smtp_host]
[-smtp_port] [-smtp_username] [-smtp_password]
[--tracebackcheck_logic_pattern TRACEBACKCHECK_LOGIC_PATTERN]
[--tracebackcheck_clean_up TRACEBACKCHECK_CLEAN_UP]
[--tracebackcheck_timeout TRACEBACKCHECK_TIMEOUT]
genie telemetry command line arguments.
Example
-------
genietelemetry /path/to/testbed.yaml
------------------------------------------------------------------------
Positional Arguments:
TESTBEDFILE testbed file to be monitored
Help:
-h, -help show this help message and exit
Logging:
-loglevel genie telemetry logging level
eg: -loglevel="INFO"
Configuration:
-configuration FILE configuration yaml file for plugins and settings
-uid UID Specify monitoring job uid
-runinfo_dir RUNINFO_DIR
Specify directory to store execution logs
-callback_notify CALLBACK_NOTIFY
Specify Liveview callback notify URI
-timeout TIMEOUT Specify plugin maximum execution length
Default to 300 seconds
-connection_timeout CONNECTION_TIMEOUT
Specify connection timeout
Mailing:
-no_mail disable final email report
-no_notify disable notification on device health status
other than "ok"
-mailto list of email recipients
-mail_subject report email subject header
-notify_subject notification email subject header
-email_domain default email domain
-smtp_host specify smtp host
-smtp_port specify smtp server port
-smtp_username specify smtp username
-smtp_password specify smtp password
Traceback Check:
--tracebackcheck_logic_pattern TRACEBACKCHECK_LOGIC_PATTERN
Specify logical expression for patterns to
include/exclude when checking tracebacks
following pyATS logic format. Default patternis
to check for Tracebacks.
--tracebackcheck_clean_up TRACEBACKCHECK_CLEAN_UP
Specify whether to clear all warnings and
tracebacks after reporting error
--tracebackcheck_timeout TRACEBACKCHECK_TIMEOUT
Specify duration (in seconds) to wait before
timing out execution of a command
Standard Arguments¶
genie.telemetry accepts a number of standard arguments that can be used to
influence and/or change monitoring behaviors. All arguments are constructed and
processed using python argparse module.
Argument |
Description |
|---|---|
|
mandatory argument, full path/name of testbed yaml file to monitor with. |
|
configuration yaml file for telemetry plugins |
|
unique id from upper systems identifying this run |
|
specify the output log level for GenieTelemetry |
|
specify alternative runtime info directory location to store execution logs |
|
Specify Liveview callback notify URI |
|
Specify plugin maximum execution length, default to 300 sec |
|
Specify connection timeout if connection class allows timeout override |
|
flag, disables email report at the end of run |
|
specify the list of email report recipients. |
|
email report subject line. |
|
flag, disable notification on abnormal device health staus reported by each plugin. |
|
notification email subject header. |
|
specify default email domain, required for email or notification |
|
specify smtp host, required for email or notification |
|
specify smtp server port, required for email or notification |
|
specify smtp username, required for email or |
notification” |
|
|
specify smtp password, required for email or notification |
Tip
genie.telemetry standardizes on single-dash - style arguments.
genie.libs.telemtery standardizes on double-dash -- style arguments.
-helpPrints help information and how to use each arguments.
bash$ genietelemetry -help
testbed_fileMandatory argument. Specifies the full path/name to the testbed yaml to monitor with. Refer to Testbed File for more details.
bash$ genietelemetry /path/to/testbed.yaml
-configurationMandatory argument, used to provide the YAML plugin configuration file. Use this if you want to configure your Genie Telemetry to run certain plugins for this particular run.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml-uidoptional argument. Allows upstream executor to pass down a unique identifier string to be stored in report.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -uid "this_is_an_example"-loglevelSpecifies the logging level for GenieTelemetry. Use this to increase or decrease GenieTelemetry module’s log output level for debugging purposes. May be specified in UPPERCASE or lowercase. Check loglevel for more details.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -loglevel INFO bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -loglevel DEBUG-no_mailFlag, disables email report at the end of execution.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -no_mail-email_domainDefault email domain for emailing. Required argument for email or notification.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com-smtp_hostSMTP host for emailing. Required argument for email or notification.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com-smtp_portSMTP port for emailing. Optional argument for email or notification. (Default: 25)
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -smtp_port 25-smtp_usernameSMTP username for emailing. Optional argument for email or notification.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -smtp_port 25 -smtp_username tonystark-smtp_passwordSMTP password for emailing. Optional argument for email or notification.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -smtp_port 25 -smtp_username tonystark -smtp_password I@mIronMan-mailtoProvides a list of recipients that receive email report at the end of the run. Supports using either white-space, comma or semi-colon as the delimiter, and supports either user ids or full email addresses. (default: current user)
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -mailto "chambers, psp, crobbins@cisco.com"-mail_subjectWhen specified, replaces the default email report subject line. (default:
Monitoring Report - testbed: <name> by: <username>, Status <status>)bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -mail_subject "legen -wait-for-it- dary.Legendary!"-no_notifyFlag, disables notification on abnormal device health staus detected from each plugin.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -no_notify-notify_subjectWhen specified, replaces the default email notification subject line. (default:
Monitoring Notification - device: <name> plugin: <plugin> status: <status>)bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -mail_subject "legen -wait-for-it- dary.Legendary!"-runinfo_dirSpecifies an alternative location for
genietelemetryexecutionruninfodirectory to store log and result yaml file. Default to current folder.bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -runinfo_dir /my/runinfo/directory-callback_notifySpecify Liveview callback notify URI. The Genie Telemetry will stream log and execution result over websocket protocol.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -callback_notify http://your.socket.io.server
Note
This argument has prerequisite of ats.liveview package.
Tip
If the uri contains fragment which will be used as part of Authorization Header for the Websocket request.
for example: http://your.socket.io.server#jwt+<Token> will translate into Websocket request header:
Authorization: jwt <Token>
-timeoutSpecify each plugin maximum execution length. Default to 300 seconds
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -timeout 30-connection_timeoutSpecify connection timeout, if connection class defined at testbed yaml file supports timeout argument override.
bash$ genietelemetry /path/to/testbed.yaml -configuration /path/to/config.yaml -email_domain cisco.com -smtp_host cisco.com -connection_timeout 10
Testbed File¶
Testbed file for Genie Telemetry is slightly different to regular pyATS testbed yaml file.
device should contains mandatory key ‘os’ and has custom abstraction order defined for abstraction plugins to work.
suggested values for ‘os’ abstraction token are
nxos,iosxe,iosxror any token that is used at your genie telemetry plugin.
Example Testbed File
testbed:
name: sampleTestbed
tacacs:
login_prompt: "login:"
password_prompt: "Password:"
username: admin
passwords:
tacacs: CSCO12345^
enable: lab
line: lab
devices:
ott-tb1-n7k4:
type: Nexus 7000
alias: device-1
os: 'nxos'
connections:
a:
protocol: telnet
ip: 10.85.84.80
port: 2001
b:
protocol: telnet
ip: 10.85.84.80
port: 2003
alt:
protocol: telnet
ip: 5.19.27.5
custom:
abstraction:
order: [os]
Hint
Please remember to include default connection class and abstraction order in your testbed YAML file as shown in the example above.