MARE NOSTRUM Del 4
Forord Denne delen av rapporten er ment å forklare alle som bruker systemet, det mest nødvendige de trenger for å bruke systemet. Det bør også merkes at som nevnt i kapittel 11 i produktrapporten, oppsto det en del problemer med systemet etter at vi var ferdig med implementasjonsfasen på grunn av endringer på kjernefunksjonalitet på systemet deres som de ikke hadde varslet. Denne manualen er imidlertid utformet med tanke på at systemet fungerer slik det gjorde da vi var ferdig med det. 2
Innholdsfortegnelse 1 Notasjoner... 4 2 Innledning... 4 3 Hoveddel... 5 3.1 For administrator... 5 3.1.1 Oppstart av AIS-parseren... 5 3.1.2 Oppstart av schedule-parseren... 6 3.1.3 Oppstart av rederistatistikkoppdatereren... 7 3.1.4 Oppstart av web-applikasjonen... 7 3.1.5 Feil og rettingsmuligheter... 8 3.2 For brukere... 10 3
1 Notasjoner For bruk av alle notasjoner i denne delen av rapporten, se ordlisten i vedlegg 1. 2 Innledning Programmet er laget og bygd for at det skal kunne vise statistikk over hvilke rederier som er mest punktlige. Mesteparten av programmet er kun ment å kjøre i bakgrunnen, derfor vil ikke programmet skrive ut noe særlig meldinger annet enn feilmeldinger når det kjører. Dette er selvfølgelig med unntak av web-siden som skal vise statistikken som programmet skal beregne. De fleste av feilmeldingene i programmet kommer i form av exeptions, men skal ikke kunne oppstå i normale brukstilfeller for sluttbruker. Disse er ofte ganske selvforklarende, men skal kun kunne oppstå ved eventuelle bugs eller feil ved programmet. 4
3 Hoveddel 3.1 For administrator Systemet er designet til å fungere på Linux, men skal virke på alle plattformer med forandringer i filbaner som benyttes av programmet. Dette er fordi vi har valgt å ikke innføre begrensninger på plasseringer av filene av hensyn til oppdragsgiver. Websiden er selvsagt fullstendig plattformuavhengig. Framgangsmåten under for oppstart av programmet er derfor skrevet for Linux. 3.1.1 Oppstart av AIS-parseren Det er viktig at komponentene i AIS-parseren startes i riktig rekkefølge. Dette er for at nettverkstilkoblingen er nødt til å gjøres i riktig rekkefølge for at programmet skal virke som det skal. Legg også merke til at kun en versjon/instans av programmet kan kjøre samtidig på et system. Figur 3.1 - Denne illustrasjonen viser en helt standard framgangsmåte for å starte opp aisparseren i linux. 1.a Dersom man ønsker å legge aisreceiver.py og mappen dk (som inneholder aisparseren) på forskjellige maskiner, bør man endre linjen clientsocket = new Socket("localhost", 2876); Slik at den kobler til den IP-adressen som aisreceiver.py kjører på. 1.b start aisreceiver.py med kommandoen python aisreceiver.py& i den samme mappen som aisreceiver.py ligger i slik som er gjort i figuren over. 5
2. Gå til det stedet der du har lagt mappen dk, som inneholder java-delen av programmet. Pass på å ikke gå inn i selve mappen dk før man går til neste trinn, men blir værende i mappen under. 3.a Skriv så inn sudo java -cp. dk.tbsalling.aismessages.aisparser& som i illustrasjonen over. 3.b Dersom man isteden ønsker å kjøre aisparseren med innlagt støtte for multithreading, skriv sudo java -cp. dk.tbsalling.aismessages.threadedaisparser& istedenfor kommandoen i punkt 3.a. 4. For at aisparseren skal fungere må det mottas data gjennom udpserveren som ligger implementert i aisparseren. Ais-rådata må derfor sendes fra en distibutør av aisdata til port 2044 på denne serveren. Dersom dette er i orden, fortsett videre til oppstart av schedule-parseren. 3.1.1.2 Tilleggsfunksjon 5. Dersom man ikke har noen avtale med noen ekstern leverandør kan man alternativt bruke applikasjonen aissender for å lese av en fil med rådata for testing eller for å eventuelt kjøre et alternativt opplegg. Denne startes opp fra det samme stedet som beskrevet i punkt 2. 6.a Før man utfører oppstartskommandoen av aissender bør man endre plasseringen og eventuelt navnet på filen som skal leses inn slik at den prøver å lese fra riktig sted. For å gjøre dette så endrer man linjen Path file=filesystems.getdefault().getpath("/home/hioa/ais-parsing_test", "nmea.dump"); til Path file=filesystems.getdefault().getpath( <banen der innlesningsfilen ligger>", "<navn på filen som skal leses inn>"). 6.b Dersom man ønsker at aissender.java og aisparser.java skal ligge på forskjellige maskiner, bør man endre hvilken adresse som klienten i aissender.java skal koble seg til. Dette gjør man ved å endre linjen InetAddress inetaddress = InetAddress.getLocalHost();, slik at datafeltet inetaddress inneholder den IP-adressen man ønsker at aissender skal koble seg til. 7. Etter filen er endret kan man starte opp AisSender med kommandoen sudo java -cp. dk.tbsalling.aismessages.aisparser&. 3.1.2 Oppstart av schedule-parseren Schedule-parseren er ikke et program som kjøres manuelt. Schedule-parseren (klassen ScheduleImporter i modulen schedule_importer.py) kjøres automatisk når e-postserveren mottar en e- postmelding som inneholder en gyldig rutetabellfil. Rutetabellfilen blir formatert(parset) og reiseplanene lagres i databasen. 6
Modulen schedule-parseren ligger i (schedule_imorter.py) ligger i mappen xeneta/marenostrum/schedule. Den kan flyttes til et annet sted, men da må importeringskoden i EmailDataHandler-klassen samsvare med filstien til modulen schedule-parseren ligger i. Importeringskoden er foreløpig følgende: from schedule.schedule_importer import ScheduleImporter. For at ScheduleImporter-klassen (schedule-parseren) skal fungere må Celery kjøre. Når en schedule-fil mottas av e-postserveren, lages det en Celery-task som analyserer e-postmeldingen og når det er verifisert at e-postmeldingen inneholder en gyldig schedule-fil som filvedlegg, kan parsingen av filen skje. For å motta schedule-filer hver uke fra ShipmentLink (www.shipmentlink.com), må man abonnere på schedule-filer ved å registrere en e-postadresse på deres web-side. Foreløpig abonnerer e-postadressen shipmentlink@marenostrum.xeneta.com på schedule-filer. Hvis man vil registrere en annen e- postadresse, kan man gjøre det på denne siden: http://www.shipmentlink.com/tvs3/jsp/tvs3_schedulesmail.jsp. Husk å avregistrere den gamle og å endre koden i modulen xeneta/email/handler.py og xeneate/marenostrum/email_handler.py til å godta meldinger med den e-postadressen det er registrert på. ScheduleImporter-klassen og EmailDataHandler-klassen inneholder kode som loggfører feil- og unntakshendelser til Xenetas Sentry-server. Les om logging i avsnitt 3.2.5 i Prosessraporten. I avsnitt 3.2.5.1 er det listet opp feilmeldinger og unntak som kan oppstå ved parsing av Schedule-filer. 3.1.3 Oppstart av rederistatistikkoppdatereren Akkurat som Schedule-parseren, så skal ikke dette programmet (klassen DepartureArrivalUpdater) kjøres manuelt. Den kjøres periodevis og er foreløpig satt til å kjøre en gang i timen. For at DepartureArrivalUpdater-klassen skal fungere må Celery kjøre. Dette er fordi den skal kjøre periodevis som en Celery-task. 3.1.4 Oppstart av web-applikasjonen Web-applikasjonen startes ved å kjøre kommandoen sudo python xeneta/marenostrum/web/rendering_templates.py & hvis man er i git-rotmappen (annerledes filsti hvis man er i annen mappe). Web-applikasjonen kjører på port 80 og web-siden kan dermed aksesseres ved å gå til siden hioa-project.xeneta.com. 7
3.1.5 Feil og rettingsmuligheter Denne delen tar for seg mulige feil ved vanlige brukstilfeller og eventuelt hvordan man fikser dem. 3.1.5.1 Adressen er allerede i bruk Dersom denne meldingen kommer opp, kan det komme av to grunner. Enten er en av portene i bruk av et annet program. Da bør man sørge for å lukke programmet på en forsvarlig måte, og deretter starte opp dette programmet. Den andre muligheten er at hele eller deler av programmet allerede kjører. Ønsker man å starte programmet om igjen, bør man drepe alle de aktive prosessene som kjører programmet. De prosessene som man er nødt til å drepe er: aisparser, aisreceiver.py og eventuelt AisSender og Threadedaisparser dersom man har startet opp disse. 3.1.5.2 Aisparseren er inresponsiv og treg Sluttbruker bør sørge for at deres system er på høyde med systemkravene som er satt i produktdokumentasjonen. Vi kan ikke garantere at aisparseren vil kjøre effektivt på alle systemer. Hvis dette problemet oppstår ved bruk av threadedaisparser, så skyldes det sannsyneligvis at det kommer mer data inn enn det systemet/maskinen kan håndtere, og det vil derfor hope seg opp. Hvis dette skjer bør man enten bruke den vanlige versjonen av aisparser, oppgradere hardware, eller be leverandøren av aisdata om å begrense datamengden. 3.1.5.3 Feilmeldinger knyttet til parsing av schedule-filer Loggingfunksjonen sender feilmeldinger og unntaksfeilmeldinger til Sentry-serveren og på web-siden til Sentry-servren kan man se alle meldingene som har blitt sendt til Sentry-serveren. Dette avsnittet viser en liste over feilmeldinger. "Invalid filename: <FILNAVN>" (exception av typen ValueError). Filnavnet til schedule-filen er ugyldig. Filnavnet må være i formatet Schedules_YYYYMMDD.txt der YYYY er året, MM er måneden og DD dagen for datoen til schedule-filen. "Could not parse line: <REISPLANLINJE>". En linje i schedule-filen kunne ikke parses (tolkes). Enten inneholder akkurat den linjen ugyldige tegn eller så kan formatet i schedulefilen være ugyldig. For det første tillfellet bør kanskje det regulære uttrykket oppdateres til å kunne håndtere linjer av den typen. For det andre tillfellet, kan det rett og slett bare bety at ShipmentLink sendte en schedule-fil som inneholder fiel eller i verste fall er schedulefilformatet endret for alle fremtidige schedule-filer og man må oppdatere en stor del av ScheduleImporter-klassen (schedule-parseren). 8
"No schedules for ship '<SKIPNAVN>'. Schedule filename: <FILNAVN>". Det ble ikke funnet noen reiseplaner for dette skipet. Dette er ikke en feil, men bare en advarsel som kan brukes til debugging. Det kan hende at schedule-parseren ikke har klart å parse schedule-filen riktig. "Schedules parsed from a schedule with the same filename (<FILNAVN>) already exists. No schedules will be saved.". Det er blitt oppdaget reiseplaner som er parset fra samme schedulefil. Ingen reiseplaner blir lagret i databasen. En schedule-fil bør ikke parses mer enn én gang. Hvis man må parse den, så må alle reiseplandokumenter i databasen som er knyttet til samme schedule-filnavn slettes. The date YYYY-MM-DD extracted from the schedule filename is not in the current week. The schedules could only be saved in the historic/archive collection.. Datoen ekstrahert fra filnavnet til schedule-filen er ikke i denne uken. Dette betyr at ingen reiseplaner kunne lagres i collection-en schedules.current., altså reiseplaner for den kommende uken. Hvis ikke denne feilmeldingen er forventet, så er det noe galt med den dan delen av koden som ekstraherer datoen ut av filnavnet eller datoen er ugyldig. "Wrong date format: '<DATO>'. Should be mm/dd.". En dato i schedule-filen er i en ugyldig format. "Invalid date: YYYY-MM-DD" (exception av typen ValueError). Datoen i en av reiseplanene er ugyldig. Dette kan enten bety at schedule-filnavnet ikke stemmer overens med datoene i reiseplanene med tanke på skuddår eller at schedule-filen inneholder ugyldige datoer rett og slett. 3.1.5.4 Feilmeldinger knyttet til anaylsering av e-postmeldinger Feilmeldingene under er feilmeldinger knyttet til analysering av e-postmeldinger som ble sendt til en adresse som ender på @marenostrum.xeneta.com. "Invalid local-part '<LOKAL ADDRESSE' of the email address sent from <AVSENDERS MAILADRESSE>". Den delen av e-postadressen som kommer før @-tegnet er ugyldig. Den skal være shipmentlink for at programmet skal verifisere e-postmeldingen som en e- postmelding relatert til rutetabeller fra ShipmenLink. "Invalid schedule email message from <AVSENDERS MAILADRESSE>.". Ugyldig e- postmelding. Dette er ikke en gyldig e-postmelding. "Schedule email from <AVSENDERS MAILADRESSE> is not a multipart message.". E- postmeldingen er ikke en multi-part-melding. Den inneholder blant annet ikke filvedlegg. 9
"No file attachments could be found in schedule email from <AVSENDERS MAILADRESSE>". Ingen filvedlegg ble funnet i e-postmeldingen. Det betyr at ingen filvedlegg "File attachment '<FILNAVN>' in schedule email from <AVSENDERS MAILADRESSE>is not a txt-file.". Filvedlegget i e-postmeldingen er ikke en txt-fil. Resten av filvedleggene vil bli analysert. OBS! Bare én schedule-fil fra hver e-postmelding vil bli parset. 3.2 For brukere Web-siden viser punktlighetsstatistikker for alle rederier det er registrert transitter på. På web-siden finnes det en tabell over alle rederier med sine punktlighetsstatistikker. I den andre kolonnen står det hvor mange transitter det er registrert på rederiet. Den tredje kolonnen viser hvor stor del av alle transittene kom for tidlig eller for sent. Den fjerde kolonnen viser hvor stor avvik det er fra den estimerte ankomsttiden (ETA) og den virkelige ankomsttiden. Tabellen er sortert etter forsinkelsesprosent (andre kolonne). Man kan klikke på tabell-headeren i en bestemt kolonne for å sortere tabellen etter den kolonnen man klikker på. Over tabellen står det beskrevet hvordan punktlighetsstatistikkene er beregnet. Resten av web-siden inneholder grafer som viser forskjellige punktlighetsstatistikker over tid de siste 18 månedene. For en nærmere forklaring av hvordan tallene og dataene bak grafene blir beregnet, se i produktrapporten i kapittel 6.4. For de fleste brukere, er imidlertid forklaringen på web-siden god nok. 10