gempa GmbH

Table Of Contents

This Page

eqevents

Static event website generator

Description

EQEvents is a static website generator for SeisComP3 XML event parameters. It can run in a spooler mode or process single files. It uses an template engine to create the HTML files. It features an index page and event detail page. More information can be added though Plug-ins.

EQEvents is meant to run as output service for GDS (gempa dissemination server).

Plug-ins

The different EQEvents features are implemented by various plug-ins which may be activated by adding a plug-in to the list of processingPlugins, e.g. browser,kml,leaflet,plots,gds,gis,rss,search,.

The following plug-ins exist:

Name Description
browser Adds a calendar based event browser.
gds Updates gempa dissemination server (GDS) database with event processing information.
gis Generates a map using gempa image server (GIS) which is much faster than running e.g. scmapcut which needs to generate the map tree at each start again.
kml Generate output in KML format.
leaflet Generates a dynamic map from many earthquakes.
plots Adds distance, azimuth, and polar plot to event detail page.
rss Creates a RSS feet user may subscribe to.
search Adds an event search. Note: The search function is implemented as a WSGI script and needs additional installation steps, described in Dynamic Content - The Search Plug-in.

System dependencies which may be required by the plug-ins:

  • python-matplotlib
  • python-jinja2

Processing

Offline

To process a single XML file run EQEvents and pass it an XML file:

eqevents -i event.xml --debug

Spooler

The default mode is the spooler mode. EQEvents runs in the background and monitors a spooler directory for new files. It will then process all files with the naming convention [prefix]-[transaction-id]-[event-id].xml. Each file touched is deleted either after processing or due to wrong filename format.

Reprocessing

If a template was changed or new plug-ins have been added all static pages need to be reprocessed. As a precondition for this the event XML data must be available, see backupXML.

To initiate reprocessing stop EQEvents and run it using the reprocess command-line option.

eqevents --reprocess

Templates

EQEvents uses templates in a well defined structure. The path to the template directory can be configured with templateDirectory. The structure is as follows:

base.html Base template inherited by all other templates
table.html Template to render event list tables
index.html The index template
search.html The search template
results.html The template of the search result list
event/base.html The base template for event details
event/overview.html The template of the overview of event details
event/quality.html The template of the event quality
event/arrivals.html The template of the event arrival list
browser/index.html The browser index template
browser/year.html The browser template showing all years
browser/month.html The browser template for one year
browser/day.html The browser template for one day

Template are processed by Python Jinja and follow its documented syntax. Each templates receives a context with several variables defined.

ep

The EventParameters structure parsed from XML converted to a Python object. Attributes are accessible following the SeisComP3 ML schema names. They are mapped directly from the XML tag/attribute names. Below a simple example how to access all picks in the EventParameters object in template syntax:

{% for p in ep.pick %}
{{ p.waveformID.networkCode }}.{{ p.waveformID.stationCode }} {{ p.time.value|qmldate|date }}
{% endfor %}

The special filter qmldate is a special filter added by EQEvents to convert a date string from SeisComP3 ML to an Python datetime object. That object can then be further processed with the Jinja date filter.

event

The event object currently processed.

origin

The preferred origin of the currently processed event.

focalMechanism

The preferred focal mechanism of the currently processed event.

magnitude

The preferred magnitude of the currently processed event.

POOL

The POOL that maps a publicID to an object.

{% for arr in origin.arrival %}
{% p = POOL[arr.pickID] %}
{% if p %}
<div>{{ p.time.value|qmldate|data }}</div>
{% else %}
<div class="error">Referenced pick {{ arr.pickID }} not available</div>
{% endif %}
{% endfor %}

This makes it easier to access referenced objects. Otherwise the template code must iterate over all pick objects and compare the publicID in combination with a linear search which is quite slow for larger events.

ID

The current event ID after cleaning invalid characters. That ID is used as event folder name and all event ID depending filenames.

settings

The global settings object.

ROOT_URL

The relative path to the site index file. This can be different according to the templates rendered. If paths are required this variable should be prepended.

<a href="{{ ROOT_URL }}index.html">Home</a>
STATIC_URL

The path to the static files according to staticURL.

<link rel="stylesheet" type="text/css" href="{{ STATIC_URL }}css/page.css">

Webpages

The following images show the different generated pages with the default templates.

_images/index.png

