7.0.0

# Help! I’m stuck! Now what?

You will …

- Troubleshoot and resolve problems with SeisComP

Pre-requisites for this tutorial:

- Have your SeisComP installation and configuration available

Afterwards/Results/Outcomes:

- Improved understanding of ways to solve issues when operating SeisComP

Time range estimate:

- 30 minutes

## Outline

Inevitably you will encounter difficulties using SeisComP. This tutorial reviews a few ways to diagnose your problems and get help to resolve them:

- Detailed HTML documentation

- Commandline help

- The SeisComP Forum

- Reviewing logging options

- The debugging options

- Commercial support

## Ways to diagnose and to get help

### HTML documentation

Most modules have HTML documentation. When installed, it can be found in scconfig under Docs. The HTML documentation can also be reached from the Help menu of all GUIs. It contains the description of configuration and command-line parameters along with an overview with many detailed information.

scmv with access to the HTML documentation.

The description of most configuration parameters is also available from within scconfig. Look under Modules, and choose the relevant module. For each parameter, the first few lines of description are shown; hovering over these reveals the full text.

The HTML documentation is built regularly and available online, e.g. gempa’s documentation.

### Commandline help

In addition to the HTML documentation, many SeisComP commands have manual pages which can be read on the command line:

    $ man [module name]

and help on command-line options:

    $ [module name] -h

Note

The command-line option -h can be used with almost all modules. No matter how many other command-line parameters were given, -h will stop the module and print the help on the command-line.

### Configuration parameters

The scconfig GUI tool can be conveniently used to adjust the module and bindings configuration. It also displays help on each individual configuration parameter for every module. Read the concepts section on configuration for a comprehensive overview.

Tool tips provide information on parameters.

scconfig evaluates the syntax of input values.

### Command-line parameters

Command-line parameters provide additional flexibility when executing modules. To learn about them read the HTML documentation or execute

    $ [module name] -h

### The SeisComP Forum

The SeisComP forum [26].

The SeisComP forum [26] is the place to discuss SeisComP. Announcements about updates, training courses and more are posted here by the developers, and users can post questions or discuss new developments. Anyone can browse the forum, while registration is required to post there.

If you have specific technical problems, it helps to have tried some of the ideas below. Please include version information (the ‘-V’ option described below) if you report a problem.

### Logging

Most SeisComP applications use a standard logging approach. By default, they log to files in your `~/.seiscomp/log` directory, such as `scamp.log`. Further options for logging are described in Configuration.

You can control how often these are rotated (old log files are closed, and moved to a new file name, such as scamp.log.1, e.g. daily). Alternatively you can use the system-wide logging facility syslog and send logs to /var/log or another “standard” place.

There are four levels of severity of SeisComP log messages, and applications can be configured to show only those which are more severe than a given threshold.

- 1 = ERROR

- 2 = WARNING

- 3 = INFO

- 4 = DEBUG.

Default is 2. Setting logging.level = 4 results in the most messages.

For other modules such as seedlink, the log files are written to `seiscomp/var/log/`

### Debugging options

Most SeisComP applications support two important command line options:

- Use –console to send output to the terminal instead of the usual log location.

- -v for increased verbosity, or use –verbosity= n where n is one of the four severity levels above.

In addition:

- –debug sets logging.level (see above) to 4 (DEBUG), and sends logging output to the console (terminal) instead of the usual log location. (This is just an easier way of specifying –verbosity=4 –console=1.) For example:

      $ ~/seiscomp/bin/seiscomp exec scmag --debug
      11:47:50 [debug] Adding plugin path: .
      11:47:50 [debug] Adding plugin path: /home/user/.seiscomp/plugins
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib/plugins
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/share/plugins
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
      11:47:50 [debug] Adding plugin path: /home/user/seiscomp/share/plugins/scmag
      11:47:50 [debug] Trying to open plugin at /home/user/seiscomp/share/plugins/dbmysql.so
      11:47:50 [info] Plugin dbmysql registered
      11:47:50 [info]
      Plugins:
      --------
       [1]
        description: MySQL database driver
             author: GFZ Potsdam <seiscomp-devel@gfz-potsdam.de>
            version: 0.9.2
                API: 12.1.0

      11:47:50 [info] Connect to messaging
      11:47:50 [debug] Trying to connect to scmag@localhost with primary group = MAGNITUDE
      11:47:50 [info] Connecting to server: localhost
      11:47:50 [info] Connected to message server: localhost
      11:47:50 [info] Joining MASTER_GROUP group
      11:47:50 [info] Sending connect message to server: localhost
      11:47:51 [info] Server version is 'Jakarta 2018.327.p15'
      11:47:51 [info] Outgoing messages are encoded to match schema version 0.11
      11:47:51 [info] user "scmag" connected successfully to localhost

  The above reveals that scmag was able to load, and connect to the messaging system. Note that the verbosity of each message (“info”, “debug”, etc) is also shown. However a moment later we see:

      11:47:51 [info] Connect to database
      11:47:51 [debug] skipping unknown network message
      11:47:51 [debug] skipping unknown network message
      11:47:51 [debug] skipping unknown network message
      11:47:56 [error] Timeout while waiting for database provide message
      11:47:56 [debug] Leaving ::done
      11:47:56 [info] Shutting down MagTool
      - database accesses while runtime: 0

  This suggests that scmaster was not running to provide a connection to the database. To resolve this, you could next check that scmaster is running as expected.

Note

Instead of –debug in the example above, you could run

    $ ~/seiscomp/bin/seiscomp exec scmag -vvvv

The output is the same, but it is sent to your normal logging file, typically ~/.seiscomp/log/scmag.log.

In scconfig, logging can be set globally. Go to the Modules tab, then System > global (see “logging”) or per module.

e.g. set “logging.level = 3” in $SEISCOMP_ROOT/etc/scamp.log to set level to INFO only for scamp.

You should also be aware of the version of SeisComP that you are running. The ‘-V’ or ‘–version’ option provides this for many SeisComP modules.

    $ ~/seiscomp3/bin/seiscomp exec scmag -V
    scmag: Jakarta 2018.327.p15
    API version: 12.1.0
    GIT HEAD:
    Compiler: c++ (Ubuntu 7.3.0-16ubuntu3) 7.3.0
    Build system: Linux 4.15.0-20-generic
    OS: Ubuntu 18.04 LTS / Linux

### Commercial support

Professional commercial support to SeisComP users is available from gempa GmbH [31].

## Next time you have a problem

- Try some of the above techniques.

- If you find a solution, don’t forget to share it at the SeisComP forum [26].