Käyttöohje

Käyttöohje

Tämä dokumentti kuvaa miten UsaProxya ja muita työkaluja voidaan käyttää eri tarkoituksiin ja miten eri työkalut liittyvät toisiinsa. Ohje on kirjoitettu suomeksi, koska se on tarkoitettu lähinnä Tampereen Yliopiston tutkimuskäyttöön, mutta se on hyödyllinen myös muille.

Pikaohje

Tämä ohje kertoo miten UsaProxy käynnistetään palvelintilaan lokittamaan halutun tyyppisiä elementtejä sekä niiden sisällöt.

Asennus

UsaProxy asennetaan purkamalla asennuspaketti haluttuun hakemistoon. Asennuksen voi myös tehdä tämän ohjeen lopussa olevien käännösohjeiden mukaisesti.

Käynnistys

UsaProxy käynnistetään asennushakemistossa komentoriviltä komennolla java -jar usaproxyFork.jar -server -port 65300 -remoteIP 127.0.0.1 -remotePort 80 -nodeTypes div;h1;h2;h3;h4;h5;h6 -logContents -logContentsLimit 200 -logExternalUrl -logSplit d. Tämä komento käynnistää UsaProxyn palvelintilaan, jossa se kuuntelee HTTP-pyyntöjä portissa 65300 ja ohjaa ne osoitteeseen 127.0.0.1 porttiin 80, jossa on oltava HTTP-palvelin (esim. Apache) palvelemassa varsinaisia WWW-sivuja. Komento rajoittaa lokitetut elementtityypit div- ja hX -tyyppisiin elementteihin, ja kytkee päälle elementtien sisällön ajonaikaisen lokituksen, rajoittaen sen maksimissaan 200 merkkiin. Lisäksi UsaProxya pyydetään lokittamaan varsinaisten URLien sijaan "ulkoiset" URLit, jolloin lokitetaan se osoite, jolla käyttäjä tuli sivulle, eikä sitä osoitetta jonka UsaProxy näkee. Lokitiedostojen päivittäinen pilkkominen kytketään päälle.

WWW-sivujen katselu

UsaProxyn valvomia WWW-sivuja voi avata normaalisti selaimella. URL:ksi kirjoitetaan UsaProxyn host-osoite ja yllä olevassa komennossa mainittu porttinumero, ja loppuosa URL:stä kirjoitetaan kuten ennenkin. Esim. jos aikaisemmin palvelimella example.com oleva sivu on avattu URL:lla http://example.com/~user/test.html, ja UsaProxy on asennettu palvelimelle default.com porttiin 65300 välittämään example.com -palvelimen sivuja, saman sivun saa avattua URL:lla http://default.com:65300/~user/test.html

Raporttien luonti

1. Pura UsaProxyReportGenerator paketistaan haluamaasi hakemistoon tai suorita asennus tämän ohjeen lopussa olevien käännösohjeiden mukaisesti
2. Käynnistä komentoriviltä asennushakemistosta komento java -jar usaproxyreportgenerator.jar <lokitiedosto>. Älä kopioi UsaProxyn lokeja mihinkään, vaan osoita raporttigeneraattorille alkuperäinen polku. Jos lokitiedostot ovat esimerkiksi toisella koneella ja ne on pakko kopioida, kopioi myös httpTraffic-hakemisto sisältöineen.
3. Muodostuneita HTML-raportteja voi katsella ainakin FireFoxilla ja Chromella.

Lokin tallennus tietokantaan

1. Pura UsaProxyLog2DB paketistaan haluamaasi hakemistoon tai suorita asennus tämän ohjeen lopussa olevien käännösohjeiden mukaisesti.
2. Lue mukana tullut readme.txt-tiedosto ja suorita sen mukaiset asetustoimet.
3. Käynnistä asennushakemistossa komentoriviltä komento java -jar usaproxylog2db.jar <lokitiedosto>. Älä kopioi lokeja mihinkään, vaan osoita ohjelmalle alkuperäinen polku. Jos lokitiedostot on pakko kopioida, kopioi myös httpTraffic-hakemisto sisältöineen.
4. Lokeja voi tallentaa tietokantaan useampia suorittamalla kohta 3 uudelleen.

