Commit 11f4484e authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

moved documentation to this places; added logrotate configuration;

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.
resolved template function resolution problem


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 3467
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent cf730233
# this is <DL1_logrotate.conf>
# ============================================================================
# config file for logrotate
# -------------------------
# $Id$
# ============================================================================
# This file should be installed in /etc/logrotate.d on OpenSuSE systems
# ============================================================================
#
# used by all syslog daemons
/var/log/dl1log /var/log/dl1logall {
compress
dateext
maxage 365
missingok
notifempty
size +4096k
create 644 root root
sharedscripts
postrotate
/etc/init.d/syslog reload
endscript
}
#
# ----- END OF DL1_logrotate.conf -----
% this is <DL1recording.tex>
% ----------------------------------------------------------------------------
% $Id: DL1recording.tex,v 1.12 2010/10/15 14:44:22 tforb Exp $
%
% Copyright (c) 2008 by Thomas Forbriger (BFO Schiltach)
%
% Recording data from the DL1 data logger
%
% REVISIONS and CHANGES
% 22/12/2008 V1.0 Thomas Forbriger
% 15/10/2010 V1.1 comment on message() versus match() filter in
% syslog-ng
%
% ============================================================================
%
\documentclass[twoside]{article}
%\usepackage{ngerman}
\usepackage{pslatex}
\usepackage{anysize}
\usepackage{amsmath}
%\usepackage[slantedgreek]{mathtime}
\usepackage{graphicx}
\usepackage{textfit}
\usepackage{fancyhdr}
\usepackage{pepigerm}
\usepackage{booktabs}
\usepackage{multicol}
\usepackage{verbatim}
\usepackage[bf,small]{caption}
\usepackage{xspace}
\bibliographystyle{pepigerm}
%----------------------------------------------------------------------
\newcommand{\mytitle}{Recording data from the Thies DL1 pluviometer}
%----------------------------------------------------------------------
\marginsize{2.5cm}{1.5cm}{1.5cm}{1.5cm}
\pagestyle{fancy}
\rhead[\mytitle]{\thepage}
\lhead[\thepage]{\mytitle}
\chead{}
\rfoot[Black Forest Observatory, \today]{Thomas Forbriger}
\lfoot[Thomas Forbriger]{Black Forest Observatory, \today}
\cfoot{}
\sloppy
\columnsep20pt
\parindent0pt
\parskip 10pt
%======================================================================
% macros
\newcommand{\DTDL}{Thies DL1 data logger}
\newcommand{\Dlaunchscript}{\texttt{launchDL1logger.sh}}
\newcommand{\Dlogscript}{\texttt{DL1logger.sh}}
\newcommand{\Dntpscript}{\texttt{ntpreport.sh}}
\newcommand{\DLdirect}{\texttt{DL1direct}}
\newcommand{\DLlogger}{\texttt{DL1logger}}
\newcommand{\Dloggerhost}{\textsc{netrunner}}
\newcommand{\DloggerhostIP}{\texttt{192.168.1.26}}
\newcommand{\Ddisplayhost}{\textsc{kubo}}
\newcommand{\DdisplayhostIP}{\texttt{192.168.1.33}}
\newcommand{\Dserialdevice}{\texttt{/dev/ttyUSB0}}
\newcommand{\Dloggeruser}{\texttt{dl1}}
\newcommand{\Dloggeruserhome}{\texttt{/home/dl1}}
\newcommand{\Dchannel}{\texttt{WR1}}
%======================================================================
\begin{document}
\mbox{ }\par
\vspace{-1.5cm}
%\hrule
\medskip
{\noindent\Large\textbf{\mytitle}\vspace{-14pt}\par}
%\smallskip\hrule
\rule{\textwidth}{0.5pt}
%\bigskip
\par
\vspace{-\parskip}
Technical Documentation
\hfill
\begin{raggedleft}
Thomas Forbriger\\
Black Forest Observatory (BFO)\\
Heubach 206,
D-77709 Wolfach\\
\vspace{3pt}
\today\ (\mbox{\texttt{$$Revision: 1.12 $$}})\par
\end{raggedleft}
\bigskip
\thispagestyle{plain}
%-------------------------------------------------------------
\begin{multicols}{2}
\parindent10pt
\parskip 0pt
\tableofcontents
%\listoftables
%\listoffigures
\parindent0pt
\parskip 10pt
%======================================================================
\section{Pluviometer data acquisition}
\subsection{Hardware components}
The rain gauge (a tiping bucket) in front of the BFO laboratory building
produces an eletrical pulse for each 0.1\,mm of precipitation.
These pulses are counted by a \DTDL.
The \DTDL\ maintains a data ring-buffer.
Its contents can be accessed through the local display, a memory card, or the
RS-232 serial port.
We use a Linux machine (\Dloggerhost) connected to the serial port to control
the \DTDL\ and to collect precipitation data.
\subsection{Data acquisition program}
Two programs are currently available to control the \DTDL.
They are \DLdirect\ (Section~\ref{sec:prog:dldirect}) and \DLlogger\
(Section~\ref{sec:prog:dllogger}).
The first supports manual control of the \DTDL\ and should not be used while
the second is in operation.
The second (\DLlogger) is the actual data acquisition program.
It controls the \DTDL, synchronizes its internal clock to the system clock of
the logger host (\Dloggerhost), and maintains an archive of data.
See Section~\ref{sec:prog:dllogger} for a detailed description in particular
for information on data sampling, poll cycles, message logging, and so on.
The data acquisition program (\DLlogger) is started from a shell script
(\Dlogscript, see Section~\ref{sec:prog:dlogscript}).
This shell script sets the correct values for the data directories, creates
them, and initializes the serial port prior to execution of \DLlogger.
The script \Dlogscript\ itself is executed from the launch-script
\Dlaunchscript\ (see Section~\ref{sec:prog:dlaunchscript}).
The latter first checks whether an instance of the logger is in operation.
If not, the logger is executed in background operation mode.
The launch-script \Dlaunchscript\ should be executed periodically by the cron
deamon.
See Section~\ref{sec:conf:crontab:logger} for an example of an entry in the
crontab.
This ensures that the data acquisition is resumed automatically upon
unexpected termination of the acquisition program.
\subsection{Diagnostics}
The data acquisition program writes its diagnostic messages to the system's
syslog facility.
The messages are tagged \DLlogger.
See Section~\ref{sec:prog:dllogger} for information on log levels used for
different diagnostic messages.
A simple configuration that maintains local publically readable log files
is given in Section~\ref{sec:conf:syslog:logger}.
This configuration also sends messages to a second system for monitoring
purposes.
Two files are maintained.
One contains all messages that are tagged \DLlogger.
These messages comprise alos purely informational messages that are issued in
each poll cycle to indicate the activity of \DLlogger.
This log stream is also exported to the display host \Ddisplayhost\ for
monitoring purposes.
A second log file contains only messages with level notice and higher (all
levels except level info).
This log file is meant to be archived together with the data to support error
analysis.
Log messages with tag \DLlogger\ are excluded from the usual system log.
\subsection{Data archive}
The data archive maintained by \DLlogger\ contains two types of data files.
The first are called dump-files and are simply literal copies of the data
received from the \DTDL\ together with some diagnostics.
The second kind of data files uses GSE format, contains diagnostics too and
is ready to be processed by plotting facilities.
The GSE data contains data in counts, not mm.
Both data archives contain files for completed days that provide the date in
the file name (as well as in the file's header).
The current data for uncompleted days is stored in files called
\texttt{active.asc} and \texttt{active.gse} for the dump and the GSE data
respectively.
The latter are updated in periodic poll intervals.
The data archive can be provided to other hosts via network file system (NFS).
An example export entry is provided in Section~\ref{sec:conf:exports:logger}.
The sampling interval provided in the GSE data files is not exact, since GSE
specifies a data rate rather than an interval.
See Section~\ref{sec:prog:dllogger} for further comments.
\subsection{Timing}
Once a day the data logger \DLlogger\ synchronizes the \DTDL\ to the system
clock of \Dloggerhost.
See Section~\ref{sec:prog:dllogger} for further comments on timing accuracy.
The system clock of \Dloggerhost\ must by disciplined by NTP (network time
protocol).
To support easy monitoring of the systems state of health a shell script
\Dntpscript\ (Section~\ref{sec:prog:dlntpscript}) is executed once a day by
the cron deamon (see Section~\ref{sec:conf:crontab:logger}).
This script polls the state of NTP peers and writes it to the system log
stream with tag \DLlogger.
The system's time zone is selected to be UTC.
This way the time stamps in the system's log files are synchronous with the
times provided in the messages from \DLlogger.
\subsection{Data acquisition account}
The logger program \DLlogger\ runs in userspace of user \Dloggeruser\ on
\Dloggerhost.
The home directory of \Dloggeruser\ is \Dloggeruserhome.
Binaries \DLlogger\ and \DLdirect\ are installed in
\Dloggeruserhome\texttt{/bin/linux}.
Shell scripts \Dlogscript, \Dlaunchscript, and \Dntpscript\ are installed in
\Dloggeruserhome\texttt{/bin/scripts}.
The \DLlogger\ memory file, the data files, and logs of the launch script go
to \Dloggeruserhome\texttt{/data/DL1} and subdirectories therein.
\subsection{Data stream}
\DLlogger\ uses the following identifiers for the data steam in GSE files:
\vspace{-12pt}
\begin{description}
\parskip0pt
\itemsep0pt
\item[channel:] \Dchannel
\item[station:] is read from \DTDL
\item[instype:] is read from \DTDL
\end{description}
The channel ID is defined according to the SEED reference manual (Appendix~A):
\vspace{-12pt}
\begin{description}
\parskip0pt
\itemsep0pt
\item[Band code W:] Weather/Environmental
\item[Instrument Code R:] Rainfall
\item[Orientation Code:] unkown
\end{description}
%----------------------------------------------------------------------
\section{Data monitoring}
A second host (\Ddisplayhost) may be used for the purpose of monitoring, data
quality control, and data backup.
Data are made available through an NFS mount
(Section~\ref{sec:conf:fstab:display}).
Log messages are made available through syslog in a local file
(Section~\ref{sec:conf:syslog:display}).
\subsection{Data graph monitor}
The data files are made available through NFS.
The processing and plotting mechanism is described elsewhere in a difference
document.
\subsection{Data file monitor}
For calibration purposes in particular a direct display of the current data
file can be useful.
The file can be displayed in a local terminal window by using the command
\begin{quote}
\texttt{less /data/DL1/dump/active.asc}
\end{quote}
The display will be updated upon pressing the \texttt{R}-key.
\subsection{Message file monitor}
A permanent display of diagnostic messages can be maintained in a local
terminal window by the command
\begin{quote}
\texttt{less /var/log/dl1log}
\end{quote}
Pressing the \texttt{F}-key will activate automatic updates of the displayed
contents.
To use the file content navigation facilities of \texttt{less} press
\texttt{Ctrl-C}.
To return to automatic updates press the \texttt{F}-key again.
%----------------------------------------------------------------------
\end{multicols}
\pagebreak
%======================================================================
\appendix
\section{Configuration}
\subsection{\texttt{crontab} on \Dloggerhost}
\label{sec:conf:crontab:logger}
\begin{verbatim}
# this is <crontab>
# ============================================================================
# crontab for netrunner
# ---------------------
#
10 * * * * /home/dl1/bin/scripts/launchDL1logger.sh 1>>/dev/null 2>&1
50 0 * * * /home/dl1/bin/scripts/ntpreport.sh 1>>/dev/null 2>&1
# ----- END OF crontab -----
\end{verbatim}
%----------------------------------------------------------------------
\subsection{\texttt{/etc/exports} on \Dloggerhost}
\label{sec:conf:exports:logger}
\begin{verbatim}
[...]
/home/dl1/data/DL1 *(ro,root_squash,sync,no_subtree_check)
[...]
\end{verbatim}
%----------------------------------------------------------------------
\subsection{\texttt{/etc/fstab} on \Ddisplayhost}
\label{sec:conf:fstab:display}
\begin{verbatim}
[...]
netrunner:/home/dl1/data/DL1 /data/DL1 nfs defaults,auto,ro 0 0
[...]
\end{verbatim}
%----------------------------------------------------------------------
\subsection{\texttt{/etc/syslog-ng/syslog-ng.conf} on \Dloggerhost}
\label{sec:conf:syslog:logger}
The following excerpt is from the syslog configuration file on the logger host
\Dloggerhost.
The messages from the data acquisition program are written to a local file and
to a second host (the display host \Ddisplayhost) via TCP.
Two local files are maintained.
One of them collects all messages while the other only collects messages that
are not at level info.
\begin{verbatim}
[...]
# BFO Thies DL1
destination dl1logall { file("/var/log/dl1logall" fsync(yes) perm(0644)); };
destination dl1log { file("/var/log/dl1log" fsync(yes) perm(0644)); };
destination dl1loghugoiv { tcp("192.168.1.27" port(2222)); };
filter f_dl1 { match('^DL1logger'); };
filter f_dl1_notice { match('^DL1logger') and not level(info); };
log { source(src); filter(f_dl1); destination(dl1logall); };
log { source(src); filter(f_dl1_notice); destination(dl1log); };
log { source(src); filter(f_dl1); destination(dl1loghugoiv); };
[...]
\end{verbatim}
The following definition keeps the \DLlogger\ diagnostics away from the system
log.
\begin{verbatim}
[...]
filter f_messages { not facility(news, mail) and not filter(f_iptables)
and not filter(f_dl1); };
[...]
\end{verbatim}
%----------------------------------------------------------------------
\subsection{\texttt{/etc/syslog-ng/syslog-ng.conf} on \Ddisplayhost}
\label{sec:conf:syslog:display}
On the display host \Ddisplayhost\ the messages from the data acquisition
software are received via TCP and syslog.
They are stored in local files with global read permissions.
\begin{verbatim}
[...]
# BFO Thies DL1
destination dl1log { file("/var/log/dl1log" fsync(yes) perm(0644)); };
destination dl1logall { file("/var/log/dl1logall" fsync(yes) perm(0644)); };
source vesuv { tcp(port(2222)); };
filter f_dl1 { match('^DL1logger'); };
filter f_dl1_notice { match('^DL1logger') and not level(info); };
log { source(vesuv); filter(f_dl1); destination(dl1logall); };
log { source(vesuv); filter(f_dl1_notice); destination(dl1log); };
[...]
\end{verbatim}
With newer versions of \texttt{syslog-ng} you have to use
\begin{verbatim}
[...]
# BFO Thies DL1
destination dl1log { file("/var/log/dl1log" fsync(yes) perm(0644)); };
destination dl1logall { file("/var/log/dl1logall" fsync(yes) perm(0644)); };
source DL1 { tcp(port(2222)); };
filter f_dl1 { match('^DL1logger' value(MSGHDR)); };
filter f_dl1_notice { match('^DL1logger' value(MSGHDR)) and not level(info); };
log { source(DL1); filter(f_dl1); destination(dl1logall); };
log { source(DL1); filter(f_dl1_notice); destination(dl1log); };
[...]
\end{verbatim}
%----------------------------------------------------------------------
\section{Programs}
Source code is is not documented here.
You can find the source documentation at
\begin{quote}
\verb+http://www-gpi.physik.uni-karlsruhe.de/pub/forbriger/txt/mycode.html+
\end{quote}
There you will find a documentation for the DL1 software as well as a small
library for serial port access.
Use the instructive source code of well performing software to understand how
the \DTDL\ should be controlled via a serial line RS232 connection.
\subsection{\DLdirect}
\label{sec:prog:dldirect}
The program \DLdirect\ supports manual communication with the \DTDL.
Upon invocation it sends one command and displays the response on standard
output.
It might be unwise to use \DLdirect\ while an instance of \DLlogger\ is in
operation on the same serial port.
\verbatiminput{DL1direct.xxx}
%----------------------------------------------------------------------
\subsection{\DLlogger}
\label{sec:prog:dllogger}
The program \DLlogger\ is the actual data acquisition program.
\verbatiminput{DL1logger.xxx}
%----------------------------------------------------------------------
\subsection{\Dlogscript}
\label{sec:prog:dlogscript}
\verbatiminput{DL1logscript.xxx}
%----------------------------------------------------------------------
\subsection{\Dlaunchscript}
\label{sec:prog:dlaunchscript}
\verbatiminput{DL1launchscript.xxx}
%----------------------------------------------------------------------
\subsection{\Dntpscript}
\label{sec:prog:dlntpscript}
\verbatiminput{DL1ntpscript.xxx}
%----------------------------------------------------------------------
\end{document}
% ----- END OF DL1recording.tex -----
......@@ -37,7 +37,7 @@ SUBOBS=$(patsubst %.cc,%.o,$(SUBSRC))
all: DL1logger DL1direct
flist: Makefile $(wildcard *.cc *.h *.cfg *.sh) README
flist: Makefile $(wildcard *.cc *.h *.cfg *.sh *.tex *.conf) README
echo $^ | tr ' ' '\n' | sort > $@
.PHONY: edit
......@@ -56,7 +56,7 @@ CPPFLAGS=-I$(LOCINCLUDEDIR) $(FLAGS)
#----------------------------------------------------------------------
cvsids.xxx: $(wildcard *.cc *.h)
cvsids.xxx: $(filter-out cvsids.cc,$(wildcard *.cc *.h))
ident $^ | egrep '^ *\$$Id:' | sort | uniq | \
awk 'BEGIN{ print "const char* const CVSIDS[]={"; } \
{ print "\"" $$0 "\","; } \
......@@ -106,4 +106,34 @@ tester DL1direct DL1logger: %: %.o $(SUBOBS)
-L$(LOCLIBDIR)
/bin/mv -fv $@ $(LOCBINDIR)
#======================================================================
# documentation
# -------------
DL1logger.xxx: ; /bin/bash -c "DL1logger -help 2>&1" > $@
DL1direct.xxx: ; /bin/bash -c "DL1direct -help 2>&1" > $@
DL1work=$(HOME)/work/src/conv/ThiesDL1
DL1logscript=$(DL1work)/DL1logger.sh
DL1logscript.xxx: $(DL1logscript); /bin/cp -vpd $< $@
DL1launchscript=$(DL1work)/launchDL1logger.sh
DL1launchscript.xxx: $(DL1launchscript); /bin/cp -vpd $< $@
DL1ntpscript=$(DL1work)/ntpreport.sh
DL1ntpscript.xxx: $(DL1ntpscript); /bin/cp -vpd $< $@
DL1recording.tex: DL1logger.xxx DL1direct.xxx DL1logscript.xxx \
DL1launchscript.xxx DL1ntpscript.xxx
$(patsubst %.tex,%,$(wildcard *.tex)): %: %.dvi
%.eps: %.ps; ps2epsi $< $@
%.pdf: %.eps; epstopdf $<
%.dvi: %.tex; latex $(patsubst %.tex,%,$<)
%.ps: %.dvi; dvips -ta4 $(patsubst %.dvi,%,$<)
%.pdf: %.tex; pdflatex $(patsubst %.tex,%,$<)
%.x: %.dvi; xdvi $(patsubst %.dvi,%,$<) &
%.psp: %.ps; gv $<
%.pdp: %.pdf; acroread $<
# ----- END OF Makefile -----
......@@ -31,11 +31,12 @@
* REVISIONS and CHANGES
* - 27/11/2008 V1.0 Thomas Forbriger
* - 22/12/2008 V1.1 pass records log messages to data file
* - 25/11/2010 V1.2 g++ was not able to resolve template function split
*
* ============================================================================
*/
#define DL_FUNCTIONS_CC_VERSION \
"DL_FUNCTIONS_CC V1.1"
"DL_FUNCTIONS_CC V1.2"
#define DL_FUNCTIONS_CC_CVSID \
"$Id$"
......@@ -56,8 +57,8 @@ namespace dl1 {
const int longtimeout=90;
const int cmaxretries=3;
extern const libtime::TRelativeTime oneday(1);
extern const libtime::TRelativeTime twominutes(0,0,2);
const libtime::TRelativeTime oneday(1);
const libtime::TRelativeTime twominutes(0,0,2);
typedef sff::SFFostream<ts::TIsfftimeseries::Tseries> TIostream;
......@@ -76,9 +77,14 @@ namespace dl1 {
Tlistofstring listofstring(const std::ostringstream& oss,
const std::string& eol)
{
Tlistofstring los;
tfxx::string::gen_split(los, oss.str(), eol, true);
return(los);
/*
std::string msg(oss.str());
Tlistofstring v=tfxx::string::split<std::list>(msg, eol, true);
Tlistofstring v=::tfxx::string::split<std::list>(msg, eol, true);
return(v);
*/
} // Tlistofstring listofstring(const std::ostringstream& oss,
// const std::string& eol)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment