Monitoring and Logging

[#1]

• Step 1: Example and Strategy
• Step 2: Utilizing Logging Functions
• Step 3: Logging Complex Objects
• Step 4: Viewing and Filtering Logs
• Step 5: Next Steps

Utilizing the ThingWorx monitoring system

Guide Concept

Being able to view your logs is an important part of knowing what is happening in your system. You can't keep things secure if you don't know who is doing what.

These concepts and provide you with ways to find information about what is going on in your application and system.

We will teach you how to access the monitoring panel and help keep your application running the way you need it to.

You'll learn how to

• How to log data and capture useful information
• How to filter and find what you need in the monitoring pages.

NOTE:  The estimated time to complete this guide is 30 minutes

Step 1: Example and Strategy

If you’d like to skip ahead, download the completed example of the Aerospace and Defense learning path: AerospaceEntitiesGuide1.zip. Extract, then import the .twx files included.

In the last guide, we ended with viewing the Monitoring section of ThingWorx. What you’ll now learn is a more detailed method to knowing exactly what is happening in your application. Part of the magic in logging comes from informative statements and how you perform your error handling.

We will create an Entity with a number of services that will allow us to see what is happening in our application. In order to automate these services and view the logs that they generate, we’ll be using Schedulers. When we have everything running, we’ll go over how to utilize the Monitoring section to its strengths.

Step 2: Utilizing Logging Functions

Errors happen. Sooner or later, there will be an error. When you have an error in your application, you need to know about it and have information to help resolve the problem. There are 5 main logging functions under the universal logger object – info, debug, trace, warn, and error.

Function	Description
info	Used for high level and general information.
debug	Used for debugging an application and capturing data.
trace	Used for low level and tracking what is happening.
warn	Used to warn for possible errors or problems.
error	Used for showing an error in a log.

Let’s create a Thing that performs logging for different data types (complex types will be handled in the next section).

1.  In the ThingWorx Composer, click the + New button in the top left. 

2. In the dropdown list, click Thing.

 

3. In the Name field, give our agency name, such as  LoggingServices.

4. In the Base Thing Template field, select GenericThing.

5. Select a Project, such as PTCDefaultProject. Set this as the default context if you wish.

6. Click Save.

Let's start creating our services.

1. Click the Services tab.

2. Click the Add button to create a new JavaScript service.

3. Enter LogInformation in the Name field of the service.

4. Enter the below lines as the code for the service.

       logger.trace("LoggingServices.LogInformation(): Entering Service.");
       logger.info("LoggingServices.LogInformation(): Logging at Information Level");
 
       try {
	    var x = 10;
	    var y = 20;
	    var z = 0;

	    logger.debug("LoggingServices.LogInformation(): Logging Addition - " + (x + y));
	    logger.debug("LoggingServices.LogInformation(): Logging Division - " + (y / z));
      }  catch(error) {
	    logger.error("LoggingServices.LogInformation(): Error - " + error);
      }

      logger.trace("LoggingServices.LogInformation(): Ending Service.");

5. Click the Save and Continue button. Hit the Execute button.

When triggered, this service will print the trace information for the service, the information level logging, the sum of the x and y variables, and our error message (because of our division by 0 attempt). In the next section, we’ll cover the log file types and how to filter to get what we want.

Step 3: Logging Complex Objects

As you know, with JavaScript, objects can be seen as JSON. That being said, The JSON.stringify function is very handy in printing out complex objects in ThingWorx (NOTE: In order to print out an InfoTable, use <infotable>.toJSON() ). Let’s create a new service to log more complex types.

1.     Open our LoggingServices Thing that we created in the earlier sections.

2.     Click the Services tab.

3.     Click the Add button to create a new service.

4.     Enter LogComplexObjects  in the Name field.

5.     Enter the below statements into the code area.

logger.trace("LoggingServices. LogComplexObjects (): Entering Service.");
logger.info("LoggingServices. LogComplexObjects (): Logging at Information Level");

try {
	var x = {};
	x.y = 20;
	x.z = 0;   

	logger.debug("LoggingServices. LogComplexObjects (): Logging Addition - " + (x + y));
	logger.debug("LoggingServices. LogComplexObjects (): Logging Division - " + (y / z));
} catch(error) {
	logger.error("LoggingServices. LogComplexObjects (): Error - " + error);
}

logger.trace("LoggingServices. LogComplexObjects (): Ending Service.");

After you execute this service, you should be able to see the outcome in the ScriptLog. Try utilizing some of the filtering methods we mentioned in order to find the log statements.

Step 4: Viewing and Filtering Logs

In the table below, you’ll see what each of the logs showcase. Keep in mind, while some of these logs are accessible in the ThingWorx composer, you can view all of these logs on the server in the /ThingworxStorage/logs directory.

Log	Description
Application Log	The Application Log contains all of the messages that ThingWorx logs while operating. Depending on your settings, this log can display errors only or every execution of the platform.
Communication Log	The Communication Log contains all communication activity with ThingWorx.
Configuration Log	The Configuration Log contains all of the messages that the ThingWorx application generates for any create, modify, and delete done in ThingWorx. For example, if a Thing or Mashup is created, modified, or deleted, that information will be included in the ConfigurationLog.
Database Log	The DatabaseLog contains all messages related to database activity.
Script Log	The ScriptLog contains all of the messages that the ThingWorx application generates while executing JavaScript services. You can use logger.warn(or logger.info, logger.trace, logger.debug, logger.error). By default, the log displays warnings and errors, so we recommend using the warn function to log this information from the services you are running. Generally, ThingWorx will only publish errors that were incurred while running a service to this log.
Security Log	The Security Log contains all of the messages that the ThingWorx application generates regarding users. This information can include login data and page requests depending on the log level.
Script Error Log	The Script Error Log contains the stack trace for scripts created in the platform and is only available in the ScriptErrorLog.log file. Not accessible in the Composer.

Let’s go to the Monitoring section of the ThingWorx Composer and view the results from the server we triggered earlier.

1.     Click on the Monitoring section on the left-hand side of the Composer.

2.     Click on ScriptLog. Based on your role on this team, this might be the log that you view the most.

 

3.     You should be able to see or find the logs we recently generated from executing our new service.

The logging views in Composer will generally show you the last 24-hour period. This can be helpful if you know something ran within the last day. Based on the amount of logging your system performs, that can be way too large a window. Let’s start playing with the filters and searches.

 

#	Function
1	The search text box allows you to search for specific words in the log based on your time window. Once you have entered the word, hit the **ENTER/RETURN key on your keyboard.
2	The filter button provides a menu that provides more features to filter the logs. See below.
3	The configure button provides a pop-up that allows you to filter incoming log statements based on a certain logging level. See below.
4	The date range will default to the last 24 hours but can be updated to a wider or smaller window. You will need to click the Apply button when ready.
5	The max rows field provides how many records will come back in the view. The search will continue until it hits this number, or your date range is met. You can shorten this field for faster searching or increase it up to 1000 to showcase more information. You will need to click the Apply button when ready.
6	Apply and Reset buttons. Apply will run the search you currently have on the screen. Reset will reset the date range and max rows ONLY.
7	Auto Refresh allows for the logs to continue rolling in based on your current filters. Think of this as a specified **tail command on a server log.
8	This grid provides the actual logging information. The information provided here can be used to also help filter what you’re looking for. If you see specific thread has the data you need, use the filter menu (2) to filter based on that thread. You can also click on these items to view the log statement clearer.
9	This log message field provides the message from the grid (8) entry clicked on.

The Filter Menu

The filter menu provides very helpful filters. See below for some information on how it works.

#	Function
1	This User field allows you to filter the logs to the user that ran the service or function. This is helpful when you know a specific person has logged in and having problems with your application.
2	The Origin field can help when trying to zero in your search. If you notice in the log message grid, there is an origin field. Use this field to help fine tune your search.
3	The Thread field is amazing when you have multiple processes running and would like to see the logs from one process only. You’ll need to find a log entry before you know which thread to filter on.
4	This is similar to the Origin field in the sense that once you find the instance value for a log entry, it can be used here to help filter.
5	The log level range is exactly as the name states. It will help filter message based on logging level.

The Configure Pop-up

 

The configure pop-up helps with logging going forward. If you only want to see debug level information or you’d like to see everything down to the trace messages, configure it here and you’ll see the change as new messages come in.

Step 5: Next Steps

Congratulations! You've successfully completed the Tracking Activities and Stats guide, and learned how to use the ThingWorx Platform to help track what is happening in your application.

Learn More

We recommend the following resources to continue your learning experience:

 Capability     Guide

Build	Design Your Data Model
Manage	Data Model Implementation Guide

 

Additional Resources

If you have questions, issues, or need additional information, refer to:

 Resource       Link

Community	Developer Community Forum
Support	REST API Help Center