Rules and Rule Definitions

Creating HOW and WHERE cfScribe sends the log

Rules and Rule Definitions work together to determine the routing of a log. Both are set as part of the cfScribe configuration and both need to be present to make the system work.

Rules are contained in a struct and describe where the routing should go. It is essentially a decision tree that is represented as a struct.

Rule Definitions are contained in an array and tell cfScribe what the criteria are for logging and in what order to apply them.

For example, if our Rule Definitions are as follows:

[ "env:environment"]

that would indicate that first cfScribe would evaluate the environmental variable "environment", which would be set in the .env file, and use that to extract nodes from the rules structure. If the environment is "production" and the corresponding Rules structure is:

{ 
    "production" : [ "console", "sentry" ],
    "development" : [ "screen" ], 
    "testing" : [ "screen" ] 
}

cfScribe would send the log to the "console" and "sentry" appenders.

CFScribe will continue to evaluate the definitions and rules until it gets to the end of the rule definitions with a few key points:

• If it comes to an array in the rules structure, it will assume that the contents are appenders and send the log to those endpoints and then continue to evaluate the rule definitions.

• If there is no node for a given rule definition, it will be ignored. This means that there is no need to create "empty" nodes in order to prevent an error. See the example below

Rule Definitions:

[
  "headerTrueFalse: myHeader",
  "env:environment",
]

Rules:

{ 
    "true": ["screen" ],
    "false" : {
        "production" : [ "console" ],
        "development" : [ "screen" ],
        "testing" : ["screen"]
    }
}

In this scenario, cfScribe first checks for the existence of the header "myHeader" then what the environment is. If the header is present, it will send the error to the screen no matter what. If the header is not present, it will then route according to the environment.

Built In Rule Definitions

env:varname - is the equivalent of createObject( "java", "java.lang.System" ).getEnv()[varname]

coldbox : varname - a key from the ColdBox variables

config:varname - a key from the ColdBox config variables

moduleConfig:varname@modname - returns the varname property from the modulename module

header:headerName - returns the value from the headername header

headerTrueFalse:headerName - returns whether the header exists or not. Note: a blank header value will return false

severity:severity - Returns the value of the submitted severity value.