Index page

_images/event-overview.png

Event overview

_images/event-arrivals.png

Event arrivals

_images/event-quality.png

Event quality

_images/browser.png

Browser index

_images/browser-year.png

Browser page for one year

_images/browser-month.png

Browser page for one month

_images/browser-day.png

Browser page for one day

_images/search.png

Search page

Apache Integration

Since EQEvents by default only consists of static pages the Apache integration is straight forward. You may either decide to

  1. generate the pages directly into the www directory by setting outputDirectory to e.g. /var/www/html/eqevents or
  2. you use a softlink to point Apache to the default EQEvents output directory:
ln -s /home/sysop/seiscomp3/var/lib/eqevents/pages /var/www/html/eqevents

In case of (1.) make sure that the EQEvents system user, probably sysop, is allowed to write to the www directory. In case of (2.) the x access right must be set for Apache group and for all directories on the path. Also security modules like SELinux might prevent access of the Apache process to the user directory. If this is the case use following command to grant those access rights:

chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/etc/global.cfg
chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/etc/eqevents.cfg
chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/etc/defaults/global.cfg
chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/etc/defaults/eqevents.cfg
chcon -Rv --type=httpd_sys_content_t /home/sysop/seiscomp3/var/lib/eqevents/pages
chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/var/lib/eqevents/eqevents.db
chcon -Rv --type=httpd_sys_content_t /home/sysop/seiscomp3/share/eqevents/templates
chcon -v --type=httpd_sys_content_t /home/sysop/seiscomp3/share/eqevents/search-wsgi.py
chcon -Rv --type=texrel_shlib_ti /home/sysop/seiscomp3/lib
#setsebool -P httpd_read_user_content 1

Dynamic Content - The Search Plug-in

The search plug-in requires Apaches WSGI module to generate dynamic content.

  1. Add the search plug-in to processingPlugins.
  2. Install and enable mod_wsgi
a2enmod wsgi
  1. Configure WSGI handler, e.g. in /etc/apache2/sites-available/eqevents.conf
WSGIScriptAlias /eqevents/search /home/sysop/seiscomp3/share/eqevents/search-wsgi.py
WSGIPythonPath /home/sysop/seiscomp3/lib/python
WSGIDaemonProcess eqevents processes=2 threads=1 python-path=/home/sysop/seiscomp3/lib/python
WSGIProcessGroup eqevents
  1. Configure access to static content (optional, same file as above)
<Location "/eqevents">
  Options -Indexes
  SetHandler None
  Require all granted
</Location>
  1. Set environment variables

Ubuntu: /etc/apache2/envvars

export LD_LIBRARY_PATH=/home/sysop/seiscomp3/lib:$LD_LIBRARY_PATH
export SEISCOMP_ROOT=/home/sysop/seiscomp3

CentOS: /etc/sysconfig/httpd

LD_LIBRARY_PATH=/home/sysop/seiscomp3/lib:$LD_LIBRARY_PATH
SEISCOMP_ROOT=/home/sysop/seiscomp3
  1. Enable site
a2ensite eqevents
  1. Restart Apache

Configuration

etc/defaults/global.cfg
etc/defaults/eqevents.cfg
etc/global.cfg
etc/eqevents.cfg
~/.seiscomp3/global.cfg
~/.seiscomp3/eqevents.cfg

eqevents inherits global options.

templateDirectory

Type: path

Directory to read templates from. Default is @DATADIR@/eqevents/templates/default.

outputDirectory

Type: path

Target directory for generated web pages. Default is @ROOTDIR@/var/lib/eqevents/pages.

spoolerDirectory

Type: path

Spooler directory to read content files from. Default is @ROOTDIR@/var/lib/eqevents/spool.

spoolerInterval

Type: int

Unit: s

Polling interval in seconds the spooler will scan the service directory for new files. Default is 10.

backupXML

Type: boolean

Defines whether to backup the input XML in the output HTML directory per event as [id].xml. The XML backup allows easy reprocessing of the Web page in case of template changes, see '--reprocess' command line option. Default is false.

staticURL

Type: string

URL prefix for static files used in the templates. Can be used as {{ STATIC_URL }} in templates. Default is static/.

enableArrivals

Type: boolean

Enables arrival output as part of the event webpage. Default is true.

numberOfIndexEvents

Type: int