Mitä UsaProxy ja muut työkalut tekevät?

UsaProxy-tools on kokoelma työkaluja, joilla voi seurata käyttäjien toimintaa WWW-sivuilla. Kokoelmaan kuuluu kolme itsenäistä sovellusta, UsaProxy-fork, UsaProxyReportGenerator ja UsaProxyLog2DB, sekä yksi sovellusohjelmointia helpottava Java-kirjasto, UsaProxyLogParser. UsaProxyReportGenerator ja UsaProxyLog2DB on toteutettu UsaProxyLogParser-kirjaston avulla.

UsaProxy-fork

UsaProxy-fork on UsaProxyn laajennos. UsaProxy on Javalla toteutettu HTTP-välityspalvelin, joka lokittaa käyttäjän toimintaa WWW-sivuilla. Käyttäjän tekemien HTTP-pyyntöjen lokituksen lisäksi se lokittaa käyttäjän toimia kaikilla WWW-sivuilla lisäämällä jokaiseen välittämäänsä sivuun JavaScriptiä, joka lähettää UsaProxylle käyttäjän toimista syntyvää dataa lokitettavaksi.

UsaProxyLogParser

UsaProxyLogParser tarjoaa sovellusohjelmointirajapinnan, jonka avulla UsaProxyn tuottamia lokeja on helppo käsitellä missä tahansa Java-pohjaisessa ohjelmassa. Kirjaston päätehtävä on lokin parsiminen ja parsitun datan muuntaminen oliorakenteeksi.

UsaProxyReportGenerator

UsaProxyReportGenerator luo HTML-raportteja sille parametrina annetun UsaProxy-lokitiedoston perusteella. Raportteja luodaan yksi per UsaProxy-istunto. Raportista näkyy millä sivuilla käyttäjä on istunnon aikana liikkunut ja mitä kohtia eri sivuista käyttäjä on milloinkin katsellut. Raportin sisältöä voi filtteröidä jälkikäteen suoraan raportin sisäisillä työkaluilla.

UsaProxyLog2DB

UsaProxyLog2DB tallentaa lokitiedostoja tietokantaan. Se käyttää UsaProxyLogParserin tarjoamaa malli- ja ORM-kerrosta. Varsinaisen ORM:n toteuttaa Hibernate-kirjasto. Kirjaston avulla lokit voidaan tallentaa helposti erilaisiin tietokantoihin. Tietokantaan tallennus mahdollistaa lokitiedon analysoinnin SQL-työkaluilla. Lisäksi näin voidaan säilyttää valmiiksi jäsennettyä lokidataa ja lukea se myöhemmin takaisin Java-olioiksi.

UsaProxyn käyttö

Tämä ohje kertoo mihin eri tarkoituksiin UsaProxya voi käyttää ja miten eri komentoriviparametrit vaikuttavat ohjelman toimintaan.

Käyttökohteet

UsaProxy tukee neljää erilaista tilaa:

• Välityspalvelin (Proxy)
• Palvelin (Server)
• Tarkkailu (Remote Monitoring)
• Jaettu selain (Shared Browsing)

Tämä ohje käsittelee näistä kahta ensimmäistä. Muita tiloja kannattaa käyttää mieluiten alkuperäisen UsaProxyn kanssa, sillä tämän version kanssa niitä ei ole testattu. UsaProxy-paketin readme.txt-tiedostossa on lisätietoja.

Käyttö välityspalvelimena

Välityspalvelimena toimiessaan UsaProxy on kuin mikä tahansa HTTP-välityspalvelin. Se asetetaan kuuntelemaan jotakin TCP-porttia, jossa se välittää HTTP-pyyntöjä asiakkaan ja palvelimen välillä. Välityspalvelimena käyttö vaatii, että käyttäjä asettaa selaimensa HTTP-proxyksi UsaProxyn osoitteen.

Välityspalvelinkäytössä UsaProxy voi valvoa minkä tahansa verkkosivun käyttöä. Tarkasteltavia sivuja ei tarvitse valmistella mitenkään etukäteen, kunhan ne ovat julkisessa internetissä saatavilla.

Käyttö palvelimena

