If you want to work with VyPR (for normal Python programs or web services), or encounter any problems with VyPR, please contact us.
This tutorial assumes Python 2. We're working on Python 3!
We have a sample Flask-based web service for you to test VyPR with here. It comes with a sample query file, a simple configuration file and an end-point that you can query to generate some data.
Note:
VyPR can run in two modes: a VyPR thread can be started at the beginning of service start-up and used by every request, or a thread can be started for every request. The version we demonstrate here starts a new thread for every request, simply because this doesn't require setting up VyPR to be accessible globally in your service. More documentation on setting up threads globally is coming soon.
Start by pulling our setup script and running it from your service's root directory.
curl -L http://cern.ch/vypr/setup -o setup chmod +x setup ./setup
This will pull VyPR, its server and its analysis library, create the server's virtual environment, install dependencies and create the server's database.
To run the server, open a new terminal (tmux is useful here), navigate to VyPRServer/ and launch the virtual environment with source venv/bin/activate, then run
python run_service.py
This will start VyPR's server on port 8080, unless you specify a different port with the --port argument.
We'll start with the query file. The first time, pull our sample query file at http://cern.ch/vypr/VyPR_queries.py. This assumes that you have a function paths_branching_test in the module routes, in the package app. You probably don't have this, so follow the instructions at http://cern.ch/vypr/writing-queries.html to write your own queries.
We'll now create the VyPR configuration file. Again, a sample file can be pulled from http://cern.ch/vypr/vypr.config. Here, we tell VyPR that it should use the verdict server running at http://localhost:8080 and that it should turn its explanation mode on. Explanation mode currently means VyPR will add path recording instruments to enable path analysis once some results have been stored.
Assuming you're using Flask, to add VyPR to monitored service you should add the lines
app = Flask(...) ... from VyPR import Monitor vypr = Monitor() vypr.initialise(app)
Here, we import VyPR's monitoring mechanism, instantiate it, then initialise it over your Flask application. Initialisation includes adding special end-points to your service to control VyPR, and also adding before_request and teardown_request hooks to manage VyPR's monitoring thread.
Instrumentation adds the necessary instructions to your service that will interact with VyPR at runtime, allowing it to monitor for your queries without having to check every piece of information your program gives.
From the root directory of your service, run
python VyPR/instrument.py
This will take your queries and instrument the service accordingly.
With instrumentation performed and VyPR added to your service's code, you can run your service as normal and VyPR will work behind the scenes! The next step is analysing the data you get, for which we have built VyPR Analysis.
We provide a simple analysis script that you can pull from http://cern.ch/vypr/sample_analysis.py to the root directory of your project (this is where the analysis library is).
This is a simple script that shows some of the basic functions provided by the analysis library to explore results of your queries. We provide some explanation of it in Part 1 of our examples.
For a more complex example of using the analysis library, take a look at Part 2. It was originally created to reproduce some of the results obtained when applying VyPR at the CMS Experiment and shows how to use the methods in the analysis library for comparing different paths taken through a program and visualising this comparison.