Adding Logs to OCMS Code

Each location that wants to output a performance log needs to first build up a LogstashService.PerformanceLog. This is the object that contains all the details of the log that we want OpenContent to output. Each performance log can contain the following data:

• eventTitle - required, a string that identifies what event is being logged.
• docCount - an integer that indicates how many documents are associated with the logged event. Defaults to 0.
• browser - a string that indicates what browser is being used. If this is not set in the PerformanceLog object, OpenContent will try to retrieve the browser from the ticket. If the browser still cannot be determined, it will be logged out as N/A.
• objectId - the objectId of a specific document associated with the performance log. Used in combination with keys.
• user - the username associated with the log. Will automatically be set to the logged in user.
• events - a map of additional information about the logged event, such as eventDuration or documentSize. These will all appear in the log as {key} {value}. Anything that does not match the other 5 descriptions can and should be put into the events map.

Without any additional information from the user, the performance log will also contain:

• timestamp - the server output time of the log

The LogstashService.PerformanceLog object should be sent through LogstashService.sendMetrics() for a configuration check and additional OCMS data that is needed before making the OpenContent call.

Visualizing the Logs in Kibana

Start by going to the Kibana Discover tab. Check that the logs that you want to visualize are listed. Click on the log instance and make sure that all the log data properties are listed in the drop-down, and both the property name and value match the log. If not, see the Update Logstash Index section before continuing.

Once the logs you want to visualize have all their data available in Kibana, go to the Visualize tab. Select the visualization that you wish to create and select the logstash-stats index. From here, you can query for the logs that you want to include in the data set and select the metrics to visualize the data set appropriately. In the top right corner, click on the clock icon to limit or expand the time frame of the logs included in the visualization.

Ingesting a Pre-existing File in Logstash

Logs are ingested via logstash so that they can be indexed by elastic search and displayed in Kibana. The typical logstash configs we use points logstash to a particular file where logs will be added and logstash has a pointer to the end of the file that updates every time a log is added. This allows for ELK to ingest and display any newly created logs while the ELK stack is running.

However, you may come across a use case where logs that have already been generated would need to be displayed in Kibana. In order to do this you will need to update the logstash.conf file located in the {Logstash_home}/bin directory. At the top of this file you will find a block labeled input. Replace this block with the following:

input {
     file {
         path => "C:/{Your_file_path}/preExisting.log"
         start_position => "beginning"
         sincedb_path => "NUL"
     }
}

The path value tells logstash where to find the pre-existing log file you wish to ingest. Setting the start_position to beginning tells logstash to read the file from the top rather than starting at the bottom and waiting for new logs to be generated which is the default. Setting sincedb_path to "NUL" ensures that the pointer tracking the current position in the tracked file is ignored since we don't want logstash dealing with file positions from a previous run and we want to ensure it ingests the file from the beginning each time we start the service.

Once these configurations are updated you will want to start(or stop and restart) the logstash service. You can do this on the command line from the logstash bin folder by running the command logstash.bat -f logstash.conf --debug. The --debug flag is optional but can be very useful in order to see any errors that may happen due to your logstash configurations.

Update Logstash Index

If the logs that you want to visualize don't show their data correctly in the Kibana Discover tab, that means they do not match the same pattern as an existing log and so they are not getting indexed correctly. In the logstash.conf file (found in Logstash/bin), add a new filter match message in filter -> grok -> match. Within the message, each value you want to pull from the log should take the form %{pattern:name}

• pattern - the format of value (ie. number, text, timestamp, etc.). See the Logstash plugins GitHub for all the patterns that logstash knows by default. If you don't find what you are looking for there, customPatterns.txt (found in Logstash/patterns) contains TSG-specific patterns.
• name - the unique identifier for the value. This name can be used in multiple messages (see log_server_timestamp as an example) but can only be used once within the message.

Other useful information when creating a new filter match:

• \s+ represents a space.
• plain text can be used to differentiate between filter matches, but these will not be included in the Kibana log data properties unless they are in the %{pattern:name} format.

After creating the filter matches, Logstash and Kibana will need to be restarted. When Kibana comes back up, go into the Management tab and click on Index Patterns. Select logstash-stats and refresh the field list. Generate a new set of logs, and the logs and their data properties should be correctly visible on the Discover page.