Palvelintilassa UsaProxy ottaa WWW-palvelimen roolin, mutta ei itse palvele varsinaista sisältöä, vaan noutaa sen HTTP-pyyntöjen perusteella joltakin ulkoiselta WWW-palvelimelta. Tämä palvelin määritellään UsaProxya käynnistettäessä remoteIP- ja remotePort-vivuilla. Ulkoinen palvelin voi olla esimerkiksi Apache tai IIS-palvelin. Ulkoisen palvelimen ei tarvitse olla julkisessa internetissä, mutta se on oltava UsaProxyn saavutettavissa.

Tässä tilassa käyttäjän on aina katseltava verkkosivuja UsaProxyn osoitteen kautta. URL-polut (esim. /~user/test.html) kirjoitetaan normaalisti UsaProxyn osoitteen perään.

Palvelintilassa UsaProxya ei voi käyttää välityspalvelimena.

Asennus

UsaProxy asennetaan yksinkertaisesti purkamalla asennuspaketti mihin tahansa hakemistoon. On suositeltavaa, että raporttigeneraattori asennetaan eri hakemistoon kuin UsaProxy.

Käynnistäminen

UsaProxy käynnistetään yksinkertaisimmillaan komentoriviltä komennolla java -jar usaproxyFork.jar, jolloin se käynnistyy oletusasetuksin välityspalvelintilaan.

Välityspalvelintilaan käynnistäminen

UsaProxy käynnistyy oletuksena välityspalvelintilaan. Seuraavat komentoriviparametrit ovat tärkeimmät tässä tilassa:

• -port <numero> määrää mitä TCP-porttia UsaProxy kuuntelee (oletus: 8000).
• -nodeTypes <tyypit> määrää minkä elementtityyppien näkymistä selaimen ikkunassa seurataan - puolipistein erotettu lista (oletus: img;h1;h2;h3;h4;h5;h6).
• -logContents kytkee päälle elementtien sisällön ajonaikaisen lokituksen. Jos tämä ei ole päällä, raporttigeneraattori yrittää etsiä elementtien sisällöt UsaProxyn httptraffic-lokeista. Tämä kannattaa erityisesti kytkeä päälle jos halutaan seurata sivuja, joiden sisältöä manipuloidaan skripteillä. (oletus: pois päältä)
• -logContentsLimit <numero> määrää kuinka monta merkkiä elementin sisällöstä enimmillään lokitetaan ajonaikaisesti. Asetuksella ei ole vaikutusta jos sisällön ajonaikainen lokitus ei ole päällä. Jos tätä ei aseteta, lokitetaan elementin koko sisältö.
• -logSplit h|d|w|m kytkee lokitiedoston pilkkomisen päälle. Uusi lokitiedosto aloitetaan joko tunneittain (h), päivittäin (d), viikottain (w) tai kuukausittain (m).
• -logSplitAt <numero> määrää tarkan hetken jolloin uusi lokitiedosto aloitetaan. Toiminta riippuu logSplit-parametrin arvosta siten, että 1) h-tilassa se määrää kuinka monta minuuttia yli tasatunnin lokitiedosto katkaistaan, 2) d-tilassa mihin kellonaikaan lokitiedosto katkaistaan (aina tasatunti), 3) w-tilassa minä viikonpäivänä lokitiedosto katkaistaan (1=maanantai), 4) m-tilassa kuinka monentena päivänä lokitiedosto katkaistaan.
• -logSplitInterval <numero> määrää katkaistaanko lokitiedosto joka kerta kun katkaisuaikaväli tulee täyteen, vai esimerkiksi vain joka toinen tai kolmas kerta. Esim. h-tilassa arvo 3 tarkoittaisi lokitiedoston katkaisua joka kolmas tunti.

Palvelintilaan käynnistäminen

UsaProxyn käynnistäminen palvelintilaan vaatii komentoriviparametrin -server lisäämistä käynnistyskomentoon. Lisäksi seuraavat komentoriviparametrit on asetettava:

