Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
There are two major improvements we did with LogBox in this release:
1) The file locking operations on file appenders have been streamlined to avoid high i/o operations.
2) The console appender uses an asynchronous streaming technique which makes it extremely efficient and fast.
[LOGBOX-34] - Console appender completely rewritten to support asynchronous streaming
[LOGBOX-33] - Improve file exists usage on file appenders to avoid i/o operations
LogBox is a standalone enterprise ColdFusion (CFML) logging library designed to give you flexibility, simplicity and power when logging or tracing is needed in your applications. LogBox is also part of the ColdBox Platform suite of services and libraries and allows you to easily build upon it's logging framework in order to meet any logging or reporting needs your applications has. LogBox surpasses ColdFusion's very basic cflog
tag. LogBox allows you to create multiple destinations for your loggings and even configure multiple destinations or change them at runtime.
And constructed with the following guidelines:
Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch
Copyright by Ortus Solutions, Corp
ColdBox is a registered trademark by Ortus Solutions, Corp
Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.
Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews
Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.
"Therefore being justified by **faith**, we have peace with God through our Lord Jesus Christ: By whom also we have access by **faith** into this **grace** wherein we stand, and rejoice in hope of the glory of God." Romans 5:5
The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.
The majority of code examples in this book are done in cfscript
.
The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -
All ColdFusion examples designed to run on the open soure Railo Platform or Adobe ColdFusion 9.0.2+
Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Railo is a trademark and copyright of Railo Technologies, GmbH.
The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.
We highly encourage contribution to this book and our open source software. The source code for this book can be found in our where you can submit pull requests.
15% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.
Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.
We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.
LogBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.
You can find the release version information here:
Bug
[] - Truncating of category data to avoid error on insertion on DB Appender
Improvement
[] - deprecate logbox xml support
New Feature
[] - Ability to asynchronize any logger via new 'async' property
Almost every application needs logging and/or tracing capabilities and we have developed LogBox to satisfy these needs. Although you should take care not to over-use logging as it can slow down an application, LogBox offers you the capabilities to filter out or cancel logging noise a-la-carte. LogBox was inspired by the original logging capabilities in ColdBox and in the project.
LogBox is maintained under the guidelines as much as possible.Releases will be numbered with the following format:
The ColdBox Platform, LogBox is open source and licensed under the License.
The LogBox help and discussion group can be found here:
We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us:
By Email:
By Jira:
ColdBox is a professional open source software backed by offering services like:
Official Site:
Source Code:
Bug Tracker:
Twitter:
Facebook:
Google+:
Vimeo Channel:
Shalom Children’s Home () is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children werecame on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.
Most applications require logging and tracing capabilities. One can usually use ColdFusion's standard cflog
or cftrace
tags but you can reach a limitation very fast.
What if you needed to log only certain severity levels for a particular CFC or piece of code?
What if you needed that severity to advise you via SMS or Twitter (yes Twitter)?
What if you wanted to turn it off easily or reconfigure your logging levels?
You would have to build all of these advising and logging capabilities yourself. Also, inserting log statements is tedious, time consuming and frequently pollutes your real code. You can understand the pain and complexity required to properly deal with these situations. These reasons (and more) are why the ColdBox team has invested in building LogBox.
This is a major release and a major rewrite of the entire framework to modern CFML, optimizations and script modes.
We have also improved all appenders for performance and reliability. Especially, the file logging facilities have been drastically improved. The new file based appenders now rely on a queuing mechanism and listener watcher threads that stream content to the file repositories.
LogBox is the core framework you need to instantiate in order to work with logging in your application. You have to instantiate it with a LogBoxConfig
object that will hold your logging configurations. After the library is instantiated and configured you can ask from it a named Logger object so you can start logging or tracing messages.
You have two ways to use LogBox:
Standalone Framework
Within a ColdBox application
If you have downloaded LogBox as a standalone framework, then the initial namespace for the core is logbox.system
. This allows you to use logbox as a standalone framework that is integrated into your proprietary application.
The ColdBox Framework already has an instance of LogBox created for you in every application and it is stored in the main application controller: controller.getLogBox()
. The namespace within the ColdBox framework is coldbox.system
.
No matter what configuration you decide to use, you will always have to instantiate LogBox with a LogBoxConfig
object: logbox.system.logging.config.LogBoxConfig
. However you have the option of either talking directly to this CFC or creating a more portable configuration. This portable configuration we denote as a simple data CFC that contains the LogBox configuration data using what we call our LogBox DSL (Domain Specific Language).
The cool thing about this LogBox DSL is that it is exactly the same whether you are using LogBox in ColdBox applications or in any other framework or non-framework ColdFusion application. So you can configure LogBox by:
Creating a portable data CFC using the LogBox DSL or
Creating the LogBoxConfig
object and interacting with its methods
We have a convention for our category names where each category name uses dot-notation according to the components path. Using a class-path convention for our category names allows one to pseudo-inherit for logging levels and appenders! The following example should help clarify this concept.
The overall premise is that when you request a logger with a category name LogBox will search for it's configuration. If LogBox does not find a configuration for the category name it will try to locate its closest ancestor for logging levels and appenders. If LogBox cannot find an ancestor the message will be logged using the root logger information. For example, let's say we define some appenders like this:
And some categories like this:
Then, let's say we request the following logger objects and logged some info:
Information All example code snippets are using a
getLogger( "categoryname" )
call instead of our preferred approach ofgetLogger( this )
because we want to showcase which category we are talking about. Please take this into consideration.
Since we requested the category: coldbox.system.plugins.BeanFactory
, LogBox tries to locate it, but it has not been defined, so it takes off the last item in the category name. Now it will search for a category of: coldbox.system.plugins
via pseudo-inheritance. However, now coldbox.system.plugins
has been found and it has been configured to only listen to error
messages. Therefore, the coldbox.system.plugins.BeanFactory
logger can ONLY log error messages according to it's inherited category. So the info()
message will be ignored, and the error()
message will be sent to both the FileAppender and the ConsoleAppender!
The second logger is called coldbox.system.interceptors.SES
, LogBox tries to match a category but fails, so it now searches for a logger called coldbox.system.interceptors
. It still cannot find it so it continues up the package chain and finds the coldbox.system
logger which has been set with a minimum of INFO
level and ONLY the console appender. So the messages that get logged is the logger.info()
and the logger.debug()
message and they will be sent to the console appender.
These examples should give you insight into category inheritance and the power they provide. You can easily turn toggle logging for entire packages with a single category definition. However, this is great only if you follow the dot notation conventions. Below is a sample generic chart sample:
LogBox can handle the inserting of logging and/or tracing statements in your application with a simple to use API while providing you the ability to manage logging behavior outside of your application code.
You can configure LogBox via a programmatic configuration file (cfc)
LogBox categorizes your logging and/or tracing statements according to user-defined categories that can be configured at runtime or pre-runtime. All of these categorizations can have their own logging level ranges (such as debug or info) and even their own destination points or what we refer to as LogBox Appenders (such as Console).
LogBox Appenders are the destination points you configure for your logging and/or tracing statements. LogBox also offers a basic extensible API so you can build and extend upon the Appender framework according to your unique logging or tracing needs. This gives you complete control and flexibility of how to expand LogBox without reinventing the wheel. Some appenders included in LogBox can log to the following destinations: File, Database, Sockets, Email, ColdFusion logging, System Console, and much more.
LogBox facilitates the creation of your very own customized message formats via Layouts. You can create a Layout component that can be configured in to ANY LogBox appender so it can spit out your very own customized messages.
LogBox can be instantiated as many times as you want and used as many times as you like in a single application. There are no restrictions upon its usage.
LogBox allows for category inheritance according to component and package conventions.
Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in Rancho Cucamonga, California with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!
He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com
Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:
He played volleyball in the Salvadorean National Team at the tender age of 17
The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)
His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)
He has a geek love for circuits, microcontrollers and overall embedded systems.
He has of late (during old age) become a fan of running and bike riding with his family.
Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!
“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5
Jorge is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in persuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.
Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Cristian who loves to play the guitar, worship and rejoice in the Lord!
Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17
LogBox can be downloaded as a standalone framework or it is included with the latest ColdBox Platform release. The main difference between both versions is the instantiation and usage namespace, the rest is the same.
The best way to install LogBox is using CommandBox CLI and package manager.
ColdFusion 11+
Lucee 4.5+
If you are using LogBox within a ColdBox application context, then LogBox is part of the platform. Just install ColdBox normally. If you are using LogBox standalone, just drop LogBox in your application root or create a mapping called logbox
that points to the installation folder. If you can run the following snippet, then LogBox is installed correctly:
You can leverage to install the standalone version of LogBox
Standalone
logbox.system.logging
ColdBox
coldbox.system.logging
Info In this book we will be using the standalone namespace for all examples.
Category
Configured Levels
Assigned Levels
Appenders
root
FATAL-DEBUG
FATAL-DEBUG
console,file
coldbox.system
INFO-DEBUG
INFO-DEBUG
console
coldbox.system.plugins
ERROR
ERROR
*
coldbox.system.interceptors.SES
coldbox.system.interceptors.SES
INFO-DEBUG from coldbox.system
console from coldbox.system
coldbox.system.plugins.BeanFactory
NONE
ERROR from coldbox.system.plugins
*
Category
Configured Levels
Assigned Levels
root
FATAL-DEBUG
FATAL-DEBUG
x
NONE
FATAL-DEBUG from root
x.y
INFO
INFO
x.y.z
NONE
INFO from x.y
The methods shown below are used to add categories to specific severity levels only. Each method can receive 1 to * category arguments.
public void debug()
public void info()
public void warn()
public void error()
public void fatal()
public void off()
LogBox has four main components:
LogBox
Logger
Appenders
Layouts.
These four (4) components work in unison to deliver the logging and tracing of messages and to control how they are logged. You will mostly interact with the Logger component as it will send your statements to the Appenders you have configured. Users can extend LogBox and build their own appenders and layouts.
Configuring a root logger is mandatory for LogBox. This is very easy and just a few arguments.
Name
Description
levelMin
The default minimum log level for the root logger. (OPTIONAL. Defaults to 0 [FATAL].)
levelMax
The default maximum log level for the root logger. (OPTIONAL. Defaults to 4 [DEBUG].)
appenders
A list of appenders to configure the root logger with. Use *
to add all registered appenders
The layout component defines the format of the message to store in an appender repository. Be default, each appender already has a pre-defined message format. However, if you do not like the format of the message you can easily change it by creating your own layout component and registering it with the appender. You can do this in the configuration object when you add appenders:
Note: Not all appenders use a layout object (e.g. the
DBAppender
).
So to create your very own layout object, you just need to extend the LogBox abstract layout object: logbox.system.logging.Layout
and implement the format()
method.
Property
The ConsoleAppender takes no additional properties.
This appender logs using Java's System.out.println
function. Logs will appear in the directory specificied in your CF or Lucee Administrator.
Once you have created and configured the LogBox library, you can interact with it in order to get logger objects. The main methods you will use to interact with LogBox are the following, but I recommend you look at the CFC api (http://www.coldbox.org/api) in order to get a listing of all available methods.
Method
Description
LogBoxConfig getConfig()
Get the config object registered
Logger getLogger(any category)
Get a named logger object using a category string or the object you will log from
Logger getRootLogger()
Get a reference to the root logger
string getVersion()
Get the current version of LogBox
string getCurrentAppenders()
Get a list of currently registered appenders
string getCurrentLoggers()
Get a list of currently instantiated loggers
void configure( LogBoxConfig config )
Dynamically re-configure the LogBox library
The two most important methods are getRootLogger() & getLogger()
, which you will use to get the root or named logger objects.
Caution: When you ask for a named category logger and LogBox cannot find its definition, it will create a logger that will inherit its logging levels and appenders from the root logger.
Property
Type
Required
Default
Description
subject
string
true
---
Get's pre-pended with the severity and category field.
from
string
true
---
The from email address
to
string
true
---
The to email(s)
cc
string
false
empty
The cc email(s)
bcc
string
false
empty
The bcc email(s)
mailserver
string
false
empty
The optional mail server
mailusername
string
false
empty
The optional mail username
mailpassword
string
false
empty
The optional mail password
mailport
int
false
25
The optional mail port
useTLS
boolean
false
false
Use the Transport level security setting in the cfmail tag.
useSSL
boolean
false
false
Use SSL or not
When using any of the logging methods like info()
, debug()
, warn()
, etc, they all take two arguments:
The message to log
An extraInfo
argument which can be anything you like.
This extrainfo
argument can be a simple value, a CFC, a complex object and pretty much anything you like. The appenders get this extraInfo
argument and process it into their appropriate destinations by serializing its value. This is done by using the following algorithm:
If it is a simple value, then just use it.
If it is an object then check if the object has a method called $toString()
. If the method exists, then call $toString()
and use its return value.
If it is an object with no $toString()
method, then marshall its representation into XML format.
If it is a complex variable like a struct, query, array, etc, then marshall it into JSON format.
As you can see from the algorithm above, you can use the extraInfo
argument to your benefit to save serialized representations of data to the appenders and then retrieve or re-inflate them later. The $toString()
convention is great because you have complete control on how a CFC will serialize to its string representation. Let's see an example on a simple CFC:
So when this object is sent to a logger's method, it will detect it is an object and the $toString()
function exists and call it for serialization.
An appender is an object that LogBox uses to log statements to a destination repository. All appenders act as destinations that can include: databases, JMS, files, consoles, sockets, etc. The appender has the responsibility of taking the logged message and persisting the message or sending the message to an external service. LogBox comes bundled with the following appenders that can be found in the package coldbox.system.logging.appenders
:
Asynchronous Appenders
You may wish your logs to be asynchronous. You can do so by passing an async
property in your configuration. ( This happens at the logger
level and is available to all appenders out of the box, even ones that you create yourself!
You can configure LogBox to use one or all of these appenders at any point in time. You can even register as many instances of any appender by defining a unique name for each. Here are examples of how one can configure appenders programmatically or via the simple configuration CFC:
Programmatic Approach
Configuration CFC approach
Another feature of a LogBox appender is that you can extend
them or create new ones simply by leveraging the LogBox API. To customize LogBox appenders for your own unique needs you would simply extend the core appender class: coldbox.system.logging.AbstractAppender
and implementing the init()
and logMessage()
methods. Extending LogBox will be reviewed in greater detail over the next few sections.