enable NSQ log aggregation (close #218)

README.md

@@ -61,7 +61,8 @@ gnparser -h
   * [R language package](#r-language-package)
   * [Ruby Gem](#ruby-gem)
   * [Node.js](#nodejs)
-  * [Usage as a REST API Interface](#usage-as-a-rest-api-interface)
+  * [Usage as a REST API Interface or Web-based User Graphical Interface](#usage-as-a-rest-api-interface-or-web-based-user-graphical-interface)
+    * [Enabling logs for GNparser's web-service](#enabling-logs-for-gnparsers-web-service)
   * [Use as a Docker image](#use-as-a-docker-image)
   * [Use as a library in Go](#use-as-a-library-in-go)
   * [Use as a shared C library](#use-as-a-shared-c-library)
@@ -353,7 +354,7 @@ Relevant flags:
 This flag is ignored if parsing mode is set to streaming with ``-s`` flag.
 
 ``--cultivars -C``
-: Adds support for botanical cultivars like ``Sarracenia flava 'Maxima'`` 
+: Adds support for botanical cultivars like ``Sarracenia flava 'Maxima'``
 and graft-chimaeras like ``+ Crataegomespilus``
 
 ``--capitalize -c``
@@ -385,6 +386,15 @@ performance.
 ``--port -p``
 : set a port to run web-interface and [RESTful API][OpenAPI].
 
+`` --web-logs``
+: requires `--port`. Enables output of logs for web-services.
+
+`` --nsqd-tcp``
+: requires `--port`. Allows to redirect web-service log output to [NSQ]
+  messaging server's TCP-based endpoint. It is handy for aggregations of logs
+  from GNparser web-services running inside of Docker containers or
+  in Kubernetes pods.
+
 ``--stream -s``
 : ``GNparser`` can be used from any language using pipe-in/pipe-out of the
 command line application. This approach requires sending 1 name at a time
@@ -509,7 +519,7 @@ uses C-binding and does not require an installed `gnparser` app.
 @tobymarsden created a [wrapper for node.js][node-gnparser]. It uses C-binding
 and does not require an installed `gnparser` app.
 
-### Usage as a REST API Interface
+### Usage as a REST API Interface or Web-based User Graphical Interface
 
 Web-based user interface and API are invoked by ``--port`` or
 ``-p`` flag. To start web server on ``http://0.0.0.0:9000``
@@ -543,14 +553,41 @@ request.body = ['Solanum mariae Särkinen & S.Knapp',
 response = http.request(request)
 ```
 
+#### Enabling logs for GNparser's web-service
+
+There are several ways to enable logging from a web service.
+
+The following enables web-access logs to be printed to STDERR
+
+```
+gnparser -p 80 --web-logs
+```
+
+This next settings allows to send logs to a [NSQ] messaging service.
+This option allows aggregation logs from several instances of GNparser together.
+It is a great way for log aggregation and analysis if the instances run
+inside Docker containers or as Kubernetes Pods.
+
+```
+gnparser -p 80 --nsqd-tcp=127.0.0.1:4150
+```
+
+An **important note**: the address must point to the TCP service of nsqd.
+
+To enable logs to be sent to STDERR and [NSQ] run
+
+```
+gnparser -p 80 --web-logs --nsqd-tcp=127.0.0.1:4150
+```
+
 ### Use as a Docker image
 
 You need to have [docker runtime installed](https://docs.docker.com/install/)
 on your computer for these examples to work.
 
 ```bash
 # run as a website and a RESTful service
-docker run -p 0.0.0.0:80:8080 gnames/gognparser -p 8080
+docker run -p 0.0.0.0:80:8080 gnames/gognparser -p 8080 --web-logs
 
 # just parse something
 docker run gnames/gognparser "Amaurorhinus bewichianus (Wollaston,1860) (s.str.)"
@@ -650,6 +687,7 @@ Released under [MIT license]
 [CONTRIBUTING]: https://github.com/gnames/gnparser/blob/master/CONTRIBUTING.md
 [Dmitry Mozzherin]: https://github.com/dimus
 [Geoff Ower]: https://github.com/gdower
+[NSQ]: https://nsq.io/overview/quick_start.html
 [Toby Marsden]: https://github.com/tobymarsden
 [Hernan Lucas Pereira]: https://github.com/LocoDelAssembly
 [Homebrew]: https://brew.sh/

config.go

@@ -10,26 +10,52 @@ import (
 // Config keeps settings that might affect how parsing is done,
 // of change the parsing output.
 type Config struct {
+	// BatchSize sets the maximum number of elements in names-strings slice.
+	BatchSize int
+
+	// Debug sets a "debug" state for parsing. The debug state forces output
+	// format to showing parsed ast tree.
+	Debug bool
+
 	// Format sets the output format for CLI and Web interfaces.
 	// There are 3 formats available: 'CSV', 'CompactJSON' and
 	// 'PrettyJSON'.
 	Format gnfmt.Format
 
+	// IgnoreHTMLTags can be set to true when it is desirable to clean up names
+	// from a few HTML tags often present in names-strings that were planned to
+	// be presented via an HTML page.
+	IgnoreHTMLTags bool
+
+	// IsTest can be set to true when parsing functionality is used for tests.
+	// In such cases the `ParserVersion` field is presented as `test_version`
+	// instead of displaying the actual version of `gnparser`.
+	IsTest bool
+
 	// JobsNum sets a level of parallelism used during parsing of
 	// a stream of name-strings.
 	JobsNum int
 
-	// BatchSize sets the maximum number of elements in names-strings slice.
-	BatchSize int
+	// Port to run wer-service.
+	Port int
 
-	// WithStream changes from parsing a batch by batch, to parsing one name
-	// at a time. When WithStream is true, BatchSize setting is ignored.
-	WithStream bool
+	// WebLogsNsqdTCP provides an address to the NSQ messenger TCP service. If
+	// this value is set and valid, the web logs will be published to the NSQ.
+	// The option is ignored if `Port` is not set.
+	//
+	// If WithWebLogs option is set to `false`, but `WebLogsNsqdTCP` is set to a
+	// valid URL, the logs will be sent to the NSQ messanging service, but they
+	// wil not appear as STRERR output.
+	// Example: `127.0.0.1:4150`
+	WebLogsNsqdTCP string
 
-	// IgnoreHTMLTags can be set to true when it is desirable to clean up names
-	// from a few HTML tags often present in names-strings that were planned to
-	// be presented via an HTML page.
-	IgnoreHTMLTags bool
+	// WithCapitalization flag, when true, the first letter of a name-string
+	// is capitalized, if appropriate.
+	WithCapitalization bool
+
+	// WithCultivars flag, when true, cultivar names will be parsed and
+	// modify cardinality, normalized and canonical output.
+	WithCultivars bool
 
 	// WithDetails can be set to true when a simplified output is not sufficient
 	// for obtaining a required information.
@@ -38,28 +64,16 @@ type Config struct {
 	// WithNoOrder flag, when true, output and input are in different order.
 	WithNoOrder bool
 
-	// WithCapitalization flag, when true, the first letter of a name-string
-	// is capitalized, if appropriate.
-	WithCapitalization bool
-
 	// WithPreserveDiaereses flag, when true, diaereses will not be transliterated
 	WithPreserveDiaereses bool
 
-	// WithCultivars flag, when true, cultivar names will be parsed and
-	// modify cardinality, normalized and canonical output.
-	WithCultivars bool
-
-	// Port to run wer-service.
-	Port int
-
-	// IsTest can be set to true when parsing functionality is used for tests.
-	// In such cases the `ParserVersion` field is presented as `test_version`
-	// instead of displaying the actual version of `gnparser`.
-	IsTest bool
+	// WithStream changes from parsing a batch by batch, to parsing one name
+	// at a time. When WithStream is true, BatchSize setting is ignored.
+	WithStream bool
 
-	// Debug sets a "debug" state for parsing. The debug state forces output
-	// format to showing parsed ast tree.
-	Debug bool
+	// WithWebLogs flag enables logs when running web-service. This flag is
+	// ignored if `Port` value is not set.
+	WithWebLogs bool
 }
 
 // Option is a type that has to be returned by all Option functions. Such
@@ -129,17 +143,17 @@ func OptPort(i int) Option {
 	}
 }
 
-// OptWithCapitaliation sets the WithCapitalization field.
-func OptWithCapitaliation(b bool) Option {
+// OptWebLogsNsqdTCP provides a URL to NSQ messanging service.
+func OptWebLogsNsqdTCP(s string) Option {
 	return func(cfg *Config) {
-		cfg.WithCapitalization = b
+		cfg.WebLogsNsqdTCP = s
 	}
 }
 
-// OptPreserveDiaereses sets the PreserveDiaereses field.
-func OptWithPreserveDiaereses(b bool) Option {
+// OptWithCapitaliation sets the WithCapitalization field.
+func OptWithCapitaliation(b bool) Option {
 	return func(cfg *Config) {
-		cfg.WithPreserveDiaereses = b
+		cfg.WithCapitalization = b
 	}
 }
 
@@ -164,13 +178,27 @@ func OptWithNoOrder(b bool) Option {
 	}
 }
 
+// OptWithPreserveDiaereses sets the PreserveDiaereses field.
+func OptWithPreserveDiaereses(b bool) Option {
+	return func(cfg *Config) {
+		cfg.WithPreserveDiaereses = b
+	}
+}
+
 // OptWithDetails sets the WithDetails field.
 func OptWithStream(b bool) Option {
 	return func(cfg *Config) {
 		cfg.WithStream = b
 	}
 }
 
+// OptWithWebLogs sets the WithWebLogs field.
+func OptWithWebLogs(b bool) Option {
+	return func(cfg *Config) {
+		cfg.WithWebLogs = b
+	}
+}
+
 // NewConfig generates a new Config object. It can take an arbitrary number
 // of `Option` functions to modify default configuration settings.
 func NewConfig(opts ...Option) Config {

gnparser.go

@@ -104,6 +104,15 @@ func (gnp gnparser) Format() gnfmt.Format {
 	return gnp.cfg.Format
 }
 
+// WebLogs returns a boolean to show or not the web-service logs.
+func (gnp gnparser) WebLogs() bool {
+	return gnp.cfg.WithWebLogs
+}
+
+func (gnp gnparser) WebLogsNsqdTCP() string {
+	return gnp.cfg.WebLogsNsqdTCP
+}
+
 // ChangeConfig allows change configuration of already created
 // GNparser object.
 func (gnp gnparser) ChangeConfig(opts ...Option) GNparser {