• -remoteIP on ulkoisen WWW-palvelimen IP-osoite (127.0.0.1 jos kyseessä on paikallinen palvelin).
• -remotePort on ulkoisen WWW-palvelimen porttinumero (usein 80).
• -server kytkee palvelintilan päälle.
• -logExternalUrl kytkee UsaProxy-URLien lokituksen päälle. Oletuksena lokitetaan varsinaiset URL-osoitteet, joilla alkuperäiselle WWW-sivulle pääsisi ilman UsaProxya. Nämä osoitteet voivat kuitenkin olla merkityksettömiä jos WWW-palvelin sijaitsee paikallisella palvelimella tai lähiverkossa siten, että se ei näy julkiseen internetiin. (oletus: pois päältä)

Myös kaikki välityspalvelintilan komentoriviparametrit toimivat palvelintilassa.

Lokin kertyminen

UsaProxy kerryttää varsinaista päälokia tiedostoon nimeltä log.txt. Lisäksi UsaProxy lokittaa jokaisen HTTP-pyynnön httpTraffic\log-hakemistoon. HTTP-lokin tiedostonimi on muotoa httpTraffic<n>.txt, missä n on juokseva numero, joka on kyseisen HTTP-pyynnön uniikki tunniste. Lokia kertyy sitä mukaa kun käyttäjät lataavat seurannassa olevia sivuja ja selaavat niitä.

Lokin kertyminen on täysin automaattista, joten siitä ei tarvitse välittää, jos haluaa vain luoda raportteja.

Pääloki

Päälokiin kirjataan seuraavan tyyppisiä tapahtumia:

• HTTP-pyynnöt: Nämä rivit muodostavat uuden HTTP traffic id:n. Ne tunnistaa avainsanasta httptraffic.
• DOM-tapahtumat: Sivun sisällä tapahtuvat DOM-tapahtumat, eli esimerkiksi hiiren klikkaukset ja näppäimistön painallukset.
• Elementtien ruudulle ilmestyminen: Kun seurattava elementti ilmestyy ruudulle, se kirjataan lokiin. Nämä tapahtumat tunnistaa avainsanasta appear.
• Elementtien poistuminen ruudulta: Kun seurattava elementti katoaa ruudulta, se kirjataan lokiin. Nämä tapahtumat tunnistaa avainsanasta disappear.
• Ruutusiirtymät: Kun sivua selataan johonkin suuntaan, ruudun sijainti kirjataan lokiin. Nämä tapahtumat tunnistaa avainsanasta viewportChange.
• Vieritys: Kun sivun vieritys aloitetaan, se kirjataan lokiin. Avainsana scrollStart.

HTTP-loki

HTTP-lokiin kirjataan kaikkien sivulatausten HTTP-otsikkotiedot sekä UsaProxyn välittämä dokumentti kokonaisuudessaan.

Lokitiedostojen muoto

Seuraavassa ohjeessa kerrotaan missä muodossa UsaProxyn lokimerkinnät ovat.

Pääloki log.txt

Jokainen päälokin rivi on joko muotoa

<IP-osoite> <aikaleima> sd=<HTTP-liikenteen tunniste> sid=<istunnon tunniste> event=<tapahtuman nimi> <attribuutit>

tai muotoa

<IP-osoite> <aikaleima> httptraffic url=<sivun osoite> sd=<HTTP-liikenteen tunniste>,

missä

• <IP-osoite> on käyttäjän IP-osoite (esim 134.231.56.11)
• <aikaleima> on lokimerkinnän tarkka aikaleima muodossa VVVV-KK-PP,hh:mm:ss.SSS
• <HTTP-liikenteen tunniste>on HTTP-liikenteen tunniste, joka on UsaProxyn automaattisesti muodostama uniikki juokseva numero
• <istunnon tunniste> on UsaProxyn muodostama uniikki istunnon tunniste, joka on alfanumeerinen merkkijono
• <tapahtuman nimi> on UsaProxyn tunniste sivun sisäiselle tapahtumalle. Tämä on usein sama kuin vastaavan DOM-tapahtuman nimi, esim. 'mouseover'.
• <attribuutit> on joukko avain-arvo -pareja, jotka kertovat tapahtuman luonteen tarkemmin