Number of events for the index page. Default is 50.

maxDays

Type: int

Maximum number of days to keep events for. Older events are removed. A value of 0 or below means unlimited. Default is 0.

ignoreType

Type: boolean

An event might be marked as fake event using the event type 'not existing' or 'other'. Set this parameter to 'true' to process fake events respectively to prevent them from being deleted. Default is false.

ignoreMatch

Type: boolean

The GDS uses the 'match' flag to signal whether an event solution fulfilled the dissemination criteria. E.g. an updated event revision might correct the epicenter to a point outside the area of interest. Set this parameter to 'true' to process not matching events respectively to prevent them from being deleted. Default is false.

processingPlugins

Type: list:string

List of active eqevents plugins. Default is browser, plots.

Note

gds.* Configuration parameters of the GDS plugin to generate gds reports. To use that plugin, add "gds" to the list of processing plugins.

gds.db

Type: string

Path to the GDS database.

Note

gis.* Configuration parameters of the GIS plugin to generate map files. To use that plugin, add "gis" to the list of processing plugins.

gis.url

Type: string

URL of the GIS RESTful API, e.g. http://localhost:20001.

gis.timeout

Type: int

Defines the timeout for GIS requests. If the timeout expires and GIS did not return an empty image is generated. Default is 5.

gis.post

Type: boolean

By default the image is requested from the GIS using the HTTP-GET mothod along with key event parameters. If set to 'true' the HTTP-POST method is used instead to transfer the whole event XML. This allows the GIS to render an image with even more information, like used stations or moment tensor solutions. Default is false.

Note

rss.* Configuration parameters of the RSS plugin. To use that plugin, add "rss" to the list of processing plugins.

rss.days

Type: int

Number of (last) days to generate the RSS feed for. Default is 1.

rss.title

Type: string

Number of (last) days to generate the RSS feed for. The variable "days" is replaced by the string containing the number of days configured, e.g. "2 days". Default is EQ Events RSS Channel - last ${days}.

rss.desc

Type: string

Description of RSS feed that is copied to the description tag of the RSS XML. Default is Real-time earthquake locations.

Type: string

URL prefix for each event detail page. eqevents just deals with relative paths but to transform an RSS item link into an absolute URL this prefix is required.

Note

notification.* Configuration parameters of the NOTIFICATION plugin to send notifications to a socket.io-server. To use that plugin, add "notification" to the list of processing plugins.

notification.server

Type: string

Server-URL of the socket.io server e.g. http://localhost.

notification.port

Type: int

Defines the server port. Default is 80.

notification.namespace

Type: string

By default the client sends the messages to the namespace '/events'. Default is /event.

Note

leaflet.* Configuration parameters for the Leaflet map plugin that renders an interactive map on the index page.

leaflet.init.lat

Type: double

Unit: degrees

Initial latitude to center the map view. Default is 53.

leaflet.init.lon

Type: double

Unit: degrees

Initial longitude to center the map view. Default is 13.

leaflet.init.zoom

Type: int

Initial zoom level for the map view. Default is 4.

Note

search.* The search plugin provides a page to configure a search filter.

search.distanceUnit

Type: string

Configures the unit used for the radius of the circular region filter. This can either be "km" or "mi". 1 mile is assumed to be 1.609344 kilometers. Default is km.

Command-line

Generic

-h, --help

show help message.

-V, --version

show version information

--config-file arg

Use alternative configuration file. When this option is used the loading of all stages is disabled. Only the given configuration file is parsed and used. To use another name for the configuration create a symbolic link of the application or copy it, eg scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

Run as daemon. This means the application will fork itself and doesn't need to be started with &.

Verbosity

--verbosity arg

Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug

-v, --v

Increase verbosity level (may be repeated, eg. -vv)

-q, --quiet

Quiet mode: no logging output

--print-component arg

For each log entry print the component right after the log level. By default the component output is enabled for file output but disabled for console output.

--component arg

Limits the logging to a certain component. This option can be given more than once.

-s, --syslog

Use syslog logging back end. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Debug mode: --verbosity=4 --console=1

--trace

Trace mode: --verbosity=4 --console=1 --print-component=1 --print-context=1

--log-file arg

Use alternative log file.

EQEvents

-i, --input string

Input file to be processed immediately. EQEvents will not change into spooler mode after processing this file.