Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- documentazione_3di:extraway:xwls [2010/04/22 16:48] – rtirabassi
+++ documentazione_3di:extraway:xwls [2012/07/23 15:19] (versione attuale) – eliminata rtirabassi
@@ Linea 1: / Linea 1: @@
-====== Manuale di Configurazione del modulo eXtraWay Log Server ======
-===== Introduzione =====
-eXtraWay Log Server è lo strumento per mezzo del quale tutti i moduli della piattaforma eXtraWay stilano le proprie registrazioni nei files che vengono dislocati nella directory logs parallela a quella che ospita i moduli binari.
-Uniformare il metodo d'uso semplifica la vita a chi produce nuovi moduli in quanto esistono nella principale libreria utilizzata da tutti i moduli della piattaforma (libreria libxw), una serie di funzioni appositamente studiate per poter scrivere il proprio log senza doversi occupare della dislocazione ed eventuale rotazione dei files di log.\\
-Quanto detto avviene sulla base di un file di configurazione, xwls.conf.xml che trova la propria naturale dislocazione nella directory conf anch'essa parallela a quella dei moduli eseguibili.
-I log stilati dal modulo eXtraWay Log Server hanno un formato uniforme spiegato nel dettagli nel documento che ne descrive il formato.
-===== Configurazione dei Logs =====
-La configurazione del modulo "xwls" avviene, come detto, per mezzo del file xwls.conf.xml che si trova nella directory conf parallela a quella degli eseguibili eXtraWay. In tale file si assegna un nome e delle caratteristiche ai logs che non fossero già stati configurati o non siano logs di default.\\
-Il file contiene una dichiarazione che può essere esemplificata come segue:
-<code>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE xwls_cfg SYSTEM "http://www.3di.it/extraway/xwls_20050913.dtd">
-<xwls_cfg>
-   <log_files num="1" name="wd_journal.log" cycling="0"/>
-   <log_files num="4" name="mylog.log" cycling="4" size="0x00400000"/>
-   <log_files num="5" name="temp.log" skip="yes"/>
-</xwls_cfg>
-</code>
-Il file presenta un elemento radice xwls_cfg che contiene singoli elementi log_files.\\
-Questi elementi a loro volta devono avere un attributo num che lega la configurazione al log desiderato ed imposta quanto segue:
-    * name: nome del file di log da utilizzare per questo codice. Molti dei moduli appartenenti alla piattaforma eXtraWay hanno un proprio codice e quindi impostazioni di default. Vds. Elenco codici assegnati ai moduli eXtraWay e loro default
-    * cycling: indica il numero di log da creare e far ruotare. In condizioni normali il server aggiunge un numero in coda al nome (1, 2, 3 e così via) per le copie fatte ruotare e cancella progressivamente la più vetusta rinominando le altre al raggiungimento di una soglia dimensionale.
-    * size: Dimensione che deve raggiungere un file di log perché venga ruotato.
-    * skip: Indicazione che, se pari a "yes" impone che il log venga temporaneamente ignorato.
-    * syslog: Se presente e se assume un valore numerico diverso da 0 indica che quanto stilato nel log indicato dev'essere stilato anche nel log di sistama dipendentemente dal tipo di piattaforma (syslog per Unix, Event Viewer per Windows). Il valore di questo parametro rappresenta un bitmap che indica che tipo di log compiere nel log di sistema, ovvero quali informazioni vi si debbano registrare. Il valore assunto può essere una combinazione dei seguenti valori:
-          * 1 = SYSLOG_MODE_INFO: Vengono poste nel syslog tutte le registrazioni considerate informazioni.
-          * 2 = SYSLOG_MODE_WARNING: Vengono poste nel syslog tutte le registrazioni considerate richieste d'attenzione.
-          * 4 = SYSLOG_MODE_ERROR: Vengono poste nel syslog tutte le registrazioni considerate errori.
-Come detto alcuni codici sono già stati assegnati ma questo non toglie che per tali files si possano dare indicazioni diverse rispetto al default.\\ Vediamo quindi di spiegare l'esempio precedente:
-Si indica che il log associato al codice '1' si chiamerà "wd_journal.log" e non sarà soggetto a rotazione. Tale file cresce sempre in modo illimitato e non viene mai rimosso. Per il log associato al codice '4' si richiede che il file venga chiamato mylog.log e che venga fatto ciclare 4 volte per dimensioni pari a 4Mb. La cifra espressa in size può essere anche decimale, il prefisso la qualifica. Far ciclare 4 volte un file comporta che esisteranno mylog.log, mylog2.log, mylog3.log e mylog4.log.\\
-Quando la dimensione di mylog.log raggiunge e supera i 4Mb indicati, il file mylog4.log viene rimosso, tutti gli altri vengono rinominati accrescendone l'ordinale (mylog.log diventa mylog2.log) e si inizia la stesura di un nuovo mylog.log. In fine, per il codice '5', si è impostato un log temp.log ma esso risulta disabilitato.
-In assenza di dichiarazioni specifiche, si considera come valore di default una rotazione di 5 files di 5Mb l'uno fatti salvi valori di default specifici. Vds. Elenco codici assegnati ai moduli eXtraWay e loro default
-__Nota:__ Anche in presenza di dichiarazione specifiche esiste un caso particolare. Il log principale di eXtraWay, il file xw.log cui corrisponde il codice 0, può essere ri-configurato per indicare un diverso numero di cicli o una diversa dimensione ma non può essere annullato, reso non cicico o direzionato su syslog. Se vengono date implementazioni inesatte (assenza di cicli o dimensione nulla) esse vengono riportate ai valori di default descritti precedentemente((A partire dalla versione 1.3.1.4)).
-Qualora si faccia uso di un codice di log non associato ad alcuna dichiarazione il nome associato la log sarà Undefined<codice>_.log e rispetterà i valori di default appena indicati. Se, ad esempio, il log '7' non viene configurato ma viene utilizzato i files risultanti, con la loro rotazione, saranno Undefined7_.log,Undefined7_2.log, Undefined7_3.log e Undefined7_4.log.\\
-===== Come configurare il Log Server per usare una porta specifica =====
-L'origine del Log Server trova le proprie radici nel progetto HighWay per il quale esiste un //HighWay Log Server// che è il progenitore del modulo in esame.\\
-L'evoluzione del suddetto hls ha condotto alla creazione di xwls in grado di offrire funzionalità di logging a moduli diversi per scopi diversi.\\
-Sin dall'origine di xwls, esso s'è distinto dal suo progenitore per la possibilità, teorica, di eseguire il Log Server indicando su quale porta esso doveva operare. Ora si può fare qualcosa si più. La precedente possibilità, di fatto, era prettamente teorica in quanto i moduli chiamanti, come eXtraWay Server, non erano in grado di regolare la porta di xwls nel momento della sua esecuzione. Questo comportava che comunque andassero le cose, xwls veniva sempre eseguito sulla sua porta standard (Vds. Elenco dei numeri di porta Tcp/Udp utilizzati dai programmi HighWay/eXtraWay).\\
-Le varianti introdotte dalla versione 1.3.0.* del modulo consentono impostazioni diverse. Fatta salva la possibilità di indicare su riga di comando, col parametro -p, su quale porta si desidera che operi il Log Server, la porta che tutti i client useranno per dialogare con il modulo può ora essere indicata direttamente nel file di configurazione indicato precedentemente. In esso è stato aggiunto un attributo port dell'elemento xwls_cfg nel quale può essere indicato il numero di porta sul quale opera il Log Server.\\
-Tutti i client (attualmente eXtraWay Server, eXtraWay Generic Launcher ed eXtraWay Inter Process Comunicator) si avvalgono dello stesso file di configurazione di xwls e sanno quindi con quale porta comunicare. Questo per evitare che tutti i client debbano essere informati su riga di comando o su altro file di configurazione della porta da utilizzare. Rimane, per il solo server eXtraWay nella versione per piattaforma Win32, la possibilità di indicare una porta specifica. In questo caso, però, moduli come xips e xwgl non riusciranno a dialogare con lo stesso Log Server.
-Cerchiamo di delineare il panorama:
-  - Se nel file xwls.conf.xml non viene indicata alcuna porta, i client ed il modulo xwls vengono eseguiti sulla porta standard (Vds. Elenco dei numeri di porta Tcp/Udp utilizzati dai programmi HighWay/eXtraWay)
-  - Se nel file xwls.conf.xml viene indicata una porta, essa sovrascrive le impostazioni di default di cui al punto a ed xwls viene eseguito per operare su tale porta così come tutti i client vengono eseguiti per dialogare sulla stessa porta.
-  - Se siamo in una qualsiasi delle precedenti condizioni ma eseguiamo il Server eXtraWay su piattaforma Win32 con parametro\\ \\ -lp<portnumber>\\ \\ il server stesso lancerà un'istanza di xwls sulla porta indicata e dialogherà con esso, potenzialmente in esclusiva, solo su quella porta. Si prega di non confondere il parametro\\ \\ -lp\\ col parametro\\ \\ -p\\ in quanto il primo indica la porta del Log Server mentre secondo indica la porta sulla quale opera il Server eXtraWay.
-Se è quindi vero che in questo modo più distinte istanze di xwls possono coesistere è bene ricordare che è assolutamente improprio che due divese istanze scrivano gli stessi files (ovvero scrivano files appartenenti alla stessa directory) del resto, il cambio di porta si fa appositamente per questo ovvero per avere log distinti e separati.\\
-Concludiamo sottolineando che le novità apportate al Log Server non richiedono alcun allineamento di moduli se ci troviamo nello scenario classico di cui al punto a mentre richiedono di lavorare con moduli client allineati negli altri casi.\\
-===== Elenco codici assegnati ai moduli eXtraWay e loro default =====
-I codici esistenti ed assegnati sono:
-    * 0: Log del Server eXtraWay. Si tratta del file xw.log e delle sue rotazioni previste per default sino ad un massimo di 5 files di 5Mb l'uno.
-    * 1: Log della procedura di acquisizione unità informative detta Watch Doc Produce in file wd_journal.log non soggetto ad alcuna rotazione. La dimensione di questo file dev'essere verificata di quando in quando dall'amministratore di sistema ed esso, quando ritenuto non più necessario, può essere liberamente rimosso.
-    * 2: Log Giornale. Contiene le registrazioni delle operazioni più importanti come attivazione e spegnimento servizi, salvataggio documenti, esecuzione di operazioni di manutenzione ordinaria e straordinaria. Stila un file mensile denominato xw<annomese>.log non soggetto a rotazione.
-    * 3: Log della procedura di acquisizione pagine internet e documenti detta XCrossWay. Esso viene stilato dal modulo libxcrwl.dll. Come il log del server prevede la rotazione di un massimo di 5 files di 5Mb l'uno.
-Sono inoltre utilizzati:
-    * 7: File Conversion Agent.
-Per i log che gli utenti volessero realizzare in proprio, seguendo le specifiche del protocollo non documentate in questa sede, si suggerisce un valore minimo pari a 192.\\
-===== Configurazione per l'uso di XAM((Per xwls 1.4.0.77 o speriore)) =====
-In primo luogo è opportuno indicare cose si intende per XAM.\\
-XAM sta per eXtraWay Administration Monitor ed è uno strumento in grado di mostrare l'andamento delle attività del server e compiere statistiche su di esse, oltre ad offrire un valido ed importante supporto per il reparto tecnico al fine di identificare condizioni d'errore anche verificatesi molto tempo prima della loro ricerca.\\
-La logica con la quale eXtraWay Log Server dialoga con eXtraWay Administration Monitor è molto semplice. In sostanza esiste una directory concordata in cui xwls scrive dei files nei quali riporta una versione modificata delle registrazioni normalmente destinate al file xw.log, versione che viene data in pasto a XAM ad intervalli di tempo.
-Procediamo con ordine nel chiarire come.\\
-Nel file di configurazione di xwls trova ora posto anche la dichiarazione della directory condivisa. In essa xwls scrive un file xam.tmp. Quando il file contiene registrazioni la cui età supera una soglia definita sempre nel file di configurazione, il file viene chiuso, rinominato come xam- <timestamp>.log e ne viene creato un altro.\\
-La nuova denominazione del file fa sì che esso venga riconosciuto da XAM come file da consumare ed una volta acquisito il file viene rimosso.
-In questa sede non viene discussa la configurazione di XAM ma solo quella di xwls.\\
-Dal momento che nel file xam.tmp vengono registrati tutti i comandi e viene data loro evidenza, essi possono essere di due tipi: comandi stile HighWay e nuovi comandi XML stile eXtraWay. Per non correre rischi di sovrapposizione i primi hanno numerazione da 1 a 255 e gli altri una numerazione superiore.\\
-Sempre per poter dare particolare evidenza ai comandi è necessario che essi vengano opportunamente filtrati per quanto concerne il sub-comando.
-Per giungere alla piena comprensione di questo argomento sarebbe necessaria una conoscenza approfondita dell'operato del server eXtraWay e delle esigenze dello XAM, tutti obiettivi che questo documento non si prefigge. Ne consegue che ci si limiterà a dare evidenza di come vada configurato il file xwls.conf.xml perché il legame con lo XAM sia corretto.
-L'ipotesi è che la directory condivisa sia, come avviene solitamente negli scenari eXtraWay, una directory parallela a quella degli eseguibili.\\
-Il file di configurazione dichiara quindi dove si trova la directory e l'intervallo in minuti oltre il quale il file xam.tmp viene rinominato per essere messo a disposizione di XAM. Questo compito è svolto dagli attributi dir e lifetime. L'elemento preposto alla dichiarazione di questi parametri contiene altre indicazioni che xwls utilizzerà per dare a XAM informazioni coerenti. Come precedentemente annunciato non viene approfondito il significato di queste voci.
-<code>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<xwls_cfg>
-   ...
-   <xam dir="../xam" lifetime="5">
-      <cmd c="x46">1</cmd>
-      <cmd c="x102">1</cmd>
-      <cmd c="x103">x14</cmd>
-      <cmd c="x35">x13</cmd>
-      <cmd c="x38">x40</cmd>
-      <cmd c="x40">x1f</cmd>
-      <cmd c="xAD">xf</cmd>
-      <cmd c="x99">3</cmd>
-      <cmd c="x9A">2</cmd>
-      <cmd c="xA9">7</cmd>
-      <cmd c="xAC">7</cmd>
-      <cmd c="x108">xf</cmd>
-      <cmd c="x116">3</cmd>
-   </xam>
-</xwls_cfg>
-</code>
-L'esempio precedente indica che la directory si chiama xam e che il file xam.tmp in esso contenuto viene fatto ciclare ogni 5 minuti.
-__Nota:__ A differenza del comportamento solito, in cui i percorsi sono da considersi relativi alla directory degli eseguibili, in questo caso, e solo in questo, la directory di riferimento per esprimere un percorso relativo è la directory logs dove opera normalmente xwls.
-__Avvertimento:__ E' assolutamente inopportuno che la directory utilizzata per il dialogo col modulo XAM sia la stessa directory dei logs di eXtraWay.
-===== Considerazioni conclusive. =====
-La creazione di nuovi moduli nella piattaforma eXtraWay comporta che essi abbiano normalmente l'esigenza di produrre un log. Quando questo avviene, normalmente, eXtraWay Log Server viene modificato per prevedere un nuovo valore di default, corrispondente al numero di codice del log in esame.
-Configurare il file xwls.conf.xml, quindi, non serve se non per i seguenti casi:
-    * Uso di un modulo più recente della versione di xwls in esecuzione. In questo caso xwls non conosce ancora le impostazioni di default per questo tipo di modulo e produrrebbe un log senza una precisa denominazione.
-    * Implementazione di una procedura non appartenente alla piataforma eXtraWay o ad essa affiancata (come il text converter realizzato in Java) che voglia potersi avvalere del servizio offerto da eXtraWay Log Server.