Ville Lindroos
Amazon Simple Queue Servicen hyödyntäminen tarratulostuksessa
Metropolia Ammattikorkeakoulu Insinööri (AMK)
Tieto- ja viestintätekniikka Insinöörityö
1.12.2021
Tekijä: Ville Lindroos
Otsikko: Amazon Simple Queue Servicen hyödyntäminen tarratu- lostuksessa
Sivumäärä: 24 sivua + 2 liitettä
Aika: 1.12.2021
Tutkinto: Insinööri (AMK)
Tutkinto-ohjelma: Tieto- ja viestintätekniikka Ammatillinen pääaine: Software Engineering
Ohjaajat: Osaamisaluepäällikkö Janne Salonen Tiiminvetäjä Jaro Koski
Provet Cloud on selainpohjainen eläinlääkäriklinikan hallintaohjelmisto. Sen on tar- koitus toimia kaikkien klinikalla käytettävien laitteiden kanssa, joihin kuuluvat myös tarratulostimet. Niitä pystyy käyttämään Provet Cloudin kanssa, kunhan ne on liitetty Raspberry Pi-laitteeseen, joka taas kommunikoi Provetin kanssa internetin kautta.
Jotta ne tietävät, onko Provetilla tulostettavia tarroja, ne joutuvat kysymään asiaa Provetilta SOAP-pyynnöillä useita kertoja minuutissa. Tällä hetkellä näitä tulostimia on käytössä useita kymmeniä, joten niistä syntyvä kuorma Provetin palvelimille on huomattava.
Projektin tarkoituksena oli vähentää tätä kuormaa noin 15 prosentilla hyödyntämällä Amazon SQS-jonoja. Tällöin jokaisella tulostimella olisi oma SQS-jono, ja Provet lä- hettäisi tulostimelle kuuluvat tarrat tulostimen SQS-jonoon. Näin tulostimet voisivat kysellä tarroja Provetin sijaan omalta SQS-jonoltaan.
Projekti saatiin päätökseen, ja SQS-toiminnallisuus on toiminut testeissä hyvin, mutta sitä ei ole vielä otettu asiakaskäyttöön. Pilotti käyttöönotosta on suunniteltu yhdelle klinikalle, jonka jälkeen toiminnallisuus voitaisiin ottaa laajempaan käyttöön, mikäli pi- lotti sujuu hyvin.
SQS-toiminnallisuudelle löydettiin projektin aikana myös muita mahdollisia käyttötar- koituksia: SQS-jonoihin voitaisiin tarrojen lisäksi lähettää myös komentoja. Näillä ko- mennoilla voitaisiin esimerkiksi käynnistää tarratulostin uudestaan, mikä helpottaisi klinikan henkilöstön ja Provetin asiakastuen työtä.
Avainsanat: SQS, AWS, Provet Cloud, tarratulostus, eläinlääketiede
Author: Ville Lindroos
Title: Utilizing Amazon Simple Queue Service in label printing Number of Pages: 24 pages + 2 appendices
Date: 1 December 2021
Degree: Bachelor of Engineering
Degree Programme: Information and Communication Technology Professional Major: Software Engineering
Supervisors: Janne Salonen, Head of School Jaro Koski, Team Lead
Provet Cloud is a web based veterinary practice management software. It is
designed to work with all devices used by the clinic, including label printers. Those can be used with Provet, when they are connected to a Raspberry Pi, which in turn is connected to Provet over the internet. Label printers receive printable labels from Provet by polling it with SOAP requests multiple times per minute. There are currently dozens of printers online, so these SOAP requests cause a significant load to
Provet’s servers.
The purpose of this project was to reduce this load by about 15 % utilizing Amazon SQS queues. The idea was that each printer would have its own SQS queue, and Provet would send new labels to the responsible printer’s SQS queue. This way the printers could poll the SQS queue instead of Provet.
The project was completed, and the SQS functionality has been working well during testing, but it has not been deployed to any customers yet. A pilot deployment is planned to a single clinic, and if all goes well, the functionality could be taken to a wider use.
Other use cases for the SQS functionality were also found during the project. In addi- tion to labels, the SQS queues could also carry commands to the printers. These commands could be used to, for example, reboot the device, which would reduce the workload of clinic employees and Provet’s support personnel.
Keywords: SQS, AWS, Provet Cloud, label printing, veterinary medi- cine
Sisällys
Lyhenteet
1 Johdanto 6
1.1 Työn tavoite 6
1.2 Provet Cloud 7
1.3 Tarratulostimet 8
1.4 BlackBoxit 9
1.5 BlackBoxien aiempi toiminta 10
1.6 Amazon Simple Queue Service 11
1.7 SQS:n hallinta Pythonilla 12
1.8 Nordhealth 12
2 Työn kulku 13
3 Kehitystyö 13
3.1 SQS-kirjasto 13
3.2 Provet Cloudin koodin muutokset 17
3.2.1 Tarrojen lähetys SQS:ään 17
3.2.2 Vanhan toiminnallisuuden säilyttäminen 18
3.2.3 Virheiden hallinta ja optimointi 18
3.2.4 Yksikkötestit 20
3.3 BlackBoxin koodiin liittyvät muutokset 21
3.3.1 Pollauksen optimointi 21
3.3.2 Uusi kenttä SOAP-pyyntöön 22
4 Toiminnallisuuden vienti asiakaskäyttöön 22
5 Yhteenveto 23
5.1 Projektin tulokset 23
5.2 Jatkokehitys 23
Lähteet 25
Liitteet
Liite 1: SQS Provet Cloudin tarratulostuksessa Liite 2: Linkit
Lyhenteet ja käsitteet
AWS: Amazon Web Services. Amazonin ylläpitämä pilvipalvelujen koko- elma, johon kuuluu muun muassa tiedon tallennuspalvelu S3, ja tässä projektissa käytetty jonopalvelu SQS.
PyPI: Python Package Index. Pakettivarasto Python-paketeille.
SQS: Simple Queue Service. Amazonin ylläpitämä verkkopalvelu, johon voi luoda jonoja, joita voi käyttää esimerkiksi viestintään kahden oh- jelmiston välillä.
BlackBox: Raspberry Pi -laite, joka on kytketty USB-kaapelilla tarratulostimeen.
Se on yhteydessä Provet Cloudiin internetin välityksellä, ja ottaa siltä vastaan tarroja, jotka se tulostaa kytketyllä tarratulostimella.
Pollaus: Provet Cloudin tarratulostuksessa pollaus tarkoittaa BlackBoxin te- kemää jatkuvaa pyyntöjen lähettämistä, jolla se tarkistaa, onko uusia tarroja saatavilla. Sana tulee englannin sanasta ”polling”.
Provet Cloud:
Selainpohjainen eläinlääkäriklinikan hallintaohjelmisto.
Raspberry Pi:
Pinta-alaltaan noin luottokortin kokoinen yhden piirilevyn tietokone.
1 Johdanto
1.1 Työn tavoiteKuvitellaan ravintola, jossa on työntekijöinä tarjoilija ja mykkä kokki. Kun kokki on saanut aterian valmiiksi, se ei pysty kertomaan siitä tarjoilijalle suoraan, vaan tarjoilijan tulee käydä säännöllisin väliajoin kysymässä kokilta, onko aterioita valmiina tarjoiltavaksi. Tämä on hankalaa kokille, jolla on kiire aterioiden valmis- tuksessa, joten olisi kätevää, jos tarjoilija saisi tietää aterioiden valmistumisesta häiritsemättä kokkia. Tilannetta voisi parantaa lisäämällä ravintolaan ilmoitus- taulun, johon kokki voisi ilmoittaa valmiista aterioista. Tällöin tarjoilija löytäisi uu- det ateriat katsomalla ilmoitustaululta, eikä hänen tarvitsisi häiritä kokin työtä.
Muutetaan tilanne nyt sellaiseksi, että asiakas onkin eläinlääkäri, ja aterian si- jaan hän odottaa tulostettavaa tarraa. Tässä tapauksessa hän on tulostanut tar- ran käyttämällä Provet Cloud -nimistä eläinlääkäriklinikan hallintaohjelmistoa, ja tarra tulostetaan fyysisesti Raspberry Pi -tietokoneeseen kytketyllä tarratulosti- mella. Provet Cloud on siis ravintolamme mykkä kokki, jolle Raspberry Pi tulos- timineen toimii tarjoilijana.
Jotta lääkärin tarra saataisiin tulostettua mahdollisimman nopeasti, täytyy Rasp- berry Pin kysyä Provet Cloudilta useita kertoja minuutissa, onko uutta tarraa tu- lostettavissa. Nämä kyselyt ovat käytännössä SOAP-pyyntöjä, ja tätä säännöl- listä pyyntöjen tekemistä nimitetään myös ”pollaamiseksi” (polling). Näitä Rasp- berry Pi:llä kytkettyjä tulostimia on useita kymmeniä, joten niiden pollauksesta syntyy huomattava kuorma Provet Cloudia ajaville palvelimille.
Tämän työn tavoitteena on vähentää tätä kuormaa noin 15 %:lla hyödyntämällä Amazonin Simple Queue Serviceä (SQS). SQS hoitaisi siis vertauksessa maini- tun ilmoitustaulun virkaa. Pollauksesta syntyvä kuorma ei siis katoaisi, vaan se siirrettäisiin SQS:ään. Ideana olisi, että kun Provet Cloud saisi tarran valmiiksi, se lähettäisi sen SQS:ään, josta BlackBox voisi sen hakea.
Tässä raportin ensimmäisessä luvussa kerrotaan enemmän tarratulostuksen osapuolista, eli Provet Cloudista, tarratulostimista ja BlackBoxeista, ja SQS:stä.
Tämän jälkeen kerrotaan työn varsinaisen toteutuksen vaiheista, ja raportin lo- puksi kerrotaan projektin lopputuloksista sekä mahdollisesta jatkokehityksestä.
1.2 Provet Cloud
Provet Cloud (jatkossa myös pelkästään Provet) on vuonna 2013 alun perin ke- hitetty eläinlääkäriklinikoille sekä sairaaloille suunnattu selainpohjainen hallinta- ohjelmisto. Sen edeltäjiä olivat Windowsille-käyttöjärjestelmille suunnattu Provet Win sekä verkkopohjainen Provet Net. Ohjelmiston tausta on kehitetty pääosin Pythonilla Django-ohjelmistokehystä käyttäen, ja sen edusta on suurimmaksi osaksi HTML:ää, CSS:ää ja JavaScriptiä sekä jQueryä. Se oli alun perin suun- niteltu helppokäyttöiseksi ja melko yksinkertaiseksi, mutta nykyään se pyrkii täyttämään kaikki klinikoiden tarpeet laskutuksesta varastokirjanpitoon ja vakuu- tuskorvauksista diagnostiseen kuvantamiseen.
Kuva 1. Provet Cloudin etusivu
Klinikoilla on käytössään useita laitteita, joita klinikat haluavat käyttää Provet Cloudin kautta, joista yksi esimerkki on tarratulostimet. Klinikat tulostavat näillä esimerkiksi etikettejä muun muassa eläimille ja laboratorionäytteille. Keskityn tässä työssä nimenomaan näihin tarratulostimiin ja siihen, miten ne toimivat
yhteistyössä Provet Cloudin kanssa.
Kuva 2. Tarratulostimien asetukset Provet Cloudissa.
1.3 Tarratulostimet
Tarratulostin muistuttaa hieman tavallista paperitulostinta. Molemmat tulostavat usein valkoiselle materiaalille mustaa tekstiä, ja molemmat voidaan usein kiin- nittää tietokoneeseen USB-kaapelilla. Tämän projektin teossa hyödynnettiin Dymo 450 -tarratulostinta, joka tulostaa tarrat suoraan itsekiinnittyville tarroille lämpötulostusta hyödyntäen. Lämpötulostuksessa käytetään tarroja, jotka on valmistettu lämpöherkästä valkoisesta paperista, jonka pinta muuttuu mustaksi lämmittämällä (1). Tulostusta varten tarvitaan siis oikeanlaisia tarroja, mutta tu- lostus ei vaadi erillisen mustekasetin hankintaa.
Kuva 3. Dymo 450 -tarratulostin (2) 1.4 BlackBoxit
Jotta tarratulostimia voidaan käyttää Provet Cloudin kanssa, tulee niiden olla yhteydessä Provet Cloudiin. Koska Provet Cloud toimii nimensä mukaisesti pil- vipalveluna ja monia tarratulostimia ei voi kytkeä suoraan internetiin, on yhtey- denpitoon käytetty Raspberry Pi -tietokoneita, joihin on asennettu mukautettu Raspbian-käyttöjärjestelmä. Tästä Raspberry Pistä on käytetty nimeä BlackBox (musta laatikko), ja sen tulisi nimensä mukaisesti toimia itsenäisesti ilman, että asiakkaan tarvitsee sitä erikseen asentaa tai muuttaa sen asetuksia. Tarratulos- tin on siis kytketty tietokoneen sijasta BlackBoxiin, joka taas on verkon yli yhtey- dessä Provet Cloudiin.
Käytännössä Provet Cloudista on samaan aikaan käynnissä useita instansseja, joita kutsutaan ympäristöiksi. Esimerkiksi Eurooppalaisia ja Pohjois-Amerikka- laisia käyttäjiä varten on olemassa omat ympäristöt. Lisäksi jokaisella Provet Cloudin asiakkaalla on oma numeerinen tunniste.
Kun BlackBox käynnistyy, sen tulee siis selvittää, mitä koodia sen tulisi suorit- taa, ja mihin Provet Cloudiin sen tulee ottaa yhteys. Se tekee tämän
lähettämällä pyynnön Nordhealthin ylläpitämään hallintasivustoon, joka pitää kirjaa kaikista toiminnassa olevista BlackBoxeista. Sivuston tarkoitus on pohjim- millaan määritellä jokaiselle laitteelle oma rooli. Jokaisella roolilla on nimi, ja roolille luotu Python-tiedosto, jota roolille määrättyjen BlackBoxien on tarkoitus suorittaa.
Sivusto tunnistaa BlackBoxin roolin sen MAC-osoitteen perusteella, ja lähettää vastauksen, joka sisältää rooliin sidotun Python-tiedoston. Tiedosto sisältää oh- jeet siitä, miten ja mihin Provet Cloudiin BlackBoxin tulisi ottaa yhteys. Seuraa- vassa osiossa käydään tarkemmin läpi, mitä kyseinen koodi käytännössä tekee.
1.5 BlackBoxien aiempi toiminta
BlackBoxit sijaitsevat asiakkaiden sisäverkoissa, joten Provetilla ei ole niihin suoraa yhteyttä, eikä se voi lähettää tarroja suoraan BlackBoxeille. Jotta Black- Box tietää mitä sen tulee tulostaa, se lähettää pyyntöjä eli "pollaa" sille määritet- tyä Provetia useamman kerran minuutissa. Edellisessä osiossa mainittu Pyt- hon-tiedosto, jonka BlackBox saa käynnistyessään, sisältää käytännössä pol- lausta tekevän koodin.
Pollauksessa BlackBox ilmoittaa muun muassa minkä tyyppisiä tarroja se voi tulostaa. Provet vastaa pollauksiin palauttamalla sillä hetkellä vanhimman tulos- tamattoman tarran. Mikäli sellaista ei löydy, palauttaa Provet tyhjän vastauksen.
Mikäli vastauksessa oli tarra mukana ja BlackBox tulosti sen onnistuneesti, BlackBox lisää kyseisen tarran tunnisteen mukaan seuraavaan pollaukseen, jol- loin Provet merkitsee pyynnön saatuaan kyseisen tarran tulostetuksi omassa tietokannassaan. Liitteessä 1 on tähän liittyvä sekvenssikaavio, jossa esitetään yhden tarran matka käyttäjän klikkauksesta fyysiseksi tarraksi.
Kun Provet saa BlackBoxilta pyynnön, se myös päivittää laitteen viimeisimmän yhteysajan, josta Provet päättelee, onko laite online-tilassa. Provetissa olevalla päätepisteellä (endpoint), johon tarrapyyntö lähetetään, on siis kolme tehtävää:
palauttaa uusin tarra kuvana, merkitä pyynnössä määritelty tarra tulostetuksi, ja päivittää laitteen viimeisin yhteysaika.
1.6 Amazon Simple Queue Service
Simple Queue Service (SQS) on Amazonin tarjoama pilvipalvelu, johon voi luoda omia jonoja, joihin voi lähettää viestejä. Viestit voivat sisältää vapaamuo- toista tai rakenteellista tekstiä esimerkiksi JSON-muodossa, ja ne voivat olla 256 kilotavun kokoisia (3). SQS-jonoa voidaan käyttää esimerkiksi viestintään kahden erillisen ohjelmiston välillä, jotka eivät voi suoraan viestiä keskenään.
SQS:ssä voi luoda kahdenlaisia jonoja: standardijonoja sekä FIFO-jonoja (first in, first out; ensimmäisenä sisään, ensimmäisenä ulos). FIFO-jonossa olevat viestit lähetetään vastaanottajalle vain kerran, ja ne lähetetään aina saapumis- järjestyksessä. Standardijonossa yksi viesti saatetaan joskus lähettää vastaan- ottajille useammin kuin kerran, ja viestit eivät välttämättä saavu vastaanottajille saapumisjärjestyksessä. (4.) Tässä projektissa viestien tarkalla järjestyksellä ei ollut väliä, joten päädyin käyttämään standardijonoja. Mikäli tarran sisältävä viesti vastaanotettaisiin useamman kerran, voitaisiin se vain ohittaa, mikäli ky- seinen tarra on jo ehditty tulostaa.
Kun viesti lähetetään SQS-jonoon, se pysyy siellä oletuksena 4 päivää, jonka jälkeen se poistetaan automaattisesti (5). Kun vastaanottaja hakee viestin jo- nosta, sitä ei silloin vielä poisteta jonosta, koska ei voida ennalta tietää, onnis- tuiko vastaanottaja käsittelemään viestin. Kun vastaanottaja on käsitellyt viestin, sen pitää tällöin poistaa viesti jonosta, jotta sitä ei käsiteltäisi uudestaan. (6.) Lisäksi kun viesti vastaanotetaan, se piilotetaan jonosta oletuksena 30 sekunnin ajaksi (6). Tällä varmistetaan, että viestillä on vain yksi käsittelijä kerrallaan.
Tällä ominaisuudella ei ollut merkitystä tässä projektissa, sillä jokaisella jonolla oli vain yksi käsittelijä, eli jonon luonut BlackBox.
Tässä projektissa viestin käsittely tarkoittaa käytännössä tarran tulostamista, eli mikäli tulostaminen ei onnistu esimerkiksi tarrojen puutteen takia, ei tarran sisäl- tävää viestiä voida vielä poistaa jonosta. Viesti siis jää jonoon niin pitkäksi ai- kaa, kunnes se saadaan tulostettua, tai kunnes viestin voimassaoloaika päättyy.
1.7 SQS:n hallinta Pythonilla
Jotta SQS:ää ja muita AWS:n palveluja pystyy hallitsemaan Pythonilla, nykyisin Amazonilla työskentelevä Mitch Garnaat kehitti Python-paketin nimeltä boto (7).
Pakettia on vuosien mittaan päivitelty, ja uusin versio on nimeltä boto3. Sen avulla pystyy hallitsemaan suurinta osaa AWS:n palveluista suoraan Python- koodia käyttäen. Nimi boto tulee Amazonissa elävästä delfiinistä, jota portugalin kielessä kutsutaan botoksi (8).
1.8 Nordhealth
Toimin ohjelmistokehittäjänä Nordhealth-nimisessä yrityksessä, joka toimi tä- män projektin tilaajana.
Nordhealth on lääketieteen ja terapia-alan ohjelmistoihin keskittynyt ohjelmisto- yritys. Yritys aloitti toimintansa vuonna 2001 nimellä Finnish Net Solutions (FNS), jolloin sen toimialaa oli nettisivujen teko. Tämän lisäksi yritys kokeili al- kuvuosinaan myös muita toimintatapoja, muun muassa tarjoten Wi-Fi-pohjaisia internet-yhteyksiä. Lopulta yritys päätti keskittyä terveydenhoitoalan praktiikka- ohjelmistoihin, ja vuonna 2005 se osti Provet-nimisen yrityksen, joka toimi Provet-nimisen eläinlääkäriklinikan hallintaohjelmiston kehittäjänä. Yritys osti vuonna 2009 Praktiikka-nimisen terapiaohjelmiston kehittäjän, jonka pohjalta se alkoi kehittämään terapiaohjelmisto Diariumia.
Vuonna 2007 perustettiin Three Plus Group (TPG) toimimaan FNS:n emoyh- tiönä, ja vuonna 2021 selkeyttääkseen brändiään TPG muutti nimensä Nordhealthiksi. Tällöin maakohtaiset tytäryhtiöt nimettiin kyseisen maan mu- kaan, ja esimerkiksi FNS:n nimi vaihtui Nordhealth Finlandiksi.
Nordhealth on kasvanut viime vuosina nopeasti; kun vuonna 2010 yhtiössä työskenteli noin 10 henkilöä, on työntekijöiden määrä noussut vuonna 2021 jo yli 200:n.
2 Työn kulku
Projektin alussa pidettiin melko säännöllisesti palavereja, joissa seurattiin työn edistymistä, ja ratkottiin työn aikana havaittuja ongelmia. Palaverit pidettiin pää- osin minun, esimieheni Jaro Kosken, sekä pääkehittäjä Julius Leppälän kanssa, jonka idea projekti alun perin oli. Tein työtä pääosin itsenäisesti, ja sain tarpeen tullen heiltä neuvoja projektin edetessä muun muassa AWS:ään liittyvissä kysy- myksissä.
Sain projektia varten kotiini Dymo 450 -tarratulostimen, jota pystyin käyttämään tarratulostuksen testauksessa. Valitettavasti en pystynyt projektin alkuvai- heessa hyödyntämään tulostinta kovinkaan paljon, sillä en saanut tulostinta toi- mimaan paikallisessa kehitysympäristössäni. Käytin sen sijaan SoapUI-nimistä ohjelmaa simuloimaan tarratulostinta lähettämällä ohjelmalla pollausta vastaa- via SOAP-pyyntöjä.
Kun tuli aika tehdä muutokset BlackBoxin koodiin, otin yhteyttä Christian Grön- holmiin, jolla oli BlackBoxin koodista aiempaa kokemusta. Projektin loppuvai- heessa projekti etenikin hänen kanssaan hyvässä yhteishengessä pääosin Slack-viestejä käyttämällä.
3 Kehitystyö
3.1 SQS-kirjastoProjektin ensimmäisenä vaiheena oli luoda Python-kirjasto SQS:n kanssa toimi- miseen, sekä muokata Provetin koodi siten, että Provet lähettäisi tarrat auto- maattisesti SQS:ään tätä kirjastoa hyödyntäen. Kirjaston tuli olla sellainen, että sitä voisi käyttää myös BlackBoxin kanssa ja mahdollisesti myös tulevissa
projekteissa, joissa hyödynnetään SQS:ää. Ajatuksena oli, että kirjasto toimisi niin sanottuna "wrapperinä" boto3:lle, mutta toteutustapaa ei sen tarkemmin määritelty.
Koska en ollut aiemmin käyttänyt SQS:ää tai kirjoittanut omaa kirjastoa, minulla ei ollut aluksi selvää kuvaa kirjaston rakenteesta. Aluksi loin kirjaston suoraan Provetin koodiin, ja kirjoitin yksinkertaisia funktioita SQS-jonojen käsittelyyn yh- teen tiedostoon Provetin koodirakenteeseen. Nämä funktiot ottivat aluksi boto3- session parametriksi, mutta myöhemmin muutin funktioita niin, että niille tarvitsi vain antaa jono-objekti. Tällöin loin myös tiedoston alkuun globaalin muuttujan boto3-istunnolle, jota kaikki funktiot voisivat käyttää.
Seuraavassa iteraatiossa muutin funktiot sellaisiksi, että niille tarvitsi antaa pa- rametriksi käsiteltävän jonon nimi, jolloin kutsujan ei tarvitsisi enää huolehtia is- tunnon tai jono-objektien käsittelystä. Lopulta päädyin luomaan funktioita varten oman luokan, jonka myötä funktiot muuttuivat kyseisen luokan metodeiksi. Täl- löin pystyin myös siirtämään istunnolle määritetyn globaalin muuttujan luokan sisälle, jolloin jokaiselle luokan instanssille luotaisiin oma istunto.
Kirjaston nimeksi tuli lopulta ”sqs-poller”. Alla on näyte kirjaston koodista, josta on tilan säästämisen vuoksi poistettu kommentit. Linkki kirjaston koodiin löytyy Liite 2:sta.
class SQSPoller:
def __init__(self, **session_kwargs):
session_kwargs.setdefault(
'aws_access_key_id',
os.environ.get('SQS_POLLER_AWS_ACCESS_KEY_ID'), )
session_kwargs.setdefault(
'aws_secret_access_key',
os.environ.get('SQS_POLLER_AWS_SECRET_ACCESS_KEY'), )
session_kwargs.setdefault(
'region_name',
os.environ.get('SQS_POLLER_REGION_NAME'), )
self.session = boto3.Session(**session_kwargs) self.sqs = self.session.resource('sqs')
self.queue_cache = {}
def get_queue_by_name(self, queue_name, skip_cache=False):
if skip_cache:
queue = self.sqs.get_queue_by_name(QueueName=queue_name) self.queue_cache[queue_name] = queue
return queue
return self.queue_cache.setdefault(
queue_name,
self.sqs.get_queue_by_name(QueueName=queue_name), )
def send_message_to_queue(self, queue_name, message_body, **send_kwargs):
queue = self.get_queue_by_name(queue_name) send_kwargs['MessageBody'] = message_body return queue.send_message(**send_kwargs)
Esimerkkikoodi 1. Näyte kirjaston lopullisesta koodista. Koodissa olevalla send_message_to_queue-metodilla voidaan lähettää viesti haluttuun SQS-jo- noon. Metodia kutsutaan antamalla jonon nimi ja viestin sisältö string-muo- dossa. Esimerkkikoodissa 3 on esimerkki metodin kutsumisesta.
Kun kirjaston koodiin oli luotu tärkeimmät metodit esimerkiksi jonojen luomiseen ja viestien lähetykseen ja poistoon, tuli koodista julkaista myös Python-paketti, jota Provet Cloud ja BlackBox voisivat hyödyntää. Tässä kohtaa koodi oli julki- sessa GitHub-tietovarastossa (repository), ja GitHubissa on GitHub Actions -ni- minen toiminnallisuus, joka mahdollistaa komentojen suorittamisen haluttujen tapahtumien yhteydessä, esimerkiksi jokaisen commitin jälkeen. Pystyin hyö- dyntämään Actions-toiminnallisuutta testien ajamiseen ja PyPIin julkaisuun, jol- loin molemmat tapahtuvat automaattisesti committeja tehtäessä.
Jotta tulevat muutokset eivät rikkoisi koodia, lisäsin pytest-kirjastoon pohjautu- vat yksikkötestit kirjaston koodille. Lisäsin näiden testien ajamista varten uuden GitHub Actions workflow:n GitHub-tietovarastoon, joka ajetaan jokaisen commi- tin yhteydessä. Testien automaattisella ajamisella lisätään luottamusta siihen, ettei julkaistavassa koodissa ole bugeja.
# conftest.py
@pytest.fixture
def aws_credentials():
return {
'aws_access_key_id': 'testing', 'aws_secret_access_key': 'testing', 'region_name': 'eu-west-1',
}
@pytest.fixture
def sqs(aws_credentials):
with mock_sqs():
yield boto3.Session(**aws_credentials).resource('sqs')
@pytest.fixture
def poller(aws_credentials):
with mock_sqs():
yield SQSPoller(**aws_credentials)
# test_sqs_poller.py
class TestCreateQueue:
def test_new_queue(self, sqs, poller):
queue_name = 'test-queue'
created_queue = poller.create_queue(queue_name)
retrieved_queue = sqs.get_queue_by_name(QueueName=queue_name) assert created_queue.url == retrieved_queue.url
def test_existing_queue(self, sqs, poller):
queue_name = 'test-queue'
created_queue = sqs.create_queue(QueueName=queue_name) recreated_queue = poller.create_queue(queue_name) assert created_queue.url == recreated_queue.url
Esimerkkikoodi 2. Yllä conftest.py-tiedoston sisältö, jossa määritellään testeissä käytettävät fikstuurit. Alla test_sqs_poller.py-tiedoston sisältö, jossa määritel- lään varsinaiset testit. Testit voivat käyttää fikstuureja antamalla fikstuurin nimi- sen parametrin, jolloin parametrin arvoksi tulee fikstuurin paluuarvo. Esimerkiksi test_new_queue-metodissa on käytetty sqs- ja poller-fikstuureja.
Kirjaston koodista tuli lopuksi luoda Python-paketti, joka tuli julkaista julkiseen PyPI-pakettivarastoon, josta paketin voisi asentaa kuka tahansa. Tämä oli
lopulta melko yksinkertaista, sillä GitHubin dokumentaatiosta löytyi lähes valmis esimerkki tähän soveltuvasta workflowista. Kopioin workflowin kirjaston koodiin, ja määrittelin siihen erikseen, että se tulisi ajaa vain commiteille, jotka on mer- kitty tunnisteella (tag). Tällöin tunnisteita voidaan käyttää versionumeroina. Jos esimerkiksi haluttaisiin julkaista versio 1.0, tarvitsisi vain merkitä uusin commit tunnisteella ”1.0”, jolloin PyPI-julkaisun tekevä workflow tekisi julkaisun auto- maattisesti.
3.2 Provet Cloudin koodin muutokset
Samaan aikaan olin alkanut sovittamaan kirjaston metodeja Provetin koodiin.
Alun perin suunnitelmana oli lähettää tarrat kuvina Provetista SQS-jonoon, jol- loin BlackBox voisi tulostaa tarran heti saatuaan sen jonosta. Ongelmaksi muo- dostui tarrojen koko, joka saattoi olla yli SQS-viestissä sallitun 256 kilotavun.
Tämän takia toteutusta muutetiin siten, että SQS-jonoon lähetettäisiin vain tar- rojen tunnisteet, jotka ovat käytännössä tarrojen primääriavaimia Provetin tieto- kannassa. Tällöin BlackBoxin tulee vielä hakea tarran kuva Provetista tätä tun- nistetta käyttämällä.
3.2.1 Tarrojen lähetys SQS:ään
Provetissa on tarroja ja tulostimia varten omat mallinsa, Label, ja LabelDevice.
Kun tarratulostin ottaa Provetiin ensimmäisen kerran yhteyden, tulostimelle luo- daan LabelDevice-olio, joka tallennetaan Provetin tietokantaan. Vastaavasti kun käyttäjä tulostaa tarran, tarrasta luodaan Label-olio, joka tallennetaan Provetin tietokantaan.
Yksi ensimmäisistä muutoksista oli varmistaa, että uusien Label-olioiden tunnis- teet lähetettäisiin oikeaan SQS-jonoon. Toteutin tämän lisäämällä signaalikuun- telijan Label-mallin post_save-signaalille. Tätä kuuntelijaa kutsutaan joka kerta, kun uusi Label-olio tallennetaan tietokantaan. Tarroja voi Provetissa tulostaa useista eri paikoista, joten tämä signaalikuuntelija oli oiva tapa varmistaa, että kaikki tarrat lähetetään SQS:ään.
@receiver(signals.post_save, sender=Label)
def send_label_to_sqs(sender, instance, created=False, **kwargs):
if settings.LABEL_SQS_SENDING_DISABLED or not created or \ not instance.device.is_sqs_capable:
return
queue_name = instance.device.sqs_queue_name poller = SQSPoller(**SQS_POLLER_AWS_CREDENTIALS)
return poller.send_message_to_queue(queue_name, str(instance.id))
Esimerkkikoodi 3. Ensimmäinen versio post_save-signaalin kuuntelijasta, joka lähettää tarran SQS-jonoon. is_sqs_capable-metodi käytännössä tarkistaa, onko kyseisen laitteen SQS-jono olemassa lähettämällä pyynnön SQS:ään.
Tämä metodi poistettiin myöhemmin, ja tästä kerrotaan tarkemmin kappaleessa 3.2.3.
3.2.2 Vanhan toiminnallisuuden säilyttäminen
Tässä kohtaa projektia aloin pohtia tarkemmin, miten projektiin liittyvät muutok- set käytännössä vietäisiin tuotantoon. Olin aluksi naiivisti ajatellut, että kaikki BlackBoxit päivitettäisiin kerralla, jolloin jäljelle ei jäisi yhtäkään vanhalla koo- dilla toimivaa BlackBoxia. Olin tämän takia poistanut sen osan koodista, jota ei enää SQS-jonoja käytettäessä tarvittaisi.
Asiaa hieman selvitettyäni tajusin, että muutokset tulevat menemään tuotantoon vaiheittain, eli tulee olemaan sellainen tilanne, jolloin vain osa laitteista tukee SQS:ää. Projektin aikana selvisi myös, ettei esimerkiksi vanhoja BlackBoxeja tai mitään Windows-laitteita voi muuttaa SQS-yhteensopiviksi. Tästä viisastuttuani palautin poistamani vanhan koodin ja varmistin, että koodi toimii sekä SQS:ää tukevilla että tukemattomilla laitteilla.
3.2.3 Virheiden hallinta ja optimointi
Tässä kohtaa aloin miettimään sitä, mitä Provetin ja BlackBoxin tulisi tehdä, kun SQS:ään ei saada yhteyttä esimerkiksi sen ollessa alhaalla. Tähän mennessä Provetin yhteydenotot SQS:ään tapahtuivat samassa säikeessä pääohjelman kanssa. Mikäli tarran lähetyksessä SQS:ään kestäisi aikaa, olisi Provetin käyttö- liittymä jumissa siihen asti, kunnes tarra saataisiin lähetettyä. Toisaalta
koodissa ei olut myöskään virheentarkistusta, joten virheen sattuessa tuotan- nossa Provetin kehittäjien olisi vaikea saada tästä tietoa.
Muutin koodia ensin siten, että yhteydenotot SQS:ään tehdään celery-tehtävillä (task). Tehtävät suoritetaan taustalla omassa säikeessään, jolloin viiveet SQS- yhteydenotoissa eivät aiheuttaisi viivettä käyttöliittymän puolella. Tämän lisäksi lisäsin SQS-yhteydenottoihin virheenkaappauksen, jossa virheet lähetetään Sentry-palveluun, josta Provetin kehittäjät voivat niitä tarkastella.
Tässä kohtaa koodi myös käytti laitteen SQS-jonon olemassaoloa päätelläk- seen, onko kyseinen laite SQS-yhteensopiva. Kun tarra piti lähettää SQS:ään, Provet teki käytännössä kaksi pyyntöä: ensimmäisen, jossa se varmisti SQS- jonon olemassaolon, ja toisen, jossa itse lähetys tapahtui. Mikäli SQS olisi al- haalla, ensimmäinen pyyntö jumittaisi käyttöliittymän, sillä se suoritettiin pää- säikeessä. Toisaalta myöskään kahden pyynnön tekeminen jokaiselle lähetyk- selle ei ollut tehokkain mahdollinen ratkaisu.
Päädyin muuttamaan koodia siten, että Provet yrittää lähettää tarran aina, kun tarran laite on BlackBox-tyyppinen. Mikäli tarran lähetyksessä tulee poikkeus siitä, ettei jonoa löydy, Provet olettaa, ettei kyseistä laitetta ole päivitetty SQS- yhteensopivaksi ja ohittaa kyseisen poikkeuksen.
@shared_task
def send_label_to_sqs_queue(label_id):
label = Label.objects.get(id=label_id) queue_name = label.device.sqs_queue_name try:
poller = SQSPoller(**SQS_POLLER_AWS_CREDENTIALS) except Exception:
sentry_client.captureException() return
try:
poller.send_message_to_queue(queue_name, str(label.id)) except poller.sqs.meta.client.exceptions.QueueDoesNotExist:
pass
except Exception:
sentry_client.captureException()
Esimerkkikoodi 4. celery-tehtävä (task), joka lähettää tarran SQS-jonoon. Mikäli jonoa ei ole olemassa, koodi olettaa, että kyseistä laitetta ei ole vielä päivitetty SQS-yhteensopivaksi ja ohittaa kyseisen poikkeuksen. Mikäli tehtävässä
tapahtuu odottamattomia poikkeuksia, ne lähetetään Sentry-palveluun, josta ke- hittäjät voivat tarkastella niitä.
@receiver(signals.post_save, sender=Label)
def send_label_to_sqs(instance, created, **kwargs):
if created and not settings.LABEL_SQS_SENDING_DISABLED \ and instance.can_be_sqs_capable:
send_label_to_sqs_queue.delay(
label_id=instance.id, )
Esimerkkikoodi 5. Päivitetty versio signaalikuuntelijasta, jossa hyödynnetään yllä olevaa celery-tehtävää. Attribuutti can_be_sqs_capable käytännössä var- mistaa, onko tarran laite BlackBox-tyyppinen. Näin esimerkiksi Windows-tulos- tinten tarroja ei yritetä turhaan lähettää SQS:ään.
Ongelmia tuli myös siitä, etten ollut huomannut, että BlackBoxien pollaus piti niitä käytännössä online-tilassa Provetissa. Mikäli BlackBoxit eivät siis enää te- kisi pyyntöjä säännöllisesti, ne olisivat suurimman osana ajasta offline-tilassa.
Tämän takia BlackBoxien toimintaa muutettiin siten, että ne pollaavat Provetia edelleen, tosin vain 5 minuutin välein. Aiemmin Provet oletti BlackBoxin olevan offline-tilassa, mikäli sen viimeisimmästä pyynnöstä oli kulunut yli 60 sekuntia.
Myös tätä aikaa nostettiin 10 minuuttiin, jotta BlackBoxit pysyisivät varmasti on- line-tilassa.
3.2.4 Yksikkötestit
Provetin koodissa on tapana kirjoittaa yksikkötestit lähes kaikelle Python-koo- dille, joten kirjoitin lopuksi yksikkötestit SQS-toiminnallisuudelle. Testeissä tuli esimerkiksi varmistaa, että tarran luomisen jälkeen sen tunniste todella lähetet- täisiin SQS-jonoon. Näitä testejä ajetaan jatkuvasti eri kehittäjien koneilla ja CI- ympäristössä (constant integration), joten testeissä ei voi käyttää oikeita SQS- jonoja.
Löysin tähän tarkoitukseen kirjaston nimeltä moto, jolla pystyy ”mockaamaan”, eli luomaan tilapäisiä jäljitelmiä, AWS:n palveluista (9). Testeissä voisi luoda siis huoletta SQS-jonoja ilman pelkoa siitä, että testit lähettäisivät pyyntöjä
AWS:ään. moton ansiosta Provetin koodia ei myöskään tarvinnut muuttaa tes- tejä varten, vaan testeissä suoritettaisiin samaa koodia kuin mitä tuotannossa.
@override_settings(LABEL_SQS_SENDING_DISABLED=False) class SQSLabelQueueTestCase(ProvetTestCase):
mock_sqs = mock_sqs() def setUp(self):
self.mock_sqs.start() self.poller = SQSPoller(
aws_access_key_id='testing', aws_secret_access_key='testing', )
self.device = LabelDeviceFactory()
self.sqs_queue = self.poller.create_queue(
queue_name=self.device.sqs_queue_name, )
def tearDown(self):
self.mock_sqs.stop()
def test_label_creation_with_sqs_device(self):
label = LabelFactory(device=self.device) self.assertEqual(self.get_count_labels(), 1)
sqs_messages = self.poller.receive_messages_from_queue(
self.device.sqs_queue_name, )
self.assertEqual(len(sqs_messages), 1)
self.assertEqual(sqs_messages[0].body, str(label.id))
Esimerkkikoodi 6. Näyte SQS:ää varten kirjoitetuista testiluokasta, ja yhdestä testimetodista. Koodia on hieman muokattu selkeyden vuoksi.
3.3 BlackBoxin koodiin liittyvät muutokset
Myös BlackBoxin koodi tuli muuttaa sellaiseksi, että BlackBoxit voivat ottaa yh- teyden SQS:ään. BlackBoxin koodi on täysin erillään Provetin koodista, eikä mi- nulla ollut siitä aiempaa kokemusta. Tästä syystä pyysin koodista vastaavaa ke- hittäjää tekemään tarvittavat muutokset BlackBoxin koodiin. Kuten mainitsin ra- portin edellisessä osiossa, en itse tehnyt näitä muutoksia, joten en käy näitä muutoksia laajasti läpi.
3.3.1 Pollauksen optimointi
SQS:n avulla BlackBoxien pollaamisesta pystyttiin hieman optimoimaan. Nor- maalissa pollauksessa BlackBox tekee pyynnön, johon Provet vastaa heti, jonka jälkeen BlackBox odottaa hetken ennen seuraavan pyynnön lähetystä.
Tämä voi johtaa toisinaan johtaa viiveisiin tulostuksessa, mikäli käyttäjä tulosti tarran juuri Provetin vastauksen jälkeen.
SQS-jonoa voi myös pollata niin kutsutulla pitkällä pollauksella (long polling), jossa BlackBox odottaa jonolta vastausta jopa 20 sekuntia. Mikäli BlackBox ei saa pollauksessa heti jonolta uutta viestiä, se odottaa sitä vielä 20 sekuntia, jonka jälkeen se luovuttaa, ja pitää hetken tauon ennen seuraavan pollauksen tekemistä. Mikäli jonoon tulee siis uusi viesti pollauksen aikana, saa BlackBox sen käytännössä heti käsittelyynsä. (10.)
3.3.2 Uusi kenttä SOAP-pyyntöön
Kuten raportin johdannossa mainittiin, yksi BlackBoxin pollaus on käytännössä SOAP-pyyntö. Pyyntö muistuttaa rakenteeltaan lomaketta, jossa BlackBox il- moittaa, minkälaisia tarroja se haluaisi Provetin palauttavan pyynnön vastauk- sessa. Aiemmin, kun BlackBox teki jatkuvasti pyyntöjä Provetille, oli Provetin tehtävä löytää BlackBoxille tarroja tulostettavaksi. Nyt kun BlackBox saa tulos- tettavien tarrojen tunnisteet SQS-jonosta, sen tulisi voida pyytää tiettyä tarraa Provetilta.
Lisäsin tätä varten Provetin puolelle SOAP-pyyntöön uuden kentän, johon BlackBox voi merkitä haluamansa tarran tunnisteen. Kun Provet saa BlackBo- xilta pyynnön, jossa kyseinen kenttä on täytetty, se palauttaa vastauksessaan BlackBoxille kyseisellä tunnisteella varustetun tarran. Tämä muutos tehtiin myös BlackBoxin koodiin, eli kun BlackBox on saanut SQS-jonosta tarran tun- nisteen, se laittaa sen mukaan seuraavaan pyyntöön.
4 Toiminnallisuuden vienti asiakaskäyttöön
Ennen kuin SQS-toiminnallisuus otettaisiin laajasti asiakaskäyttöön, päätettiin toiminnallisuutta testata ensin pienessä mittakaavassa. Provetilla on yksi norja- lainen asiakas, jolla on käytössä 3 BlackBox-tulostinta, jotka pystyttiin päivittä- mään SQS-yhteensopiviksi. Tarkoituksena on seuraavaksi ottaa heihin yhteyttä, ja pyytää heitä SQS-toiminnallisuuden koekäyttäjiksi. Kun mahdolliset ongelmat on löydetty ja korjattu, voidaan SQS-toiminnallisuus ottaa asteittain käyttöön myös muilla asiakkailla.
Koska SQS-toiminnallisuutta ei ole vielä otettu asiakaskäyttöön, ei projektin ta- voitetta voida vielä tässä kohtaa vahvistaa täytetyksi. Kun toiminnallisuus on otettu laajasti käyttöön, voidaan todeta, kuinka paljon SQS-jonojen hyödyntämi- nen todellisuudessa vähensi Provetin palvelimien kuormaa.
5 Yhteenveto
5.1 Projektin tuloksetVaikka projekti saatiin päätökseen, ei sitä ole vielä siis ole ehditty ottamaan asiakaskäyttöön, joten sen tuloksia ei voida tässä vaiheessa vielä arvioida. Pro- jektissa itsessään tuli muutamia ongelmia vastaan, kuten kappaleessa 3.2.3 to- dettiin. Nämä olisi voitu mahdollisesti välttää omalta osaltani tarkemmalla taus- tatyöllä, ja tarkemmalla testauksella, oikeaa BlackBoxia käyttäen.
Varsinkin online-tila-ongelma huomattiin vasta varsin myöhään kehityksessä, ja se oli melko kriittinen projektin kannalta. Projektin ajatuksena oli vähentää BlackBoxien pyyntöjä Provetille, ja ideaalitilanteessa BlackBox lähettäisi pyyn- nön vain, kun sillä on tarra, jonka se haluaa tulostaa, tai kun se haluaa merkitä tarran tulostetuksi Provetissa. Mikäli BlackBox tekisi näin, se näkyisi Provetissa offline-tilassa lähes jatkuvasti, joten tästä ratkaisusta jouduttiin luopumaan, ja BlackBoxien pyyntöjen väliä Provetille vain harvennettiin.
5.2 Jatkokehitys
Alun perin SQS-jonoon oli tarkoitus lähettää koko tarra pelkän tunnisteen sijaan, mutta SQS-viestin kokorajoitteesta johtuen tästä luovuttiin. Yksi vaihtoehto olisi ollut lähettää tarran kuva Provetista Amazonin S3-palveluun ja lähettää SQS- jonoon vain linkki S3:een, mutta ajan säästämiseksi tämä jätettiin toteuttamatta.
Tällä tavalla voisi mahdollisesti vähentää Provetiin kohdistuvaa kuormaa enti- sestään, joten tämä voisi olla yksi kehitysidea tulevaisuuden varalle.
SQS-toiminnallisuudelle on jo ehditty suunnittelemaan muutakin käyttöä. Nyt kun Provet voi lähettää viestejä BlackBoxille SQS-jonon kautta, voi se teoriassa lähettää muutakin kuin tarrojen tunnisteita. Suunnitelmana on tulevaisuudessa lisätä Provetille mahdollisuus lähettää komentoja SQS-jonoon, joka mahdollis- taisi esimerkiksi BlackBoxin uudelleenkäynnistämisen suoraan Provetista.
Tämä helpottaisi klinikoiden ja Provetin tuen työtä, kun BlackBoxeja ei tarvitsisi käynnistää uudelleen ottamalla niitä hetkeksi irti sähköverkosta, vaan sen voisi tehdä Provetista hiiren klikkauksella.
Lähteet
1 What is Direct Thermal Printing? 2016. Verkkoaineisto. LabelValue.com.
<https://www.labelvalue.com/blog/what-is-direct-thermal-printing>. Päivi- tetty 7.9.2016. Luettu 30.11.2021.
2 DYMO LabelWriter 450 Direct Thermal Label Printer. Verkkoaineisto.
Dymo Corporation. <https://www.dymo.com/label-makers-printers/la- belwriter-label-printers/dymo-labelwriter-450-direct-thermal-label- printer/SAP_1752264.html>. Luettu 30.11.2021.
3 SendMessage. Verkkoaineisto. Amazon Web Services, Inc.
<https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIRefer- ence/API_SendMessage.html >. Luettu 30.11.2021.
4 Queue types. Verkkoaineisto. Amazon Web Services, Inc.
<https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDe- veloperGuide/welcome.html#sqs-queue-types>. Luettu 30.11.2021.
5 CreateQueue. Verkkoaineisto. Amazon Web Services, Inc.
<https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIRefer- ence/API_CreateQueue.html>. Luettu 30.11.2021.
6 Amazon SQS visibility timeout. Verkkoaineisto. Amazon Web Services, Inc. <https://docs.aws.amazon.com/AWSSimpleQueueService/lat-
est/SQSDeveloperGuide/sqs-visibility-timeout.html>. Luettu 30.11.2021.
7 boto. Verkkoaineisto. Python Software Foundation. <https://pypi.org/pro- ject/boto/>. Luettu 30.11.2021.
8 Why is the project named boto? 2017. Verkkoaineisto. GitHub, Inc.
<https://github.com/boto/boto3/issues/1023#issuecomment-287127647>.
Päivitetty 16.3.2017. Luettu 30.11.2021.
9 moto. Verkkoaineisto. Python Software Foundation. <https://pypi.org/pro- ject/moto/>. Luettu 30.11.2021.
10 Amazon SQS short and long polling. Verkkoaineisto. Amazon Web Ser- vices, Inc. <https://docs.aws.amazon.com/AWSSimpleQueueService/lat- est/SQSDeveloperGuide/sqs-short-and-long-polling.html>. Luettu
30.11.2021.
SQS Provet Cloudin tarratulostuksessa
Kuva 1. Kaavio SQS:n toiminnasta tarratulostuksen apuna Provet Cloudissa.
Tummennetut kohdat suoritetaan vain, jos BlackBox tukee SQS:ää. Jokainen SQS:ää tukeva BlackBox luo käynnistyessään oman SQS-jononsa. Jos BlackBoxin SQS-jono on olemassa, Provet Cloud olettaa, että kyseinen BlackBox tukee SQS:ää.
Linkit
sqs-poller: https://pypi.org/project/sqs-poller/
