Validating SAS Viya Environments Has Never Been this Easy
Pyviyatools provides a large swath of command-line tools that utilize the SAS Viya REST APIs to work with an existing Viya environment. These tools are designed to be easy to use and offer a great deal of opportunities for understanding how your Viya environment is performing. Recently, I created a new tool, ValidateViya, which is designed to validate a Viya environment, testing its functionality while also reporting important metrics. Automating the process of validating a Viya environment can be extremely beneficial to a SAS Viya administrator, making ValidateViya a valuable tool.
Installation
To use pyviyatools, you’ll need to open the command line, clone the github repository, and cd into the new directory:
git clone https://github.com/sassoftware/pyviyatools.git
cd $install-dir
Running setup.py will point pyviyatools to the location and name of your sascli executable. The default location of this executable is /opt/sas/viya/home/bin/sas-viya. If your executable is in a different location, run:
./setup.py --clilocation [LOCATION] --cliexecutable [EXECUTABLE NAME]
If your executable is in the default location, just run:
./setup.py
Setting Up
Before using ValidateViya, you’ll need to ensure that you’ve authenticated to Viya with the SAS Administration CLI. To do so, you’ll need to create a profile as a SAS administrator on the machine with the Viya CLI. To do so, open the command line and run:
sas-viya profile init
When prompted for the base endpoint of your Viya server, enter the base endpoint for the Viya environment you will be connecting to. For example, I entered:
Service Endpoint> https://gelcorp.rext03-0029.race.sas.com
With a profile created, you now are able to authenticate into Viya. To do so, you have two options:
- Running sas-viya auth login and entering your user id and password
sas-viya auth login
Enter credentials for https://gelcorp.rext03-0029.race.sas.com
Userid> [enter your user id]
Password> [enter your password]
Login succeeded. Token saved.
- Creating a .authinfo file with your userid and password in your home directory and then using loginviaauthinfo.py.
In your home directory, you’ll need to create an .authinfo file containing your default username and password. In your home directory, create a file named .authinfo with the following information.
default user [enter your user id] password [enter your password]
for example:
default user user1 password 321password123
Once this file has been created, you then will be able to use another tool in pyviyatools to authenticate into Viya:
/opt/pyviyatools/loginviaauthinfo.py
Explore the loginviaauthinfo.py documentation for more details on setting up the .authinfo file Once you have authenticated into Viya, you now will have full access to all the tools inside pyviyatools, including ValidateViya.
Using ValidateViya
Available Result Types
The next sections will detail the various arguments available for ValidateViya. Here’s a quick summary of what’s available:
| Argument | Description |
| -v/--verbose | Provides additional output |
| -s/--silent | Limits output to results only |
| -o/--output | Returns results in one of eight styles |
| -g/--generate-tests | Creates a custom tests file for editing |
| -c/--custom-tests | Uses a custom tests file for testing |
| -d/--output-directory | Selects the directory to output files |
Additionally, the following sections will explore the various output types available for ValidateViya results. Here’s a quick summary of the output options available:
| Output Type | Output Options |
| CSV | csv (default) |
| JSON | json simplejson passfail-full |
| Command Line | simple passfail |
| HTML | report report-full |
Default Results
ValidateViya does contain a multitude of options, but can be run using entirely default settings with:
/opt/pyviyatools/validateviya.py
This will run a default series of tests on your Viya environment and return the test results in csv format. The default test series includes eight total tests, seven of which involve collecting important metrics for the environment and one of which involves running test code. Each of these tests report back pertinent details about the data they’ve generated. Example results on a functioning environment could look like the following:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
Default Tests
To help you further understand ValidateViya, I’ve provided a description of each of the eight default tests:
| Test ID | Test Name | Description |
| 0 | Logged in User | Prints the name and id for the authenticated user. |
| 1 | List Users | Lists the name and id for all users in the Viya environment. |
| 2 | List Base Folders | Lists and provides a description for the base folders for the Viya environment. |
| 3 | List CAS Servers | Lists the CAS servers available on the Viya environment. |
| 4 | List CAS Server Metrics | Provides server metrics for the CAS servers on the Viya environment including the name, number of nodes, number of cores, system CPU time, and total memory. By default, the only CAS server which is analyzed is the default CAS server, cas-shared-default. |
| 5 | List CAS Server CASLibs | Lists the CAS Libraries available in each CAS server on the Viya environment. By default, the only CAS server examined is the default CAS server. |
| 6 | List CASLib Tables | Lists the tables loaded in the specified CAS Libraries in the Viya environment. By default, the only caslib that is examined is systemData, found inside the default CAS server. |
| 7 | Run Test SAS Code | Finds a compute context, creates a compute session and executes sample SAS code. The SAS code that is run utilizes both base SAS procs as well as proc CAS. |
Changing Output
These default results come in csv format without labels for each test. For more information on each test result, you can use the --verbose (-v) argument.
/opt/pyviyatools/validateviya.py --verbose
When the tests are running, you’ll receive more information on the process of testing, as seen below:
After your tests are complete, the results of each test will be labeled and a newline will separate each test.
ValidateViya provides the option to print results in many ways. To select an output format besides csv, use the --output (-o) argument. For the most detailed results, use the json output.
/opt/pyviyatools/validateviya.py --output json
As mentioned, the json output provides the most detailed output. The provided screenshot is only a small portion of the results of one test. To get results in json format without the links items (highlighted in red), you can use the simplejson output type. This will drastically decrease the volume of results, while maintaining the json format. Notice, though, that there are significantly more detailed results with simplejson than csv.
/opt/pyviyatools/validateviya.py --output simplejson
Another output result option is simple, which provides a more user-friendly version of simplejson results. Also included is passfail, which returns either “pass” if all tests have passed, or “fail” if one or more tests is failing, as well as passfail-full, which returns “pass” or “fail” results for each individual test.
/opt/pyviyatools/validateviya.py --output simple
/opt/pyviyatools/validateviya.py --output passfail
/opt/pyviyatools/validateviya.py --output passfail-full
Output as a HTML Report
ValidateViya has a unique output feature that allows you to view your test results as an HTML report. This report is viewable like a webpage but is saved to your computer locally.
To create a summary HTML report for your test results, use the report output type:
/opt/pyviyatools/validateviya.py --output report
By default, the HTML report will be saved to the current directory with the filename report-[MONTH.DAY.YEAR-TIME].html. Be sure to run ValidateViya inside a directory that you have permissions to read and write to, or you will encounter the following error.
Exploring the generated report, you can see a summary of all the test results, as well as some limited results for each test.
For a more detailed HTML report containing the full results for each test, use the report-full output type:
/opt/pyviyatools/validateviya.py --output report-full
Just like the report output type, the report will be saved to the current directory with the filename report-[MONTH.DAY.YEAR-TIME].html. Opening the generated report, the format is very similar to the report output type, but there is noticeably more information provided for each test.
To save the report in an alternative directory, use the --output-directory (-d) argument. By providing an alternative directory with --output-directory, the report will still be saved with its traditional filename, but inside a user-specified directory. For example, it may be beneficial to create a reports directory (home/user1/reports) to hold a series of reports over time. To point the --output-directory argument to your newly created directory, run:
/opt/pyviyatools/validateviya.py --output report --output-directory /home/user1/reports
Customizing Tests
Generating a Custom Test Suite
To customize the tests inside of ValidateViya, you can use the --generate-tests (-g) argument. This will save a custom tests json to your current directory as testPreferences.json. Your test suite can be renamed with the optional filename parameter. As well, --generate-tests can be combined with the --output-directory argument to save the file in a custom directory.
/opt/pyviyatools/validateviya.py --generate-tests
/opt/pyviyatools/validateviya.py --generate-tests customTest.json
/opt/pyviyatools/validateviya.py --generate-tests customTest.json --output-directory /home/user1/tests
The default test suite contains the eight default tests that we explored earlier in this blog. Each test contains the following properties:
- id: a unique numerical id for the test, appearing in ascending order, starting with 0
- name: a unique test name
- active: a boolean value determining whether to run the test
- req: the API request used
- cols: the array of fields that will be reported for csv and report-full output
- type: either data collection or computation
Some more advanced tests contain other properties, which we will explore later.
Using a Custom Test Suite
After altering testPreferences.json, you can feed your custom test suite into ValidateViya with the --custom-tests (-c) argument. To load in a custom test suite, run:
/opt/pyviyatools/validateviya.py --custom-tests testPreferences.json
Selecting Output Columns
For the CSV and report-full output types, the amount of data in your test results is limited to certain columns. Each test contains a cols property, which is an array of the fields that will be reported as columns in your test results. To examine the fields that there are to choose from, you can run your tests with the json or simplejson output type. For test results with an items property, the fields inside a given item are those that can be included in the cols array. For example, Test 2: List Base Folders contains the items property, where each item contains a multitude of fields.
Looking at the default test suite, Test 2 reports back two fields as columns: name and description. To expand this to include another available field, such as the memberCount, testPreferences.json can be altered such that cols contains another item.
If a test result does not have an items property, all of the fields from the json output can be selected for the cols array. For example, Test 4: List CAS Server Metrics does not contain an items property in its json output.
Looking at the default test suite, Test 4 reports five fields as columns: serverName, systemNodes, systemCores, cpuSystemTime, and memory. Notice how all of these are surface-level properties for the json output.
Saving Output as a File
Besides report and report-full, there is no internal way to save results as a file with ValidateViya. To save any output type as a file, run ValidateViya like so:
/opt/pyviyatools/validateviya.py --silent > file.csv
Using the > symbol redirects the output of validateviya.py entirely into file.csv, while the --silent (-s) argument limits output to only test results. This combination of arguments will result in file.csv looking like so:
This method can be combined with any of the text-based output options:
/opt/pyviyatools/validateviya.py --output json --silent > file.json
/opt/pyviyatools/validateviya.py --output passfail-full --silent > passfail.jsonTesting Additional Variables
Several tests (tests 4-6) test a variable number of items. It may be beneficial to test more than just the default values. For example, Test 4: List CAS Server Metrics is designed to test any number of CAS servers. By default, it only tests the default CAS server (cas-shared-default). In a Viya environment with more than one CAS server, it would be beneficial to test all of them.
Each test with a variable number of items contains a reqVariable property, which specifies the name of the property for that test which contains the variable items. Looking at Test 4: List CAS Server Metrics, the reqVariable is “servers”, which corresponds to the servers property, which, by default, contains only one item: the name of the default CAS server.
If the Viya environment contains more than one server, it can be added to the servers property like so:
Notice that the servers property is not an array, but an array of arrays, where each internal array only contains a single element: the name of a CAS server. This is designed for other tests that require more than one value in each variable item. For example, Test 6: List CASLib Tables requires both the name of a CASLib and its corresponding server. In the caslibs property for test 6, each CASLib is passed as an array containing first the name of the CAS server, and then the CASLib.
Creating Custom Tests
Given an API endpoint from the SAS Viya REST APIs, a custom ValidateViya test can be created. First, create a test object with the required fields (name, req, cols, active, type, and id) and append it to the tests array in testPreferences.json.
{
"name": "List Reports",
"req": [
"/reports/reports"
],
"cols": [
"id",
"name",
"createdBy"
],
"active": "True",
"type": "Data Collection",
"id": "8"
}
Be sure to maintain the ascending order of test ids inside testPreferences.json. As well, increment the count property for the test suite to ensure that it matches the number of unique tests inside the tests property.
Custom tests that test a variable number of items can also be created but be sure to implement them with a reqVariable and variable field. As well, the req field needs to be formatted in the same manner as the default tests. As an example, the API endpoint for Test 4: List CAS Server Metrics is /casManagement/servers/[SERVER]/metrics. Test 4 can test any number of cas servers, resulting in the reqVariable of servers. The req field is formatted like so:
"req": [
"/casManagement/servers/",
"/metrics"
],
By splitting the req field into multiple parts, ValidateViya knows to insert the values from servers into the values of req, forming a coherent API request. As an example, when ValidateViya takes the value “cas-shared-default” from the servers field, it is then inserted into the request to form “ “/casManagement/servers/cas-shared-default/metrics.”
As explored earlier, some tests may require more than one value in each variable item (such as Test 6: List CASLib Tables). This can be achieved by splitting the req variable in the same way as seen earlier and making the variable field an array of the multiple values that are required. For example, test 6 contains:
"req": [
"/casManagement/servers/",
"/caslibs/",
"/tables?limit=10000"
],
"caslibs": [
[
"cas-shared-default",
"systemData"
]
],
"reqVariable": "caslibs",For each [SERVER, CASLIB] array value inside of the caslibs property, an API request will be formed in the format /casManagement/servers/[SERVER]/caslibs/[CASLIB]/tables?limit=10000.
Conclusion
ValidateViya, like all the tools available in pyviyatools, can be incredibly useful to a SAS administrator. By providing a reliable tool to validate a new or existing Viya environment, ValidateViya can automate one of the many tasks necessary to ensure that Viya is running smoothly. By providing customizability, ValidateViya is designed to fit with any Viya environment, making it another great member of the pyviyatools family.
More information
ValidateViya Manual - pyviyatools
Loginviaauthinfo Manual - pyviyatools
Find more articles from SAS Global Enablement and Learning here.
