Planning Analytics LogOutput Function

Rob Baierle, July 10, 2023

The Planning Analytics (TM1) function named LOGOUTPUT allows a developer to write custom messages to the tm1server.log file when a certain condition occurs in your TurboIntegrator (TI) Process. This function has been around since TM1 version 10.2, but I recently came across this function in use with a client, and it prompted me to check out this function again. Let’s explore the functionality and usage of the LogOutput function.

Table of Contents

Syntax of the LOGOUTPUT Function:

This is the syntax of the LOGOUTPUT function:

LogOutput('SeverityLevel', 'MessageString');

Valid values for the ‘SeverityLevel’ argument are: ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’, and ‘FATAL’. The ‘MessageString’ can be any customized message and may include variables defined in the data source or manually created variables within the process.

There is a prerequisite to use this function. You will need to create or edit your tm1s-log.properites file. This file should be located in the same directory as your tm1s.cfg file. Once this file is created or edited, you must restart the database for these changes to get picked up.

If you do not have this file already, you can copy/paste this example provided from IBM. I typically update the two ‘TimeZone’ lines from ‘GMT’ to ‘LOCAL’. This allows the log files to write out all messages in the local server time zone.

log4j.logger.TM1=INFO, S1

# S1 is set to be a SharedMemoryAppender

log4j.appender.S1=org.apache.log4j.SharedMemoryAppender

# Specify the size of the shared memory segment

log4j.appender.S1.MemorySize=5 MB

# Specify the max filesize

log4j.appender.S1.MaxFileSize=100 MB

# Specify the max backup index

log4j.appender.S1.MaxBackupIndex=20

# Specify GMT or Local timezone

log4j.appender.S1.TimeZone=GMT

log4j.logger.Event=INFO, S_Event

log4j.appender.S_Event=org.apache.log4j.SharedMemoryAppender

log4j.appender.S_Event.MemorySize=1 MB

log4j.appender.S_Event.MaxFileSize=100 MB

log4j.appender.S_Event.MaxBackupIndex=1

log4j.appender.S_Event.File=tm1event.log

log4j.appender.S_Event.Format=TM1Event

log4j.appender.S_Event.TimeZone=GMT

Enabling the LOGOUTPUT Function

If you already have this file or are starting with the example provided above, you should only need to add the highlighted line below to enable to use of the LOGOUTPUT function. You may need to adjust this to match your file if it is different from IBM’s example. Remember to restart the database to pick up the changes to the file. You will want to have a tm1s-log.properties file for each database you want to use this function with.

log4j.appender.S1.TILogOutput=DEBUG

Example code added to a TI Process:

Results of the above code outputting to the tm1server.log file:

Testing Possibilities with LOGOUTPUT

The possibilities for testing are unlimited, but here are a few examples to consider:

 1. Testing to see if an Invalid Version is passed into the process.

2. Testing to see if the Scenario parameter is a subcategory of the Live Scenarios consolidation.

3. Testing to see if an Employee ID showed up in the data, but it had not been added to the dimension yet.

Benefits and Applications

By incorporating this useful function into your development workflow, you can add several benefits. Custom messages can be sent to the standard tm1server.log file, allowing for easy identification of certain conditions during data processing. If you read the tm1server.log file into another application for analysis, you can pick up on the TM1.TILogOutput messages as a trigger for notifications when a certain condition is met in your processing of your data. This can help you to proactively correct any issues before users identify them, ensuring smoother operations.

Conclusion

The LOGOUTPUT function in Planning Analytics provides developers with a powerful tool to enhance their TurboIntegrator (TI) processes. By enabling custom messages in the tm1server.log file, developers can streamline issue detection and resolution, ultimately improving the overall efficiency of data processing.

Next Steps

We hope that you found this article to be both interesting and informative. If you have any questions about the LOGOUTPUT function or would like PMsquare to provide guidance and support for your analytics solution, contact us today. Be sure to subscribe to our newsletter for more PMsquare updates, articles, and insights delivered directly to your inbox.