put in LDMS Kokkos Tools connector

Author: vlkale

profiling/ldms-connector/README.md

@@ -0,0 +1,45 @@
+# LDMS-Kokkos Connector
+
+The LDMS Kokkos Tools Connector - along with the optional Kokkos Sampler Tools utility - utilizes LDMS Streams to collect kernel messages generated by it (or optionally generated by the Kokkos Tools Sampler) and received by the Kokkos Tools Connector.
+
+The LDMS-Kokkos Connector relies on LDMS Streams to publish data to your provided database. Please refer to the following on how to setup LDMS Streams: https://ovis-hpcreadthedocs.readthedocs.io/en/latest/ldms-streams.html
+
+The following libraries are needed for the kokkosConnector:
+* Kokkos-Tools: https://github.com/kokkos/kokkos-tools
+
+To install the appropriate utitilies in Kokkos-Tools for the optional Kokkos Tools sampler:
+* Navigate to kokkos-tools/common/kokkos-sampler/
+* Follow the appropriate make instructions in Kokkos-Tools to make the kokkos-sampler with its included Makefile. 
+
+The following information will need to be added to the kokkosConnector's Makefile before running make:
+* Path to Ovis needs to be set for OVIS_DIR in the Makefile
+* Path to Kokkos-Tools needs to be set of KTO_DIR in the Makefile
+
+When using the KokkosConnector, the following environmental variables are required to be set prior to application execution command:
+  * KOKKOS_LDMS_HOST="localhost"
+  * KOKKOS_LDMS_PORT="412"
+  * KOKKOS_TOOLS_LIBS="[INSERT PATH TO OVIS]/kokkosConnector/kp_kernel_ldms.so"
+  * KOKKOS_LDMS_AUTH="munge"
+  * KOKKOS_LDMS_XPRT="sock"
+  
+# Usage with sampler utility
+
+Because of the large amount of performance data obtained from LDMS via the
+Kokkos Tools connector, it is recommended to use the Kokkos Tools sampler
+utility, which was in part inspired by the needs of data order reduction for
+performance profiling data of LDMS. Please see the documentation for the
+sampler for its usage. When using the sampler with the LDMS connector, one must
+enables the sampler utility tool connector _and_ considers the LDMS connector
+as its child tool connector library. 
+
+This is done by: 
+
+export KOKKOS_TOOLS_LIBS="kp_sampler.so; kp_kernel_ldms.so";
+ 
+# Verbose Output
+
+For verbose output for the LDMS data, set the KOKKOS_LDMS_VERBOSE environment
+variable. 
+
+* KOKKOS_LDMS_VERBOSE
+  * This variable is for debug purposes and prints all Kokkos messages received by the LDMS-Kokkos Connector to the output file.