-
Notifications
You must be signed in to change notification settings - Fork 1
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.
Tämä ohje kertoo miten UsaProxy käynnistetään palvelintilaan lokittamaan halutun tyyppisiä elementtejä sekä niiden sisällöt.
UsaProxy asennetaan purkamalla asennuspaketti haluttuun hakemistoon. Asennuksen voi myös tehdä tämän ohjeen lopussa olevien käännösohjeiden mukaisesti.
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.
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
- Pura UsaProxyReportGenerator paketistaan haluamaasi hakemistoon tai suorita asennus tämän ohjeen lopussa olevien käännösohjeiden mukaisesti
- 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öshttpTraffic
-hakemisto sisältöineen. - Muodostuneita HTML-raportteja voi katsella ainakin FireFoxilla ja Chromella.
- Pura UsaProxyLog2DB paketistaan haluamaasi hakemistoon tai suorita asennus tämän ohjeen lopussa olevien käännösohjeiden mukaisesti.
- Lue mukana tullut
readme.txt
-tiedosto ja suorita sen mukaiset asetustoimet. - 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öshttpTraffic
-hakemisto sisältöineen. - Lokeja voi tallentaa tietokantaan useampia suorittamalla kohta 3 uudelleen.
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 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 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 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 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.
Tämä ohje kertoo mihin eri tarkoituksiin UsaProxya voi käyttää ja miten eri komentoriviparametrit vaikuttavat ohjelman toimintaan.
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.
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.
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.
UsaProxy asennetaan yksinkertaisesti purkamalla asennuspaketti mihin tahansa hakemistoon. On suositeltavaa, että raporttigeneraattori asennetaan eri hakemistoon kuin UsaProxy.
UsaProxy käynnistetään yksinkertaisimmillaan komentoriviltä komennolla java -jar usaproxyFork.jar
, jolloin se käynnistyy oletusasetuksin välityspalvelintilaan.
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 riippuulogSplit
-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.
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.
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ää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-lokiin kirjataan kaikkien sivulatausten HTTP-otsikkotiedot sekä UsaProxyn välittämä dokumentti kokonaisuudessaan.
Seuraavassa ohjeessa kerrotaan missä muodossa UsaProxyn lokimerkinnät ovat.
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ä.
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.
Tämä ohje kertoo mihin tarkoitukseen ja miten raporttigeneraattoria käytetään.
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
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.
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
.
Raportteja voi lukea ainakin FireFox- ja Chrome-selaimilla.
Tämä ohje kuvaa mihin ja miten UsaProxyLog2DB-sovellusta voi käyttää ja miten se asennetaan.
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.
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.
Sovellus vaatii olemassaolevan tietokannan, johon se tallentaa lokitiedot. Tarkemmat ohjeet löytyvät readme.txt
-tiedostosta.
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
Tämä ohje kertoo mistä ohjelman lähdekoodin saa ja miten se käännetään.
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.
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.
Lataa ja asenna ensin JDK ja sen jälkeen Maven niiden omien asennusohjeiden mukaisesti.
- Avaa komentorivi
usaproxyFork
-hakemistoon. - Anna komento
mvn package
. Maven alkaa ladata tarvittavia paketteja ja kääntää ohjelman. - Maven-ajon päätyttyä ohjelmasta on muodostunut ajettava versio
target
-hakemistoon. - Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä
target
-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.
- Avaa komentorivi
UsaProxyLogParser
-hakemistoon. - Anna komento
mvn install
. Maven lataa tarvittavat kirjastot, kääntää ohjelman ja asentaa sen paikalliseen Maven-repositoryyn.
- Asenna usaproxylogparser edellä olevan ohjeen mukaisesti.
- Avaa komentorivi
usaproxyreportgenerator
-hakemistoon. - Anna komento
mvn package
. Maven lataa tarvittavat kirjastot ja kääntää ohjelman. - Ajon päätyttyä ohjelmasta on muodostunut ajettava versio
target
-hakemistoon. - Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä
target
-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.
- Asenna usaproxylogparser edellä olevan ohjeen mukaisesti.
- Avaa komentorivi
usaproxylogdb
-hakemistoon. - Anna komento
mvn package
. Maven lataa tarvittavat kirjastot ja kääntää ohjelman. - Ajon päätyttyä ohjelmasta on muodostunut ajettava versio
target
-hakemistoon. - Jos haluat siirtää sovelluksen toiseen hakemistoon, käytä
target
-hakemistoon muodostunutta ZIP-pakettia, joka sisältää ohjelman asennuspaketin kokonaisuudessaan.
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.
Kaikki ohjelman lähdekoodi on GPL-lisenssin alaista, joten kaikki tästä ohjelmasta johdettu koodi on julkaistava saman lisenssin alla.
Jos haluat tehdä kontribuution alkuperäiseen lähdekoodiin, tee itsellesi githubiin forkki ja tee sen jälkeen alkuperäiseen projektiin pull request.