[docs] Add third-party logging and tracing integration docs

docs/01_nodeos/06_logging/10_native_logging/index.md

@@ -0,0 +1,112 @@
+---
+content_title: Nodeos Native Logging
+link_text: Nodeos Native Logging
+---
+
+Logging for `nodeos` is controlled by the `logging.json` file. CLI options can be passed to `nodeos` to [setup `logging.json`](10_setup-logging.json.md). The logging configuration file can be used to define [appenders](#appenders) and tie them to [loggers](#loggers) and [logging levels](20_logging-levels.md).
+
+## Appenders
+
+The logging library built into EOSIO supports two appender types:
+
+- [Console](#console)
+- [GELF](#gelf) (Graylog Extended Log Format)
+
+### Console
+
+This will output log messages to the screen. The configuration options are:
+
+- `name` - arbitrary name to identify instance for use in loggers
+- `type` - "console"
+- `stream` - "std_out" or "std_err"
+- `level_colors` - maps a log level to a colour
+  - level - see [logging levels](20_logging-levels.md)
+  - color - may be one of ("red", "green", "brown", "blue", "magenta", "cyan", "white", "console_default")
+- `enabled` - bool value to enable/disable the appender.
+
+Example:
+
+```json
+{
+    "name": "consoleout",
+    "type": "console",
+    "args": {
+    "stream": "std_out",
+
+    "level_colors": [{
+        "level": "debug",
+        "color": "green"
+        },{
+        "level": "warn",
+        "color": "brown"
+        },{
+        "level": "error",
+        "color": "red"
+        }
+    ]
+    },
+    "enabled": true
+}
+```
+
+### GELF
+
+This sends the log messages to `Graylog`. `Graylog` is a fully integrated platform for collecting, indexing, and analyzing log messages. The configuration options are:
+
+ - `name` - arbitrary name to identify instance for use in loggers
+ - `type` - "gelf"
+ - `endpoint` - ip address and port number
+ - `host` - Graylog hostname, identifies you to Graylog.
+ - `enabled` - bool value to enable/disable the appender.
+
+Example:
+
+```json
+{
+    "name": "net",
+    "type": "gelf",
+    "args": {
+        "endpoint": "104.198.210.18:12202”,
+        "host": <YOURNAMEHERE IN QUOTES>
+    },
+    "enabled": true
+}
+```
+
+## Loggers
+
+The logging library built into EOSIO currently supports the following loggers:
+
+- `default` - the default logger, always enabled.
+- `net_plugin_impl` - detailed logging for the net plugin.
+- `http_plugin` - detailed logging for the http plugin.
+- `producer_plugin` - detailed logging for the producer plugin.
+- `state_history` - detailed logging for state history plugin.
+- `transaction_success_tracing` - detailed log that emits successful verdicts from relay nodes on the P2P network.
+- `transaction_failure_tracing` - detailed log that emits failed verdicts from relay nodes on the P2P network.
+- `trace_api` - detailed logging for the trace_api plugin.
+
+The configuration options are:
+
+ - `name` - must match one of the names described above.
+ - `level` - see logging levels below.
+ - `enabled` - bool value to enable/disable the logger.
+ - `additivity` - true or false
+ - `appenders` - list of appenders by name (name in the appender configuration)
+
+Example:
+
+```json
+{
+    "name": "net_plugin_impl",
+    "level": "debug",
+    "enabled": true,
+    "additivity": false,
+    "appenders": [
+        "net"
+    ]
+}
+```
+
+[[info]]
+| The default logging level for all loggers if no `logging.json` is provided is `info`. Each logger can be configured independently in the `logging.json` file.

docs/01_nodeos/06_logging/20_third_party_logging/10_deep_mind_logger.md

@@ -0,0 +1,42 @@
+---
+content_title: Deep-mind Logger Integration
+link_text: Deep-mind Logger Integration
+---
+
+## Overview
+
+The `Deep-mind logger` is part of the `dfuse` [platform]([https://dfuse.io/](https://dfuse.io/)) which is a highly scalable and performant [open-source]([https://github.com/dfuse-io/dfuse-eosio/tree/master](https://github.com/dfuse-io/dfuse-eosio/tree/master)) platform for searching and processing blockchain data.
+
+### How To Enable Deep-mind Logger
+
+EOSIO 3.0 integrates the `nodeos` core service daemon with `deep-mind logger`. To benefit from full `deep-mind` logging functionality you must start your `nodeos` instance with the flag `--deep-mind`. After the start you can observe in the `nodeos` console output the informative details outputs created by the `deep-mind` logger. They distinguish themselves from the default `nodeos` output lines because they start with the `DMLOG` keyword. \
+ \
+Example of `deep-mind` log lines:
+
+```sh
+DMLOG START_BLOCK 30515
+
+DMLOG TRX_OP CREATE onblock 308f77bf49ab4ddde74d37c7310c0742e253319d9da57ebe51eb7b35f1ffe174 {"expiration":"2020-11-12T10:13:06","ref_block_num":30514,...}
+
+DMLOG CREATION_OP ROOT 0
+
+DMLOG RLIMIT_OP ACCOUNT_USAGE UPD {"owner":"eosio","net_usage":{"last_ordinal":1316982371,"value_ex":0,"consumed":0},"cpu_usage":{"last_ordinal":1316982371,"value_ex":24855,"consumed":101},"ram_usage":27083}
+
+DMLOG APPLIED_TRANSACTION 30515 {"id":"308f77bf49ab4ddde74d37c7310c0742e253319d9da57ebe51eb7b35f1ffe174","block_num":30515,"block_time":"2020-11-12T10:13:05.500",...}
+
+DMLOG RLIMIT_OP STATE UPD {"average_block_net_usage":{"last_ordinal":30514,"value_ex":0,"consumed":0},"average_block_cpu_usage":{"last_ordinal":30514,...} \
+DMLOG ACCEPTED_BLOCK 30516 {"block_num":30516,"dpos_proposed_irreversible_blocknum":30516,"dpos_irreversible_blocknum":30515,...
+```
+
+```sh
+DMLOG FEATURE_OP ACTIVATE 0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd {"feature_digest":"0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd","subjective_restrictions":{"enabled":true,"preactivation_required":false,"earliest_allowed_activation_time":"1970-01-01T00:00:00.000"},"description_digest":"64fe7df32e9b86be2b296b3f81dfd527f84e82b98e363bc97e40bc7a83733310","dependencies":[],"protocol_feature_type":"builtin","specification":[{"name":"builtin_feature_codename","value":"PREACTIVATE_FEATURE"}]}
+
+```
+
+```sh
+DMLOG FEATURE_OP ACTIVATE 825ee6288fb1373eab1b5187ec2f04f6eacb39cb3a97f356a07c91622dd61d16 {"feature_digest":"825ee6288fb1373eab1b5187ec2f04f6eacb39cb3a97f356a07c91622dd61d16","subjective_restrictions":{"enabled":true,"preactivation_required":true,"earliest_allowed_activation_time":"1970-01-01T00:00:00.000"},"description_digest":"14cfb3252a5fa3ae4c764929e0bbc467528990c9cc46aefcc7f16367f28b6278","dependencies":[],"protocol_feature_type":"builtin","specification":[{"name":"builtin_feature_codename","value":"KV_DATABASE"}]}
+```
+
+```sh
+DMLOG FEATURE_OP ACTIVATE c3a6138c5061cf291310887c0b5c71fcaffeab90d5deb50d3b9e687cead45071 {"feature_digest":"c3a6138c5061cf291310887c0b5c71fcaffeab90d5deb50d3b9e687cead45071","subjective_restrictions":{"enabled":true,"preactivation_required":true,"earliest_allowed_activation_time":"1970-01-01T00:00:00.000"},"description_digest":"69b064c5178e2738e144ed6caa9349a3995370d78db29e494b3126ebd9111966","dependencies":[],"protocol_feature_type":"builtin","specification":[{"name":"builtin_feature_codename","value":"ACTION_RETURN_VALUE"}]}
+```

docs/01_nodeos/06_logging/20_third_party_logging/20_zipkin_tracer.md

@@ -0,0 +1,34 @@
+---
+content_title: Zipkin Tracer Integration
+link_text: Zipkin Tracer Integration
+---
+
+## Overview
+
+The `Zipkin service` is a [distributed tracing system](https://zipkin.io/). It helps gather timing data needed to troubleshoot latency problems in service architectures. Its features include both the collection and lookup of this data. `Zipkin tracer` is the EOSIO 3.0 component that sends traces to the `Zipkin service`. The `Zipkin` service can be installed in the local environment or it can be remote.
+
+### How To Enable Zipkin Tracer
+
+EOSIO 3.0 makes available `Zipkin tracer` through the [core `chain_plugin`](https://developers.eos.io/manuals/eos/v2.0/nodeos/plugins/chain_plugin/index/?query=chain%20plugin&page=1#gatsby-focus-wrapper). To enable the `Zipkin tracer` you must set the `telemetry-url` parameter for the `chain_plugin`. There are two additional parameters you can set: `telemetry-service-name` and `telemetry-timeout-us`. All three available parameters are detailed below:
+
+* `telemetry-url` specifies the url of the Zipkin service, e.g. [http://127.0.0.1:9411/api/v2/spans](http://127.0.0.1:9411/api/v2/spans) if it is installed in the local environment.
+* `telemetry-service-name` specifies the Zipkin `localEndpoint.serviceName` sent with each span.
+* `telemetry-timeout-us`, optional parameter, specifies the timeout for sending zipkin spans with default value set to 200000. `Zipkin tracer` sends zipkin spans, in json format, to the `Zipkin service` via HTTP POST requests on a separate thread. `telemetry-timeout-us` specifies how long to allow each HTTP POST request before reaching the time out and thus fail. Nine consecutive failures will disable the `Zipkin tracer` until a restart of `nodeos` daemon occurs.
+
+Once `Zipkin tracer` is enabled you can observe the detailed traces it sends to the `Zipkin service`. Examples of such traces are given below.
+
+Submitted transaction:
+
+![Submitted transaction](submitted_transaction.png)
+
+Processed transaction:
+
+![Processed transaction](processed_transaction.png)
+
+Block accepted:
+
+![Block accepted](block_accepted.png)
+
+SHiP Accepted:
+
+![SHiP Accepted](ship_accepted.png)

docs/01_nodeos/06_logging/20_third_party_logging/index.md

@@ -0,0 +1,15 @@
+---
+content_title: Third-Party Logging And Tracing Integration
+link_text: Third-Party Logging And Tracing Integration
+---
+
+## Overview
+
+To stay informed about the overall and detailed performance of your EOSIO-based blockchain node(s), you can make use of the telemetry tools available. EOSIO offers integration with two such telemetry tools:
+
+* [Deep-mind logger](10_deep_mind_logger.md)
+* [Zipkin tracer](20_zipkin_tracer.md)
+
+## Performance Considerations
+
+Many wise people already said it, everything comes with a price. The telemetry tools, when activated, will have a certain impact on your `nodeos` performance which depends on various factors, but nevertheless the performance will be impacted. Therefore it is recommended you use them wisely in those situations when you really need the extra detailed information they provide, and then you turn them off.

docs/01_nodeos/06_logging/index.md

@@ -1,111 +1,9 @@
 ---
-content_title: Nodeos Logging
+content_title: Nodeos Logging And Tracing
+link_text: Nodeos Logging And Tracing
 ---
 
-Logging for `nodeos` is controlled by the `logging.json` file. CLI options can be passed to `nodeos` to [setup `logging.json`](00_setup-logging.json.md). The logging configuration file can be used to define [appenders](#appenders) and tie them to [loggers](#loggers) and [logging levels](01_logging-levels.md).
+Nodeos has the following logging and tracing features:
 
-## Appenders
-
-The logging library built into EOSIO supports two appender types:
-
-- [Console](#console)
-- [GELF](#gelf) (Graylog Extended Log Format)
-
-### Console 
-
-This will output log messages to the screen. The configuration options are:
-
-- `name` - arbitrary name to identify instance for use in loggers
-- `type` - "console"
-- `stream` - "std_out" or "std_err"
-- `level_colors` - maps a log level to a colour
-  - level - see [logging levels](01_logging-levels.md)
-  - color - may be one of ("red", "green", "brown", "blue", "magenta", "cyan", "white", "console_default")
-- `enabled` - bool value to enable/disable the appender.
-
-Example:
-
-```json
-{
-    "name": "consoleout",
-    "type": "console",
-    "args": {
-    "stream": "std_out",
-
-    "level_colors": [{
-        "level": "debug",
-        "color": "green"
-        },{
-        "level": "warn",
-        "color": "brown"
-        },{
-        "level": "error",
-        "color": "red"
-        }
-    ]
-    },
-    "enabled": true
-}
-```
-
-### GELF
-
-This sends the log messages to `Graylog`. `Graylog` is a fully integrated platform for collecting, indexing, and analyzing log messages. The configuration options are:
-
- - `name` - arbitrary name to identify instance for use in loggers
- - `type` - "gelf"
- - `endpoint` - ip address and port number
- - `host` - Graylog hostname, identifies you to Graylog.
- - `enabled` - bool value to enable/disable the appender.
-
-Example:
-
-```json
-{
-    "name": "net",
-    "type": "gelf",
-    "args": {
-        "endpoint": "104.198.210.18:12202”,
-        "host": <YOURNAMEHERE IN QUOTES>
-    },
-    "enabled": true
-}
-```
-
-## Loggers
-
-The logging library built into EOSIO currently supports the following loggers:
-
-- `default` - the default logger, always enabled.
-- `net_plugin_impl` - detailed logging for the net plugin.
-- `http_plugin` - detailed logging for the http plugin.
-- `producer_plugin` - detailed logging for the producer plugin.
-- `state_history` - detailed logging for state history plugin.
-- `transaction_success_tracing` - detailed log that emits successful verdicts from relay nodes on the P2P network.
-- `transaction_failure_tracing` - detailed log that emits failed verdicts from relay nodes on the P2P network.
-- `trace_api` - detailed logging for the trace_api plugin.
-
-The configuration options are:
-
- - `name` - must match one of the names described above.
- - `level` - see logging levels below.
- - `enabled` - bool value to enable/disable the logger.
- - `additivity` - true or false
- - `appenders` - list of appenders by name (name in the appender configuration)
-
-Example:
-
-```json
-{
-    "name": "net_plugin_impl",
-    "level": "debug",
-    "enabled": true,
-    "additivity": false,
-    "appenders": [
-        "net"
-    ]
-}
-```
-
-[[info]]
-| The default logging level for all loggers if no `logging.json` is provided is `info`. Each logger can be configured independently in the `logging.json` file.
+* [Nodeos Native Logging](10_native_logging/index.md)
+* [Nodeos Logging And Tracing Third-Party Integration] (20_third_party_logging/index.md)