Package: runregistry
Run Registry ClientPython client to retrieve and query data fromCMS Run Registry.To switch toDev CMS Run Registrydo:importrunregistryrunregistry.setup("development")Possible values are"production","development"(will use the development deployment as target),"qa"(will use the new SSO proxy on the production deployment) or"local"(if you have a local instance of Run Registry's backend running).Python version and Virtual envPython version>=3.6 is required for this package.
A virtual environment is also required, if you are in lxplus you should run the following commands:virtualenv-p`whichpython3`venvsourcevenv/bin/activateInstallationpipinstallrunregistryAuthentication PrerequisitesWarningGrid certificates have been deprecated by CERN. As of version1.0.0, therunregistryclient only works with a client ID and a secret.You will need to create an SSO registration for your application which is going to be using the runregistry API client.Instructions on how to do it can be found on thecernrequestsGitHub page.Once you have a client ID and a secret, you will need to store them in a file named.env. Asample fileis provided so that you can edit it and rename it to.env.Alternatively, you can runexport SSO_CLIENT_ID=...andexport SSO_CLIENT_SECRET=...on the same terminal that you will be running your python script in.UsageGet a single run (get_run):importrunregistryrun=runregistry.get_run(run_number=328762)Query several runs (get_runs):importrunregistryruns=runregistry.get_runs(filter={'run_number':{'or':[328762,323555,323444]}})Apply a custom filter (run_numbers between 309000 and 310000 which had at least one GOOD dt lumisection)importrunregistryruns=runregistry.get_runs(filter={'run_number':{'and':[{'>':309000},{'<':310000}]},'dt-dt':'GOOD'})Do note that we usedt-dt('dt' twice) this is due to the fact that there are multiple workspaces, the first 'dt' states we are in dt workspace, the second 'dt' states we want column 'dt'. So the syntax for status flags is{workspace}-{column}. If we wanted runs with the strip column from tracker workspace to have at least 1 lumisection GOOD, the query would look like this:importrunregistryruns=runregistry.get_runs(filter={'run_number':{'and':[{'>':309000},{'<':310000}]},'tracker-strip':'GOOD'})Depending on the attribute you can use different operators:OperatorsAttributeSupported operatorsnumber'=', '>', '<', '>=', '<=', '<>'String=, like, notlikeBoolean= (true, false)date'=', '>', '<', '>=', '<=', '<>'When usinglikeornotlikeoperator, you must surround your query with percentage signs, see example below.When filtering for triplet attributes (anything that is GOOD/BAD/STANDBY...) you must not use any String values, the only value allowed is strict equality '=' and is set by default. The values allowed are GOOD, BAD, STANDBY, NOTSET, EXCLUDED and EMPTY.You can combine the filters as well:importrunregistryruns=runregistry.get_runs(filter={'run_number':{'and':[{'>':309000},{'<':310000}]},'hlt_key':{'like':'%commissioning2018%'}'significant':{'=':True}})If by observing the Network Requests in RR web application, you want to use the same filters observed by the network request. Just passsignore_filter_transformation=Trueto any query.Example (run_numbers between 309000 and 310000 which had at least one GOOD dt lumisection):importrunregistryruns=runregistry.get_runs(filter={'run_number':{'and':[{'>':309000},{'<':310000}]},# Remember! this will only work if you pass ignore_filter_transformation=True (please read above what this means), otherwise use the other examples'oms_attributes.hlt_key':{'like':'%commissioning2018%'},'triplet_summary.dt-dt.GOOD':{'>':0}},ignore_filter_transformation=True)Also, if by observing the Network Requests in RR web application, you want to obtain the data as it is seen in the network requests. Justcompress_attributes=False, for example:importrunregistryruns=runregistry.get_runs(filter={'run_number':{'and':[{'>':309000},{'<':310000}]},'dt':'GOOD'},compress_attributes=False)querying by comments and cause is not yet possibleGet datasetimportrunregistrydataset=runregistry.get_dataset(run_number=327604,dataset_name="/PromptReco/HICosmics18A/DQM")Get datasetsimportrunregistrydatasets=runregistry.get_datasets(filter={'run_number':{'and':[{'>':309000},{'<':310000}]}})Get LumisectionsGet the array of lumisectionsYou can query the lumisections of a run (or dataset), you will need the run number and the dataset name (when querying for a run, the dataset name must be 'online')importrunregistry# lumisections = runregistry.get_lumisections(run_number, dataset_name)lumisections=runregistry.get_lumisections(327743,"/PromptReco/HICosmics18A/DQM")The response will be an array of lumisections which will contain{workspace}-{column}: {"status":"Either GOOD/BAD/STANDBY...", "comment": "a comment made for the range", "cause":"a common repeated cause"}To get OMS data: use the OMS API. You should only use Run Registry for data that RR is responsible for.
However if you still want to access OMS lumisections, you can do so like this:Previous Run Registry allowed you to change OMS (in that time WBM) attributes per dataset, if you need certain dataset lumisections you can provide the name of the RR dataset in the second argument:importrunregistry# oms_lumisections = runregistry.get_oms_lumisections(run_number, dataset_name)oms_lumisections=get_oms_lumisections(327743,'online')# If you want to get particular dataset that is not online for OMS lumisections:dataset_oms_lumisections=get_oms_lumisections(327743,'/PromptReco/HICosmics18A/DQM')Get lumisection rangesUsually there will be runs/datasets which contain an enormous amount of lumisections (some even more than 5000), therefore it can be heavy on the API to query for these type of lumisections.A query to retrieve ranges is also possible, you can do it like this:importrunregistry# lumisections = runregistry.get_lumisection_ranges(run_number, dataset_name)lumisections=runregistry.get_lumisection_ranges(327743,"/PromptReco/HICosmics18A/DQM")You will receive an array of ranges, that apart from stating the triplets (comment, status and cause) for each column, the array will consist of two more attributes calledstart(lumisection where range starts) andend(lumisection where range ends).Handling the responseWhen filtering runs, the attributes from the response get divided into those belonging to OMS and those belonging to RR (to see which belong to which, see the tables below, or go through a response).Those that belong to OMS are inside "oms_attributes".Those that belong to RR are inside "rr_attributes".Attributes available to queryAccording to the type of attribute (number, string, boolean), see the Operator table above to see which types of operators can be applied to queryingOms Attributes:AttributeTypeBelongs torun_numbernumberOMSenergynumberOMSl1_keystringOMSb_fieldnumberOMShlt_keystringOMSl1_menustringOMSl1_ratenumberOMSdurationnumberOMSend_luminumberOMSend_timedateOMSsequencestringOMSinit_luminumberOMSclock_typestringOMSstart_timedateOMSfill_numbernumberOMSl1_hlt_modestringOMSlast_updatedateOMSls_durationnumberOMSstable_beambooleanOMStrigger_modestringOMScmssw_versionstringOMSrecorded_luminumberOMSdelivered_luminumberOMStier0_transferbooleanOMSl1_key_strippedstringOMSfill_type_party1stringOMSfill_type_party2stringOMShlt_physics_ratenumberOMShlt_physics_sizenumberOMSfill_type_runtimestringOMShlt_physics_counternumberOMSl1_triggers_counternumberOMSl1_hlt_mode_strippedstringOMShlt_physics_throughputnumberOMSinitial_prescale_indexnumberOMSbeams_present_and_stablebooleanOMSes_includedbooleanOMShf_includedbooleanOMSdaq_includedbooleanOMSdcs_includedbooleanOMSdqm_includedbooleanOMSgem_includedbooleanOMStrg_includedbooleanOMShcal_includedbooleanOMStcds_includedbooleanOMSpixel_includedbooleanOMStracker_includedbooleanOMS*_included (be sure to add it to the validation runregistry/attributes if it's not here)booleanOMSRR Run Attributes:AttributeTypeBelongs toclassstringRRstatestringRRsignificantbooleanRRstop_reasonstringRRRR Dataset Attributes:AttributeTypeBelongs todataset_namestringRRdt_statestringRRcsc_statestringRRhlt_statestringRRl1t_statestringRRrpc_statestringRRtau_statestringRRbtag_statestringRRecal_statestringRRhcal_statestringRRlumi_statestringRRmuon_statestringRRctpps_statestringRRcastor_statestringRRegamma_statestringRRglobal_statestringRRjetmet_statestringRRtracker_statestringRRThe dt_state, csc_state and so on, are the workspace OFFLINE states of the datasets, they can be either OPEN, SIGNOFF or COMPLETED.For Offline and Online status flags, filtering is also available. The Attribute is composed by{workspace}-{column}. So for example if we want to query for GOOD tracker-strip datasets of runs between 309000 and 310000, we would do it like this:importrunregistrydatasets=runregistry.get_datasets(filter={'tracker-strip':'GOOD''run_number':{'and':[{'>':309000},{'<':310000}]},})Generating JSONsIn order to generate JSONs (like the golden json) you must send the configuration of the attributes you wish the generated json to satisfy (in json-logic)The json logic below generates a json file for the dataset name: "/PromptReco/Collisions2018A/DQM" although you can use placeholders just as in the json portal as: /PromptReco/Collisions2018(A|B)/DQM or /PromptReco/Collisions2018_/DQM the underscore '_' is a wildcard.importrunregistryjson_logic={"and":[{">=":[{"var":"run.oms.energy"},6000]},{"<=":[{"var":"run.oms.energy"},7000]},{">=":[{"var":"run.oms.b_field"},3.7]},{"in":["25ns",{"var":"run.oms.injection_scheme"}]},{"==":[{"in":["WMass",{"var":"run.oms.hlt_key"}]},False]},{"==":[{"var":"lumisection.rr.dt-dt"},"GOOD"]},{"==":[{"var":"lumisection.rr.csc-csc"},"GOOD"]},{"==":[{"var":"lumisection.rr.l1t-l1tmu"},"GOOD"]},{"==":[{"var":"lumisection.rr.l1t-l1tcalo"},"GOOD"]},{"==":[{"var":"lumisection.rr.hlt-hlt"},"GOOD"]},{"==":[{"var":"lumisection.oms.bpix_ready"},True]}]}generated_json=runregistry.create_json(json_logic=json_logic,dataset_name_filter="/PromptReco/Collisions2018A/DQM")AdvancedYou can also manipulate runs via API:Mark run significant:runregistry.make_significant_runs(run=362761)Reset RR attributes and reload data from OMS:runregistry.reset_RR_attributes_and_refresh_runs(run=362761)Move runs from one state to another:runregistry.move_runs("OPEN","SIGNOFF",run=362761)TroubleshootingSupportIf you have any questions, or the client is not working properly feel free to drop our team an email atcms-dqm-coreTeam@cern.ch.[Package developers] Updating the package on PyPIpython3-mpipinstall--upgradepipbuildtwine
python3-mbuild
python3-mtwineupload--skip-existing--repositorypypidist/*Instructions fromhere.TestingLocallyTODORemove the qa environment after migration.You will be needing a file named.envwith the following variablesSSO_CLIENT_ID=<change>SSO_CLIENT_SECRET=<change>ENVIRONMENT=qaWhile most of the tests work on the development deployment, some fail and need the production one. This is the reason we are settingENVIRONMENT=qa.python3-mvenvvenvsourcevenv/bin/activate
pipinstall-rrequirements.txt
pipinstall-rtesting-requirements.txt
pipinstall-e.
pytesttests-sGitHub actionsAutomated GitHub actions run on each push to the repository. The workflow is definedhereThe same env variables are needed as inlocal testing, so those are addedhere.FAQDoes this work with Python 2.7?No.Should I be usingrunregistry_api_clientfor getting OMS data?No*.Our recommendation is to query Run Registry only for data that RR is responsible for.*It's not that you can't, it's just that this puts extra burden on the application, making it slow for everyone.Is the token stored somewhere and reused?No, almost every function call gets a new token. This is not ideal, and it may be improved in the future.