Event-rivit kertovat tietyn sivun sisäisistä tapahtumista. Ne ovat joko suoria DOM-tapahtumia tai niiden perusteella muodostettuja seurantaan liittyviä erityisiä tapahtumia (esim. 'appear' ja 'disappear'). Httptraffic-rivit kertovat milloin käyttäjä on avannut tietyn sivun selattavaksi. HTTP-liikenteen tunnisteen elinkaari alkaa tästä rivistä.

HTTP-liikenneloki httpTraffic/log/

Jokainen HTTP-liikennelokitiedosto on muotoa

[request]
<HTTP-otsikot>

[response]
<HTTP-otsikot>

<dokumentti>

missä <HTTP-otsikot> sisältää HTTP-pyynnön tai -vastauksen otsikkotiedot siinä muodossa kuin ne on lähetetty. <dokumentti> on välitetty dokumentti kokonaisuudessaan.

Raporttigeneraattorin käyttö

Tämä ohje kertoo mihin tarkoitukseen ja miten raporttigeneraattoria käytetään.

Käyttötarkoitus

Raporttigeneraattorilla muodostetaan UsaProxyn tuottamista lokitiedostoista HTML-raportteja. Raporteista on mahdollista tarkastella seuraavia asioita:

• Käyttäjän avaamat verkkosivustot, joista jokaisesta kuvaaja, jossa:
  • Seurattujen elementtien näkyminen (aika ja sijainti) käyttäjän selaimessa
  • Sivun vieritys
  • HTTP-otsikkotiedot
• Käyttäjän IP-osoite
• Istunnon tunnistetiedot

Asennus

Raporttigeneraattori asennetaan purkamalla asennuspaketti mihin tahansa hakemistoon. Ei ole kuitenkaan suositeltavaa purkaa sitä samaan hakemistoon missä UsaProxy on asennettuna. Generaattori voidaan myös asentaa tämän ohjeen lopussa olevilla lähdekoodin käännösohjeilla.

Raportin luominen

Raportti luodaan käynnistämällä asennushakemistossa komentoriviltä raporttigeneraattorin JAR-paketti ja osoittamalla sille UsaProxyn lokitiedoston sijainti. Tyypillisesti tämä tapahtuu siis komennolla java -jar usaproxyreportgenerator.jar <UsaProxy-lokipolku>, missä <UsaProxy-lokipolku> on täydellinen polku UsaProxyn lokitiedostoon.

Generaattorille on annettava alkuperäinen lokitiedoston sijainti, koska se yrittää etsiä myös HTTP-liikennelokitiedostoja lokihakemiston alta. Jos alkuperäistä sijaintia ei voida käyttää, lokitiedostot voi myös kopioida muualle. Tällöin on kopioitava seuraavat tiedostot ja hakemistot:

• log.txt -tiedosto
• httpTraffic -hakemisto

Raportti muodostuu tiedostoon nimeltä usaproxy-session-report-<istunnon ID>.html, missä <istunnon ID> on UsaProxyn generoima istunnon tunniste. Generaattorille voi antaa vivun -outputDir <hakemisto>, missä <hakemisto> on hakemisto mihin HTML-tiedostojen halutaan muodostuvan. Jos vipua käytetään, on samaan hakemistoon kopioitava myös hakemistot js ja css.

Raportin lukeminen

Raportteja voi lukea ainakin FireFox- ja Chrome-selaimilla.

UsaProxyLog2DB-sovelluksen käyttö

Tämä ohje kuvaa mihin ja miten UsaProxyLog2DB-sovellusta voi käyttää ja miten se asennetaan.

Käyttötarkoitus

Sovelluksen avulla lokitiedostoja voi lukea relaatiotietokantaan. Tämä mahdollistaa SQL-työkalujen käytön lokitiedon analysoinnissa. Valmiiksi jäsennetyn lokidatan voi myös lukea tietokannasta takaisin olioiksi käyttäen samaa ORM-mallia, mutta se ei kuulu osaksi tätä sovellusta.

Asennus

Sovellus asennetaan purkamalla asennuspaketti mihin tahansa hakemistoon. Ei ole kuitenkaan suositeltavaa purkaa sitä samaan hakemistoon missä UsaProxy on asennettuna. Sovellus voidaan myös asentaa tämän ohjeen lopussa olevilla lähdekoodin käännösohjeilla.

Asetukset

