Merge pull request #29 from corda/logging-cordapp

Author: davidawad

Features/README.md

@@ -3,43 +3,47 @@
 This folder features several sample projects, each of them demonstrates different specific features of corda.
 
 ### [Blacklist -- Attachment](./attachment-blacklist):
-This CorDapp allows nodes to reach agreement over arbitrary strings of text, but only with parties that are not included in the blacklist uploaded to the nodes as an [attachment](https://training.corda.net/corda-details/attachments/).  
+This CorDapp allows nodes to reach agreement over arbitrary strings of text, but only with parties that are not included in the blacklist uploaded to the nodes as an [attachment](https://training.corda.net/corda-details/attachments/).
 
 ### [Sendfile -- Attachment](./attachment-sendfile):
-This Cordapp shows how to upload and download an [attachment](https://training.corda.net/corda-details/attachments/) via a flow.  
+This Cordapp shows how to upload and download an [attachment](https://training.corda.net/corda-details/attachments/) via a flow.
 <p align="center">
   <img src="./attachment-sendfile/graph.png" alt="Corda" width="700">
 </p>
 
 ### [Whistleblower -- Confidential Identity ](./confidentialIdentity-whistleblower):
-This CorDapp is a simple showcase of [confidential identities](https://docs.corda.net/docs/corda-os/api-identity.html#confidential-identities) (i.e. anonymous public keys).  
+This CorDapp is a simple showcase of [confidential identities](https://docs.corda.net/docs/corda-os/api-identity.html#confidential-identities) (i.e. anonymous public keys).
 
 ### [Autopayroll -- CordaService](./cordaService-autopayroll):
-This Cordapp shows how to trigger a flow with vault update(completion of prior flows) using [CordaService](https://training.corda.net/corda-details/automation/#services) & [trackby](https://training.corda.net/corda-details/automation-solution/#track-and-notify).  
+This Cordapp shows how to trigger a flow with vault update(completion of prior flows) using [CordaService](https://training.corda.net/corda-details/automation/#services) & [trackby](https://training.corda.net/corda-details/automation-solution/#track-and-notify).
 <p align="center">
   <img src="./cordaService-autopayroll/webpic/Business%20Logic.png" alt="Corda" width="500">
 </p>
 
 ### [Trade Reporting -- ObservableStates](./observableStates-tradereporting):
-This CorDapp shows how Corda's [observable states](https://docs.corda.net/docs/corda-os/4.4/tutorial-observer-nodes.html#observer-nodes) feature works. Observable states is the ability for nodes who are not participants in a transaction to still store them if the transactions are sent to them.  
+This CorDapp shows how Corda's [observable states](https://docs.corda.net/docs/corda-os/4.4/tutorial-observer-nodes.html#observer-nodes) feature works. Observable states is the ability for nodes who are not participants in a transaction to still store them if the transactions are sent to them.
 
 ### [Prime Number -- Oracle](./oracle-primenumber):
 This CorDapp implements an [oracle service](https://training.corda.net/corda-details/oracles) that allows nodes to:
 
 * Request the Nth prime number
-* Request the oracle's signature to prove that the number included in their transaction is actually the Nth prime number  
+* Request the oracle's signature to prove that the number included in their transaction is actually the Nth prime number
 
 
 ### [Car Insurance -- QueryableState](./queryableState-carinsurance):
-This CorDapp demonstrates [QueryableState](https://docs.corda.net/docs/corda-os/api-persistence.html) works in Corda. Corda allows developers to have the ability to expose some or all parts of their states to a custom database table using an ORM tools. To support this feature the state must implement `QueryableState`.  
+This CorDapp demonstrates [QueryableState](https://docs.corda.net/docs/corda-os/api-persistence.html) works in Corda. Corda allows developers to have the ability to expose some or all parts of their states to a custom database table using an ORM tools. To support this feature the state must implement `QueryableState`.
 
 ### [Sanctionsbody -- ReferenceStates](./referenceStates-sanctionsBody):
 This CorDapp demonstrates the use of [reference states](https://training.corda.net/corda-details/reference-states/) in a transaction and in the verification method of a contract.
 
-This CorDapp allows two nodes to enter into an IOU agreement, but enforces that both parties belong to a list of sanctioned entities. This list of sanctioned entities is taken from a referenced SanctionedEntities state.  
+This CorDapp allows two nodes to enter into an IOU agreement, but enforces that both parties belong to a list of sanctioned entities. This list of sanctioned entities is taken from a referenced SanctionedEntities state.
 
 ### [Heartbeat -- SchedulableState](./schedulableState-heartbeat):
-This CorDapp is a simple showcase of [scheduled activities](https://docs.corda.net/docs/corda-os/event-scheduling.html#how-to-implement-scheduled-events) (i.e. activities started by a node at a specific time without direct input from the node owner).  
+This CorDapp is a simple showcase of [scheduled activities](https://docs.corda.net/docs/corda-os/event-scheduling.html#how-to-implement-scheduled-events) (i.e. activities started by a node at a specific time without direct input from the node owner).
 <p align="center">
   <img src="./schedulableState-heartbeat/heart.jpg" alt="Corda" width="500">
 </p>
+
+### [CustomLogging -- YoCordapp](./customlogging-yocordapp):
+This cordapp has some examples on how to setup custom logging with corda for either json logging and other tooling.
+

Features/customlogging-yocordapp/.ci/Jenkinsfile

@@ -0,0 +1,37 @@
+#!groovy
+/**
+ * Jenkins pipeline to build the kotlin CorDapp template
+ */
+
+/**
+ * Kill already started job.
+ * Assume new commit takes precedence and results from previousunfinished builds are not required.
+ * This feature doesn't play well with disableConcurrentBuilds() option
+ */
+@Library('corda-shared-build-pipeline-steps')
+import static com.r3.build.BuildControl.killAllExistingBuildsForJob
+killAllExistingBuildsForJob(env.JOB_NAME, env.BUILD_NUMBER.toInteger())
+
+pipeline {
+    agent {
+        label 'eight-cores'
+    }
+    options {
+        ansiColor('xterm')
+        timestamps()
+        timeout(3*60) // 3 hours
+        buildDiscarder(logRotator(daysToKeepStr: '7', artifactDaysToKeepStr: '7'))
+    }
+    stages {
+        stage('Build') {
+            steps {
+                sh './gradlew --no-daemon -s clean build test deployNodes'
+            }
+        }
+    }
+    post {
+        cleanup {
+            deleteDir()
+        }
+    }
+}

Features/customlogging-yocordapp/.gitignore

@@ -0,0 +1,77 @@
+# Eclipse, ctags, Mac metadata, log files
+.classpath
+.project
+tags
+.DS_Store
+*.log
+*.log.gz
+*.orig
+
+.gradle
+
+# General build files
+**/build/*
+!docs/build/*
+
+lib/dokka.jar
+
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio
+
+*.iml
+
+## Directory-based project format:
+#.idea
+
+# if you remove the above rule, at least ignore the following:
+
+# Specific files to avoid churn
+.idea/*.xml
+.idea/copyright
+.idea/jsLibraryMappings.xml
+
+# User-specific stuff:
+.idea/tasks.xml
+.idea/dictionaries
+
+# Sensitive or high-churn files:
+.idea/dataSources.ids
+.idea/dataSources.xml
+.idea/sqlDataSources.xml
+.idea/dynamic.xml
+.idea/uiDesigner.xml
+
+# Gradle:
+.idea/libraries
+
+# Mongo Explorer plugin:
+.idea/mongoSettings.xml
+
+## File-based project format:
+*.ipr
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+workflows/out/
+contracts/out/
+clients/out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+
+# docs related
+docs/virtualenv/
+
+# if you use the installQuasar task
+lib

Features/customlogging-yocordapp/.settings/org.eclipse.jdt.core.prefs

@@ -0,0 +1 @@
+org.eclipse.jdt.core.compiler.codegen.methodParameters=generate

Features/customlogging-yocordapp/LICENCE

@@ -0,0 +1,13 @@
+  Copyright 2016, R3 Limited.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Features/customlogging-yocordapp/README.md

@@ -0,0 +1,136 @@
+# Logging CorDapp
+
+## Custom Logging
+
+This is a modified version of the original yo cordapp with some additions to use custom log4j2 configurations.
+
+
+The primary example we've implemented here is json logging which is configured in `config/dev/log4j2.xml`.
+
+This gives us the ability to use Log4j thread contexts to log arbitrary objects or data points in json format.
+
+In this example not only do the node logs output in json but we can add arbitrary key value pairs as well.
+
+```java
+        // here we have our first opportunity to log out the contents of the flow arguments.
+        ThreadContext.put("initiator", me.name.toString())
+        ThreadContext.put("target", target.name.toString())
+        // publish to the log with the additional context
+        logger.info("Initializing the transaction.")
+```
+
+When we log this message, it gets output along with the other key value pairs we've specified in a JSON format:
+```
+{
+  "instant": {
+    "epochSecond": 1612982209,
+    "nanoOfSecond": 487000000
+  },
+  "thread": "Node thread-1",
+  "level": "INFO",
+  "loggerName": "net.corda",
+  "message": "Initializing the transaction.",
+  "endOfBatch": true,
+  "loggerFqcn": "org.apache.logging.slf4j.Log4jLogger",
+  "contextMap": {
+    "actor_id": "internalShell",
+    "actor_owning_identity": "O=PartyA, L=London, C=GB",
+    "actor_store_id": "NODE_CONFIG",
+    "fiber-id": "10000001",
+    "flow-id": "94543b19-b949-441e-9962-bc50dcd7ad55",
+    "initiator": "O=PartyA, L=London, C=GB",
+    "invocation_id": "a53a3a5d-b450-456e-a0f1-dfb7dcdce6dd",
+    "invocation_timestamp": "2021-02-10T18:36:49.312Z",
+    "origin": "internalShell",
+    "session_id": "e8ba737e-e809-4a14-8c3b-284b7ae5ed88",
+    "session_timestamp": "2021-02-10T18:36:49.022Z",
+    "target": "O=PartyB, L=New York, C=US",
+    "thread-id": "168"
+  },
+  "threadId": 168,
+  "threadPriority": 5
+}
+```
+
+
+This can be quite powerful if you're looking to produce a consumable output stream to a log aggregator like splunk.
+
+You can end up getting log feeds in json that look something like this:
+
+```json
+{"instant":{"epochSecond":1612369055,"nanoOfSecond":12000000},"thread":"main","level":"INFO","loggerName":"net.corda.node.internal.Node","message":"Vendor: Corda Open Source","endOfBatch":true,"loggerFqcn":"org.apache.logging.slf4j.Log4jLogger","threadId":1,"threadPriority":5}
+. . .More Node Startup loggings
+
+// when our flow is run we see the log we specified
+{"instant":{"epochSecond":1612460471,"nanoOfSecond":866000000},"thread":"pool-10-thread-2","level":"INFO","loggerName":"net.corda.tools.shell.FlowShellCommand","message":"Executing command \"flow start net.corda.samples.logging.flows.YoFlow target: PartyA\",","endOfBatch":true,"loggerFqcn":"org.apache.logging.slf4j.Log4jLogger","threadId":224,"threadPriority":5}
+{"instant":{"epochSecond":1612460472,"nanoOfSecond":304000000},"thread":"Node thread-1","level":"INFO","loggerName":"net.corda","message":"Initializing the transaction.","endOfBatch":true,"loggerFqcn":"org.apache.logging.slf4j.Log4jLogger","threadId":166,"threadPriority":5}
+{"instant":{"epochSecond":1612460472,"nanoOfSecond":428000000},"thread":"pool-10-thread-2","level":"WARN","loggerName":"net.corda.tools.shell.utlities.StdoutANSIProgressRenderer","message":"Cannot find console appender - progre
+```
+
+## Usage
+
+
+### Pre-Requisites
+
+See https://docs.corda.net/getting-set-up.html.
+
+
+### Running the CorDapp
+
+Open a terminal and go to the project root directory and type: (to deploy the nodes using bootstrapper)
+```
+./gradlew clean deployNodes
+```
+Then type: (to run the nodes)
+
+```
+./build/nodes/runnodes
+```
+
+When the nodes run you'll be able to see the node's json log files in their respesctive `logs` folders.
+This logging configuration will add a new file that you can view.
+
+```shell
+tail -f  build/nodes/PartyA/logs/node.json
+
+{"instant":{"epochSecond":1612543764,"nanoOfSecond":930000000},"thread":"main","level":"INFO","loggerName":"net.corda.cliutils.CliWrapperBase","message":"Application Args: run-migration-scripts --core-schemas --app-schemas","endOfBatch":true,"loggerFqcn":"org.apache.logging.slf4j.Log4jLogger","contextMap":{},"threadId":1,"threadPriority":5}
+{"instant":{"epochSecond":1612543766,"nanoOfSecond":300000000}
+
+. . .
+```
+
+### Sending a Yo
+
+We will interact with the nodes via their specific shells. When the nodes are up and running, use the following command to send a
+Yo to another node:
+
+```
+    flow start YoFlow target: PartyB
+```
+
+Where `NODE_NAME` is 'PartyA' or 'PartyB'. The space after the `:` is required. You are not required to use the full
+X500 name in the node shell. Note you can't sent a Yo! to yourself because that's not cool!
+
+To see all the Yo's! other nodes have sent you in your vault (you do not store the Yo's! you send yourself), run:
+
+```
+    run vaultQuery contractStateType: YoState
+```
+
+### Other ways to use this log configuration
+
+The above method will run all nodes together but if you're running your corda node manually all you need to do is specify the particular config file.
+
+You can do that by just running the jar directly:
+
+```shell
+java -Dlog4j.configurationFile=logging-cordapp/build/resources/main/log4j2.xml -jar corda.jar
+```
+
+> notice that all we're doing is adding this param to the command we'd otherwise use to run corda in order to specify the log file.
+
+
+## Attribution
+
+This example was built with help from [Splunk](https://splunk.com), and they have our thanks.
+

Features/customlogging-yocordapp/TRADEMARK

@@ -0,0 +1,4 @@
+Corda and the Corda logo are trademarks of R3CEV LLC and its affiliates. All rights reserved.
+
+For R3CEV LLC's trademark and logo usage information, please consult our Trademark Usage Policy at
+https://www.r3.com/trademark-policy/.