Logging & Debugging
Relevant source files
The following files were used as context for generating this wiki page:
The Wikispeech server implements a centralized logging system and a suite of debugging tools to ensure operational transparency and facilitate troubleshooting across its distributed architecture. The system provides configurable log levels, multiple output targets, and automated startup tests to validate the health of connected microservices such as Lexicon and MaryTTS.
Sources: README.md:25-50, wikispeech_server/wikispeech.py:27-35
Logging Infrastructure
The logging system is built around a custom log.py module that provides standard logging levels: debug, info, warning, error, and fatal. The configuration is primarily managed through .conf files, allowing developers to set the verbosity and destination of log output.
Log Configuration Parameters
Configuration is handled in the [Server] section of the configuration files.
| Option | Description | Default/Possible Values |
|---|---|---|
log_level | Sets the minimum severity level for log messages. | info, debug, warning |
logger | Defines the output destination for logs. | stderr (default), stdout, syslog, <filename> |
flask_debug_mode | Enables automatic reloading of the Python Flask server upon file edits. | True, False |
Sources: wikispeech_server/default.conf:2-10, README.md:30-35
Data Flow for Log Initialization
The server initializes the logging environment by reading the configuration and applying the specified levels and handlers.
This diagram shows the sequence in which logging settings are applied during server startup.
Sources: wikispeech_server/wikispeech.py:27-40, wikispeech_server/default.conf:1-10
Debugging and Automated Testing
Wikispeech includes several mechanisms for debugging the server state and validating component integrations. This includes API endpoints for status checks and script-based integration tests.
Diagnostic API Endpoints
The server exposes specific endpoints to verify its version, status, and supported capabilities.
/ping: Returns "wikispeech" in plain text to verify server responsiveness./version: Provides build information, git tags, branch details, and the server start timestamp./options: Returns a JSON object describing available parameters for text-to-speech synthesis.
Sources: wikispeech_server/wikispeech.py:100-140, wikispeech_server/test_api.py:30-50
Startup and Unit Testing
The [Tests] configuration section controls how the server behaves regarding validation during initialization.
The logic for component loading and error handling during startup is governed by the configuration file.
Sources: wikispeech_server/default.conf:34-40, wikispeech_server/wikispeech.py:45-55
External Service Debugging
Because Wikispeech relies on microservices (MaryTTS, Lexicon, Mapper), log files for these sub-services are often redirected during startup for easier debugging. The start_wikispeech.sh script handles these redirections.
- Pronlex Log: Located at
$logdir/pronlex.log - Mapper Log: Located at
$logdir/mapper.log - Wikispeech Log: Located at
$logdir/wikispeech.log
Sources: start_wikispeech.sh:135-155
Implementation Details
The log.py module defines global methods used throughout the codebase to ensure consistent formatting.
# From wikispeech_server/wikispeech.py
log.info("\nOPUSENC\n\nChecking that opusenc is installed on your system..")
retval = os.system('opusenc -V')
if retval != 0:
log.error("ERROR: opusenc was not found.")
else:
log.info("opusenc found.\n")
Sources: wikispeech_server/wikispeech.py:65-75
Diagnostic Sequence for API Calls
When an API request fails, the server uses log traces to follow the processing through various adapters.
This sequence illustrates how log entries are generated at critical points in the request lifecycle to aid in pinpointing where a failure occurs.
Sources: wikispeech_server/wikispeech.py:200-220, wikispeech_server/adapters/piper_adapter.py:15-25
Conclusion
The logging and debugging system in the Wikispeech server is designed to be highly configurable, supporting everything from local development with flask_debug_mode to production environments utilizing syslog. By integrating automated startup tests and exposing diagnostic endpoints, the architecture ensures that developers can quickly identify configuration errors or service outages within the microservices ecosystem.
Sources: README.md:30-45, wikispeech_server/wikispeech.py:600-620