BookmarkSubscribeRSS Feed

Validating SAS Viya Environments Has Never Been this Easy

Started ‎01-17-2023 by
Modified ‎01-20-2023 by
Views 2,869

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:

 

  1. 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.

 

  1. 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:

 

me_1_defaultResults.png

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:

 

me_2_verboseRunningResults.png

 

After your tests are complete, the results of each test will be labeled and a newline will separate each test.

 

me_3_verboseTestResults.png

 

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

 

me_4_jsonResults.png

 

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

 

me_5_simplejsonResults.png

 

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

 

me_6_simpleResults.png

 

/opt/pyviyatools/validateviya.py --output passfail

 

me_7_passfailResults.png

 

/opt/pyviyatools/validateviya.py --output passfail-full

 

me_8_passfailfullResults.png

 

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.

 

me_9_noPermissionsError.png

 

Exploring the generated report, you can see a summary of all the test results, as well as some limited results for each test.

 

me_10_summaryReportResults-423x1024.png

 

 

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.

 

me_11_reportFullResults-914x1024.png

 

 

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.

 

me_12_defaultTestSuite.png

 

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.

 

me_13_fieldsForColsProperty.png

 

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.

 

me_14_test2DefaultCols-300x222.png

 

me_15_test2CustomCols-300x244.png

 

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.

 

me_16_fieldsForColsPropertyNoItems-300x248.png

 

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.

 

me_17_test4defaultCols.png

 

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:

 

me_18_csvInFile-1024x697.png

 

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.json

 

Testing 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.

 

me_19_test4defaultVariables-1.png

 

If the Viya environment contains more than one server, it can be added to the servers property like so:

 

me_20_test4customVariables.png

 

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.

 

me_21_test6DefaultVariables.png

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

 

pyviyatools - Github

 

SAS Viya REST APIs

 

Loginviaauthinfo Manual - pyviyatools

 

Find more articles from SAS Global Enablement and Learning here.

Comments

This is a great addition, until now we had a manual check after update! I have read carefully this blog and was able to add some columns, for example in test 2 List Users, I have added column "creationTimeStamp". Is there also a way to add a filter to see only the new added users? Otherwise I will make a shell script, but it would be great to have this option in testPreferences.json. Thank you Karolina.

Version history
Last update:
‎01-20-2023 04:42 PM
Updated by:
Contributors

sas-innovate-2024.png

Available on demand!

Missed SAS Innovate Las Vegas? Watch all the action for free! View the keynotes, general sessions and 22 breakouts on demand.

 

Register now!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started