Initial skeleton

Signed-off-by: Greg Haskins <greg@manetu.com>

Author: ghaskins

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Manetu
+Copyright (c) Manetu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -0,0 +1,41 @@
+# Copyright © Manetu, Inc.  All rights reserved
+
+NAME=manetu-sparql-loadtest
+BINDIR ?= /usr/local/bin
+OUTPUT=target/$(NAME)
+SHELL=/bin/bash -o pipefail
+
+SRCS += $(shell find src -type f)
+
+COVERAGE_THRESHOLD = 98
+COVERAGE_EXCLUSION += "manetu.sparql-loadtest.main"
+
+all: scan bin
+
+bin: $(OUTPUT)
+
+scan:
+	lein cljfmt check
+	lein bikeshed -m 120 -n false
+	#lein kibit
+	lein eastwood
+
+.PHONY: test
+test:
+	lein cloverage --fail-threshold $(COVERAGE_THRESHOLD) $(patsubst %,-e %, $(COVERAGE_EXCLUSION)) | perl -pe 's/\e\[?.*?[\@-~]//g'
+
+$(OUTPUT): $(SRCS) Makefile project.clj
+	@lein bin
+
+$(PREFIX)$(BINDIR):
+	mkdir -p $@
+
+install: $(OUTPUT) $(PREFIX)$(BINDIR)
+	cp $(OUTPUT) $(PREFIX)$(BINDIR)
+
+clean:
+	@echo "Cleaning up.."
+	@lein clean
+	-@rm -rf target
+	-@rm -f *~
+

README.md

@@ -1,2 +1,103 @@
 # sparql-loadtest