Sovellus vaatii olemassaolevan tietokannan, johon se tallentaa lokitiedot. Tarkemmat ohjeet löytyvät readme.txt-tiedostosta.

Lokitiedoston lukeminen tietokantaan

Loki luetaan tietokantaan käynnistämällä asennushakemistossa komentoriviltä sovelluksen JAR-paketti ja osoittamalla sille UsaProxyn lokitiedoston sijainti. Tyypillisesti tämä tapahtuu siis komennolla java -jar usaproxylog2db.jar <UsaProxy-lokipolku>, missä <UsaProxy-lokipolku> on täydellinen polku UsaProxyn lokitiedostoon.

Sovellukselle on annettava alkuperäinen lokitiedoston sijainti, koska se yrittää etsiä myös HTTP-liikennelokitiedostoja lokihakemiston alta. Jos alkuperäistä sijaintia ei voida käyttää, lokitiedostot voi myös kopioida muualle. Tällöin on kopioitava seuraavat tiedostot ja hakemistot:

• log.txt -tiedosto
• httpTraffic -hakemisto

Lähdekoodi ja kääntäminen

Tämä ohje kertoo mistä ohjelman lähdekoodin saa ja miten se käännetään.

GitHub-projekti

Kaikki lähdekoodi ja muut resurssit löytyvät projektin github-sivuilta. Lähdekoodin voi ladata joko suoraan githubin tarjoamilla WWW-pohjaisilla työkaluilla (ZIP-paketti tästä) tai käyttäen git-ohjelmaa. Lähdekoodi-repository on julkinen.

Kääntäminen

Ohjelma on jaettu useaan eri osaan, jotka on lueteltu toisaalla tässä dokumentissa. Jokainen osa on myös oma käännösyksikkönsä. Seuraavat ohjeet neuvovat miten eri osat käännetään. Käännöstä varten lähdekoodipaketti on purettava.

Tarvittavat työkalut

• Java SE 7 JDK
• Maven

Lataa ja asenna ensin JDK ja sen jälkeen Maven niiden omien asennusohjeiden mukaisesti.

UsaProxyFork

1. Avaa komentorivi usaproxyFork-hakemistoon.
2. Anna komento mvn package. Maven alkaa ladata tarvittavia paketteja ja kääntää ohjelman.
3. Maven-ajon päätyttyä ohjelmasta on muodostunut ajettava versio target-hakemistoon.
4. Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä target-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.

usaproxylogparser

1. Avaa komentorivi UsaProxyLogParser-hakemistoon.
2. Anna komento mvn install. Maven lataa tarvittavat kirjastot, kääntää ohjelman ja asentaa sen paikalliseen Maven-repositoryyn.

usaproxyreportgenerator

1. Asenna usaproxylogparser edellä olevan ohjeen mukaisesti.
2. Avaa komentorivi usaproxyreportgenerator-hakemistoon.
3. Anna komento mvn package. Maven lataa tarvittavat kirjastot ja kääntää ohjelman.
4. Ajon päätyttyä ohjelmasta on muodostunut ajettava versio target-hakemistoon.
5. Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä target-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.

usaproxylog2db

1. Asenna usaproxylogparser edellä olevan ohjeen mukaisesti.
2. Avaa komentorivi usaproxylogdb-hakemistoon.
3. Anna komento mvn package. Maven lataa tarvittavat kirjastot ja kääntää ohjelman.
4. Ajon päätyttyä ohjelmasta on muodostunut ajettava versio target-hakemistoon.
5. Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä target-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.

Lähdekoodin muokkaaminen

Jos haluat muokata lähdekoodia, voit tehdä sen lempityökaluillasi. Itse käytän työkaluna Eclipseä ja m2eclipse-pluginia, joka tarjoaa Maven-tuen. Lisäksi käytän Eclipsen git-pluginia.

Lisenssi

Kaikki ohjelman lähdekoodi on GPL-lisenssin alaista, joten kaikki tästä ohjelmasta johdettu koodi on julkaistava saman lisenssin alla.

Kontribuutiot

Jos haluat tehdä kontribuution alkuperäiseen lähdekoodiin, tee itsellesi githubiin forkki ja tee sen jälkeen alkuperäiseen projektiin pull request.