-A utility to measure SPARQL query performance on the Manetu Platform
+
+The sparql-loadtest is a command-line tool to measure SPARQL query performance on the Manetu platform.  The basic premise is that you may specify an arbitrary query with optional initial-bindings, and the tool will run a fixed number of iterations with the specified concurrency.  After the test, the tool will compute and report various metrics such as the min/ave/max latency and the throughput rate.
+
+This utility helps measure your cluster's overall query performance and helps optimize your SPARQL query.
+
+## Installing
+
+### Prerequisites
+
+- JDK (tested with JDK22)
+- make
+
+## Building
+
+### Prerequisites
+
+In addition to the requirements for installation, you will also need:
+
+- Leiningen
+
+```
+$ make
+```
+## Usage
+
+```shell
+$ java -jar ./target/uberjar/app.jar -h
+Usage: manetu-sparql-loadtest [options]
+
+Measures the performance metrics of concurrent SPARQL queries to the Manetu platform
+
+Options:
+  -h, --help
+  -v, --version                 Print the version and exit
+  -u, --url URL                 The connection URL
+      --insecure                Disable TLS host checking
+      --[no-]progress    true   Enable/disable progress output (default: enabled)
+  -l, --log-level LEVEL  :info  Select the logging verbosity level from: [trace, debug, info, error]
+  -c, --concurrency NUM  64     The number of parallel jobs to run
+  -d, --driver DRIVER    :gql   Select the driver from: [null, gql]
+  -q, --query PATH              The path to a file containing a SPARQL query to use in test
+  -b, --bindings FILE           (Optional) The path to a CSV file to cycle through as input bindings to each SPARQL query
+  -n, --nr COUNT         10000  The number of queries to execute
+```
+
+### Connection details
+
+In addition to --url and optionally --insecure, you must set the environment variable MANETU_TOKEN to a personal access token issued from your Manetu cluster.
+
+### Test parameters
+
+The parameters of the test include the level of concurrency (--concurrency), the number of iterations (--nr), the query (--query) specified as a path to a file containing a SPARQL expression, and optionally a set of initial bindings (--bindings) defined as a path to a CSV file.
+
+#### SPARQL expression
+
+The SPARQL expression must be legal SPARQL grammar.  For example:
+
+```sparql
+PREFIX manetu: <http://manetu.com/manetu/>
+PREFIX mmeta:  <http://manetu.io/rdf/metadata/0.1/>
+
+SELECT ?label
+
+WHERE  {
+       ?s manetu:email ?email ;
+          mmeta:vaultLabel ?label .
+ }
+```
+The expression may optionally contain input bindings that will be satisfied by the CSV input file specified by --bindings.  The utility will submit the column header of the CSV file as a binding verbatim, with the requisite "?" prefix.  For example, for the following CSV:
+
+```csv
+id,name,email
+1,alice,alice@example.com
+2,bob,bob@example.com
+```
+This would generate bindings such as:
+
+```json
+{"?id": "1", "?name": "alice", "?email": "alice@example.com"}
+```
+The utility will cycle through the rows for cases where the number of iterations (--nr) exceeds the rows in the --bindings.  For example, if the initial bindings contains 4 rows (numbered 1-4) and the test is executed with --nr 10, the utility will generate queries with the rows cycled e.g. [1 2 3 4 1 2 3 4 1 2].
+
+### Example
+
+For this example, we will use a query to search the graph by email to return a vault label.  We will use several files from this repository for our [query](./examples/by-email/label-by-email.sparql) and [bindings](./examples/by-email/bindings.csv).  Running this example assumes you have onboarded some [mock-data](./examples/by-email/data-loader.csv) using the Manetu [data-loader](https://github.com/manetu/data-loader) utility.
+
+```shell
+$ java -jar ./target/uberjar/app.jar -u https://manetu.example.com --insecure -q ./examples/by-email/label-by-email.sparql --bindings ./examples/by-email/bindings.csv -n10000 -c64
+```
+If successful,  the test should display something similar to the following:
+
+```shell
+2024-10-17T20:21:33.172Z INFO processing 10000 requests with concurrency 64
+2024-10-17T20:21:33.175Z INFO Loading bindings from: ./examples/by-email/bindings.csv
+10000/10000   100% [==================================================]  ETA: 00:00
+|-----------+----------+------+-------+--------+--------+--------+----------------+--------|
+| Successes | Failures |  Min |   Q1  | Median |   Q3   |   Max  | Total Duration |  Rate  |
+|-----------+----------+------+-------+--------+--------+--------+----------------+--------|
+| 10000.0   | 0.0      | 27.1 | 87.05 | 113.04 | 132.75 | 292.57 | 20517.48       | 487.39 |
+|-----------+----------+------+-------+--------+--------+--------+----------------+--------|
+```
+

dev-resources/user.clj

@@ -0,0 +1,9 @@
+;; Copyright © Manetu, Inc.  All rights reserved
+
+(ns user
+  (:require [clojure.tools.namespace.repl :refer [refresh]]
+            [manetu.sparql-loadtest.main :as main]))
+
+(defn run
+  [params]
+  (apply main/-app (clojure.string/split params #" ")))

examples/by-email/bindings.csv

@@ -0,0 +1,101 @@
+email
+haireton0@cam.ac.uk
+braithmill1@reverbnation.com
+raggas2@tinyurl.com
+hfreda3@dagondesign.com
+otomich4@digg.com
+cneame5@sakura.ne.jp
+ltooley6@chicagotribune.com
+bmoryson7@last.fm
+cneylan8@istockphoto.com
+jkidstoun9@w3.org
+gchaffena@deviantart.com
+pcollcottb@timesonline.co.uk
+meagellc@slideshare.net
+dtalmand@gmpg.org
+bdownse@yahoo.co.jp
+mmcnallyf@xinhuanet.com
+jcradduckg@wordpress.com
+hecklyh@mapquest.com
+sbartlomiejczyki@google.com
+lrossonij@ucla.edu
+cmaccaugheyk@live.com
+mlambartonl@hc360.com
+dsambedgem@economist.com
+ahamiltonn@apple.com
+zchancelloro@independent.co.uk
+vcowplandp@omniture.com
+eramsdaleq@de.vu
+tratchfordr@devhub.com
+mclemencons@twitter.com
+svollert@cbsnews.com
+rsnowdonu@guardian.co.uk
+tgianolov@bloomberg.com
+mschwandermannw@weebly.com
+jcicchettox@deliciousdays.com
+stomensony@accuweather.com
+kgreastyz@unesco.org
+ngostyke10@jugem.jp
+yattle11@nymag.com
+jmanicom12@apple.com
+bfantonetti13@businessinsider.com
+rperree14@salon.com
+ncrathern15@chicagotribune.com
+tbremen16@printfriendly.com
+agiacomini17@tmall.com
+lspurgeon18@arizona.edu
+fsterry19@google.com.br
+tduffill1a@soundcloud.com
+rgreenacre1b@prlog.org
+rscott1c@un.org
+cbanbury1d@cnet.com
+rdeppen1e@tinyurl.com
+wbraffington1f@sfgate.com
+cskittle1g@digg.com
+vgarside1h@cpanel.net
+mwhittek1i@biblegateway.com
+igreeve1j@studiopress.com
+bcaudray1k@amazon.co.uk
+sgooder1l@phpbb.com
+lleverton1m@google.com
+wbutterfint1n@walmart.com
+nmccleary1o@un.org
+ltrainor1p@indiatimes.com
+rpolini1q@psu.edu
+lcarnock1r@shinystat.com
+dyakubov1s@skype.com
+mdrust1t@economist.com
+gespie1u@aol.com
+jgarbett1v@feedburner.com
+cswalowe1w@craigslist.org
+rjouannisson1x@sun.com
+jwalenta1y@flickr.com
+athame1z@yandex.ru
+jpoynser20@whitehouse.gov
+dgeorgot21@de.vu
+cserrell22@ox.ac.uk
+mgosnall23@histats.com
+mcogar24@fotki.com
+mmelhuish25@newsvine.com
+mliddon26@gravatar.com
+dvankov27@myspace.com
+ldurward28@nifty.com
+lricciardi29@shareasale.com
+lnobles2a@wiley.com
+lfisbey2b@angelfire.com
+sgeydon2c@patch.com
+ecargenven2d@wikia.com
+whaigh2e@globo.com
+lbrack2f@instagram.com
+mhustler2g@cnet.com
+muden2h@businessinsider.com
+poughtright2i@princeton.edu
+ecreaser2j@ftc.gov
+waudus2k@nih.gov
+rchurchard2l@sohu.com
+bchitty2m@livejournal.com
+arains2n@nyu.edu
+dtrett2o@imdb.com
+mpiechnik2p@buzzfeed.com
+eearey2q@mayoclinic.com
+bregus2r@squarespace.com

examples/by-email/data-loader.csv

@@ -0,0 +1,101 @@
+FirstName,LastName,Email,MailingCountry,Phone,Title,MobilePhone
+Hortense,Aireton,haireton0@cam.ac.uk,China,774-141-1849,Registered Nurse,144-282-8691
+Bard,Raithmill,braithmill1@reverbnation.com,Peru,983-911-7172,VP Product Management,859-147-5124
+Rhodie,Aggas,raggas2@tinyurl.com,Portugal,742-260-3395,Programmer IV,129-150-9854
+Holli,Freda,hfreda3@dagondesign.com,Portugal,559-829-1888,Marketing Assistant,676-465-8386
+Olive,Tomich,otomich4@digg.com,Portugal,696-175-4251,Software Engineer I,191-158-9736
+Curr,Neame,cneame5@sakura.ne.jp,Antigua and Barbuda,847-705-5168,Tax Accountant,319-834-0139
+Lavena,Tooley,ltooley6@chicagotribune.com,Indonesia,461-109-2836,Clinical Specialist,961-969-6280
+Bent,Moryson,bmoryson7@last.fm,South Africa,256-311-3793,Software Consultant,548-392-5370
+Cherice,Neylan,cneylan8@istockphoto.com,Thailand,174-917-1085,Desktop Support Technician,531-441-2476
+Jakob,Kidstoun,jkidstoun9@w3.org,Greece,362-947-7629,Teacher,693-592-3042
+Gabi,Chaffen,gchaffena@deviantart.com,Jordan,125-732-4741,Recruiter,328-709-2644
+Pauline,Collcott,pcollcottb@timesonline.co.uk,Russia,905-426-4893,Junior Executive,304-351-1564
+Margaretta,Eagell,meagellc@slideshare.net,Lithuania,451-332-3165,Research Nurse,203-363-3082
+Dominique,Talman,dtalmand@gmpg.org,Russia,753-582-5789,Research Assistant II,849-177-4302
+Bertram,Downs,bdownse@yahoo.co.jp,Mexico,663-760-3564,Marketing Assistant,379-971-3760
+Mylo,McNally,mmcnallyf@xinhuanet.com,Philippines,511-283-9564,Analog Circuit Design manager,240-643-7118
+Jacobo,Cradduck,jcradduckg@wordpress.com,China,711-762-8932,Staff Scientist,155-332-3945
+Hedvig,Eckly,hecklyh@mapquest.com,Thailand,504-426-3890,Assistant Professor,661-325-4538
+Shay,Bartlomiejczyk,sbartlomiejczyki@google.com,Cuba,224-174-9540,Chemical Engineer,498-966-8837
+Lora,Rossoni,lrossonij@ucla.edu,Ukraine,713-141-9527,VP Sales,336-175-0250
+Celestine,MacCaughey,cmaccaugheyk@live.com,Macedonia,603-315-6701,Budget/Accounting Analyst IV,442-871-8980
+Michele,Lambarton,mlambartonl@hc360.com,Greece,818-523-5941,Help Desk Operator,926-992-6924
+Darsie,Sambedge,dsambedgem@economist.com,Russia,660-235-2074,Graphic Designer,907-488-1645
+Aimil,Hamilton,ahamiltonn@apple.com,China,935-491-9584,Financial Advisor,885-782-8031
+Zea,Chancellor,zchancelloro@independent.co.uk,France,219-833-8596,Executive Secretary,940-439-1314
+Vincent,Cowpland,vcowplandp@omniture.com,Indonesia,733-212-9023,General Manager,511-605-8518
+Elfrieda,Ramsdale,eramsdaleq@de.vu,Uganda,734-865-8385,Human Resources Manager,804-448-7692
+Tedra,Ratchford,tratchfordr@devhub.com,United States,504-187-5766,Assistant Manager,629-521-6176
+Maximilianus,Clemencon,mclemencons@twitter.com,Philippines,132-644-2247,Actuary,759-213-5726
+Shep,Voller,svollert@cbsnews.com,Mexico,765-638-5495,Food Chemist,807-319-5451
+Rodd,Snowdon,rsnowdonu@guardian.co.uk,Palestinian Territory,242-775-5461,Senior Sales Associate,610-665-9951
+Tina,Gianolo,tgianolov@bloomberg.com,Portugal,806-772-7872,Budget/Accounting Analyst I,760-823-7063
+Merlina,Schwandermann,mschwandermannw@weebly.com,Ukraine,458-175-9979,Actuary,113-202-9089
+Joell,Cicchetto,jcicchettox@deliciousdays.com,China,880-610-6910,Technical Writer,110-923-9427
+Shelley,Tomenson,stomensony@accuweather.com,Indonesia,122-895-8062,Desktop Support Technician,105-415-0731
+Kayle,Greasty,kgreastyz@unesco.org,Peru,376-875-2645,Biostatistician III,843-310-4589
+Nevsa,Gostyke,ngostyke10@jugem.jp,Lithuania,995-788-5865,Safety Technician II,635-370-5722
+Yehudi,Attle,yattle11@nymag.com,Indonesia,777-411-6246,Help Desk Technician,970-184-7389
+Jackie,Manicom,jmanicom12@apple.com,Russia,698-834-9618,Financial Advisor,134-549-2597
+Benedick,Fantonetti,bfantonetti13@businessinsider.com,Sweden,129-356-1600,Senior Developer,293-379-5248
+Ray,Perree,rperree14@salon.com,Nigeria,641-255-6072,Automation Specialist IV,792-343-5240
+Nester,Crathern,ncrathern15@chicagotribune.com,Comoros,948-173-7998,Actuary,797-974-3994
+Torin,Bremen,tbremen16@printfriendly.com,Mexico,638-687-8201,Account Executive,842-246-6111
+Abbey,Giacomini,agiacomini17@tmall.com,Indonesia,752-409-7245,Office Assistant III,533-279-2044
+Luella,Spurgeon,lspurgeon18@arizona.edu,China,310-807-6342,Media Manager II,327-396-4345
+Francklin,Sterry,fsterry19@google.com.br,Indonesia,353-136-8226,Registered Nurse,553-429-8424
+Trixi,Duffill,tduffill1a@soundcloud.com,Venezuela,139-479-9874,Desktop Support Technician,262-900-0313
+Rosabelle,Greenacre,rgreenacre1b@prlog.org,United States,501-589-9741,Clinical Specialist,394-549-9520
+Rachel,Scott,rscott1c@un.org,France,100-259-1002,Desktop Support Technician,734-963-6128
+Corine,Banbury,cbanbury1d@cnet.com,Peru,280-480-8836,Mechanical Systems Engineer,138-782-2746
+Roz,Deppen,rdeppen1e@tinyurl.com,Afghanistan,954-690-5074,Registered Nurse,536-488-6009
+Wallis,Braffington,wbraffington1f@sfgate.com,Russia,677-501-8542,Automation Specialist III,891-593-4344
+Corie,Skittle,cskittle1g@digg.com,Papua New Guinea,581-187-4279,Information Systems Manager,191-226-8331
+Vachel,Garside,vgarside1h@cpanel.net,Poland,729-825-6386,Biostatistician II,262-324-0475
+Martainn,Whittek,mwhittek1i@biblegateway.com,Guatemala,953-198-5982,Mechanical Systems Engineer,861-542-6908
+Ivette,Greeve,igreeve1j@studiopress.com,Greece,964-351-9613,VP Sales,499-239-9600
+Broderick,Caudray,bcaudray1k@amazon.co.uk,Sweden,168-105-8228,Research Assistant III,134-316-6825
+Sal,Gooder,sgooder1l@phpbb.com,China,559-209-6802,Nurse,764-783-7957
+Lexine,Leverton,lleverton1m@google.com,Uzbekistan,337-412-1974,Automation Specialist IV,274-953-0641
+Westley,Butterfint,wbutterfint1n@walmart.com,Pakistan,850-466-7344,Staff Accountant II,203-713-9106
+Natal,McCleary,nmccleary1o@un.org,Indonesia,498-648-5087,Associate Professor,265-932-9935
+Loraine,Trainor,ltrainor1p@indiatimes.com,Indonesia,521-612-8712,Speech Pathologist,597-615-6166
+Rockie,Polini,rpolini1q@psu.edu,China,267-579-7542,VP Marketing,259-298-0015
+Lowe,Carnock,lcarnock1r@shinystat.com,Ireland,106-768-2433,VP Quality Control,188-704-0714
+Dawn,Yakubov,dyakubov1s@skype.com,Nigeria,899-459-2134,Assistant Manager,940-244-0720
+Michell,Drust,mdrust1t@economist.com,South Africa,560-778-8252,Paralegal,500-166-3697
+Genvieve,Espie,gespie1u@aol.com,Yemen,585-921-7103,Paralegal,774-995-5202
+Jillane,Garbett,jgarbett1v@feedburner.com,Poland,695-895-4375,Chief Design Engineer,849-344-9610
+Carson,Swalowe,cswalowe1w@craigslist.org,China,330-767-0455,Web Developer I,117-508-9266
+Robbin,Jouannisson,rjouannisson1x@sun.com,Indonesia,431-864-5388,Systems Administrator I,953-430-6999
+Jeri,Walenta,jwalenta1y@flickr.com,Tajikistan,610-281-6748,Senior Quality Engineer,498-597-2676
+Arliene,Thame,athame1z@yandex.ru,Indonesia,752-431-3754,Professor,681-300-8567
+Jeff,Poynser,jpoynser20@whitehouse.gov,Portugal,835-781-0613,Electrical Engineer,453-275-3289
+Daniella,Georgot,dgeorgot21@de.vu,Philippines,174-411-7036,Research Assistant II,414-140-4679
+Cherida,Serrell,cserrell22@ox.ac.uk,Thailand,994-676-8399,Financial Advisor,193-647-3816
+Maurizia,Gosnall,mgosnall23@histats.com,Russia,192-299-1719,Account Representative I,846-614-0188
+Marketa,Cogar,mcogar24@fotki.com,United States,515-211-2110,Senior Sales Associate,854-751-1679
+Milly,Melhuish,mmelhuish25@newsvine.com,China,620-243-2859,Graphic Designer,949-578-2926
+Micky,Liddon,mliddon26@gravatar.com,Portugal,444-368-1711,Dental Hygienist,552-457-5955
+Del,Vankov,dvankov27@myspace.com,Poland,422-539-2625,Programmer Analyst II,951-604-3207
+Lusa,Durward,ldurward28@nifty.com,Mexico,896-743-2755,Geologist III,180-117-4670
+Leshia,Ricciardi,lricciardi29@shareasale.com,China,795-112-5386,Assistant Professor,901-260-6097
+Lorrie,Nobles,lnobles2a@wiley.com,Mexico,581-635-9831,Developer III,734-500-8048
+Larissa,Fisbey,lfisbey2b@angelfire.com,Brazil,506-446-4718,Account Representative IV,510-676-5558
+Saxe,Geydon,sgeydon2c@patch.com,Thailand,464-791-4077,Structural Analysis Engineer,262-371-1284
+Eulalie,Cargenven,ecargenven2d@wikia.com,Russia,553-362-6429,Software Consultant,117-869-5254
+Way,Haigh,whaigh2e@globo.com,Portugal,744-449-9278,Budget/Accounting Analyst III,239-795-2443
+Lewiss,Brack,lbrack2f@instagram.com,China,825-540-0449,Librarian,436-290-0006
+Mattie,Hustler,mhustler2g@cnet.com,China,305-453-2353,Assistant Professor,987-898-7138
+Moe,Uden,muden2h@businessinsider.com,Poland,262-910-1433,Analyst Programmer,944-364-9135
+Padriac,Oughtright,poughtright2i@princeton.edu,Indonesia,760-872-5774,Internal Auditor,655-875-9766
+Emmeline,Creaser,ecreaser2j@ftc.gov,China,176-186-7404,Marketing Manager,846-521-1606
+Winny,Audus,waudus2k@nih.gov,Paraguay,846-212-4676,Editor,497-560-7764
+Ryann,Churchard,rchurchard2l@sohu.com,Dominican Republic,149-565-0752,Research Associate,325-127-1706
+Bryn,Chitty,bchitty2m@livejournal.com,France,849-604-5630,Account Representative IV,635-521-7941
+Anjanette,Rains,arains2n@nyu.edu,China,624-319-7104,Senior Developer,295-666-4202
+Dean,Trett,dtrett2o@imdb.com,Philippines,313-241-0348,Health Coach I,544-266-4613
+Maurizia,Piechnik,mpiechnik2p@buzzfeed.com,Indonesia,679-487-0992,Quality Engineer,662-696-6011
+Elia,Earey,eearey2q@mayoclinic.com,Nigeria,287-276-2445,Technical Writer,103-557-1317
+Bobette,Regus,bregus2r@squarespace.com,Thailand,392-422-1401,Account Coordinator,717-820-5134

examples/by-email/iri-by-email.sparql

@@ -0,0 +1,10 @@
+PREFIX rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX manetu: <http://manetu.com/manetu/>
+PREFIX mmeta:  <http://manetu.io/rdf/metadata/0.1/>
+
+SELECT ?iri
+
+WHERE  {
+       ?iri rdf:object ?email ;
+            rdf:predicate manetu:email .
+}

examples/by-email/label-by-email.sparql

@@ -0,0 +1,9 @@
+PREFIX manetu: <http://manetu.com/manetu/>
+PREFIX mmeta:  <http://manetu.io/rdf/metadata/0.1/>
+
+SELECT ?label
+
+WHERE  {
+       ?s manetu:email ?email ;
+          mmeta:vaultLabel ?label .
+}