FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

Sentry

Build Status

Welcome to the Sentry Module

This module connects your CFML application to send bug reports to Sentry (https://sentry.io)

LICENSE

Apache License, Version 2.0.

IMPORTANT LINKS

  • Source: https://github.com/coldbox-modules/sentry
  • Issues: https://github.com/coldbox-modules/sentry/issues
  • Account Setup: https://sentry.io
  • Changelog

SYSTEM REQUIREMENTS

  • Adobe ColdFusion 2016+
  • Lucee 5

Instructions

Just drop into your modules folder or use the box cli to install

box install sentry

CFML App Installation

If your app uses neither ColdBox nor LogBox, you can still instantiate the SentryService and use it directly so long as you prep it with the settings it needs.

// Create Sentry service and load it with data
application.sentryService = new modules.sentry.models.SentryService( {
  async : true,
  DSN : 'https://[email protected]/3'
} );

// Send a log message
application.sentryService.captureMessage( 'winter is coming', 'warn' );

// Send an exception
application.sentryService.captureException( exception=cfcatch, additionalData={ anything : 'here' } );

LogBox Standalone Installation

If your app doesn't use ColdBox but does use LogBox, you can use our SentryAppender class in your LogBox config. You'll need to still instantiate the SentryService the same as above, but then you can just use the standard LogBox API to send your messages.

This means if your app already has LogBox calls in place, simply adding the Sentry appender will start sending all those messages to Sentry without any app code changes on your part.

Here is an example LogBox standalone config file

MyLogBoxConfig.cfc

component {
  function configure() {
    logBox = {
      appenders : {
        sentry : {
          class : 'modules.sentry.models.SentryAppender',
          levelMax : 'WARN',
          properties : {
            sentryService : new sentry.models.SentryService( {
              async : true,
              DSN : 'https://[email protected]/3'
            } )                      
          }
        }
      },
      root : { levelMax : 'INFO', appenders : '*' },
      categories = {}
    };
  }
}

Then create LogBox as normal and send your messages:

application.logbox = new logbox.system.logging.LogBox(
	new logbox.system.logging.config.LogBoxConfig( CFCConfigPath="config.MyLogBoxConfig" ) 
);

// Send a log message
application.logbox.getRootLogger().warn( 'winter is coming' );

// Send an exception
application.logbox.getRootLogger().error( message='Boom boom', extraInfo=cfcatch );

// Send an exception plus other stuff
application.logbox.getRootLogger().error( message='Boom boom', extraInfo={ exception: cfcatch, anything: 'here', as : 'well' );

The extraInfo is optional, but if it is a cfcatch object or a struct containing a cfcatch object in a key called exception, the appender will use special treatment of the exception object. Both of the examples above will extract the cfcatch and log to Sentry as an error which contain additional information over a simple text log message.

ColdBox Installation

Lucky you, ColdBox provides you with the "easy street" method of using this module. By just installing the module, the following things will happen automatically for you:

  • The Sentry LogBox appender we showed above will be registered to capture all messages of FATAL or ERROR severity
  • An onException interceptor will be registered to log all errors that ColdBox sees.

The only required configuration is your client DSN or auth keys so we can contact Sentry. This configuration goes in /config/ColdBox.cfc in moduleSettings.sentry like so:

moduleSettings = {
 sentry : {
   async : true,
   DSN : 'https://[email protected]/3'
 }
};

Settings

Regardless of the installation method above, the settings for Sentry are mostly the same. Here is the full list. Note, enableLogBoxAppender, levelMin, levelMax, and enableExceptionLogging are only used in when installing Sentry into a ColdBox app. The default values are shown below. Any settings you omit will use the default values.

settings = {
  // Enable the Sentry LogBox Appender Bridge
  enableLogBoxAppender : true,
  // Min/Max levels for appender
  levelMin : 'FATAL',
  levelMax : 'ERROR',
  // auto-register onException interceptor
  enableExceptionLogging : true,
  // Send messages to Sentry in a thread
  async : true,
  // Don't sent URL or FORM field values of these names to Sentry
  scrubFields : [ 'passwd', 'password', 'password_confirmation', 'secret', 'confirm_password', 'secret_token', 'APIToken', 'x-api-token', 'fwreinit' ],
  // Don't sent HTTP header values of these names to Sentry
  scrubHeaders : [ 'x-api-token', 'Authorization' ],
  // The current release of your app, used with Sentry release/deploy tracking. Ex. "[email protected]"
  release : '',
  // App environment, used to control notifications and filtering
  environment : 'production',
  // Client connection string for this project. Mutually exclusive with next 4 settings
  // Get this from the "settings" page on a project under "Client Keys (DSN)" 
  DSN : '',
  // Sentry public client key for this project. (Not needed when using DSN)
  publicKey : '',
  // Sentry public client key for this project (Not needed when using DSN)
  privateKey : '',
  // Sentry projectID (Not needed when using DSN)
  projectID : 0,
  // URL of your Sentry server (Not needed when using DSN)
  sentryUrl : 'https://sentry.io',
  // name of your server
  serverName : cgi.server_name,
  // Default logger category. LogBox appender will pass through the LogBox category name 
  logger : 'sentry',
  // Closure to return dynamic info of logged in user which will appear in Sentry error reports under "User".
  // No args are passed to the closure when used outside of a ColdBox app. 
  userInfoUDF : function( event, rc, prc ){
    return {
      // Standard user data Sentry looks for
      id : 123
      username : 'bwood',
      email : '[email protected]',
      // Anything else you want
      cool : true,
      memberType : 'platinum'
    };
  }
}

Credit

This project is based on the fine open source work of others.

  • https://github.com/GiancarloGomez/sentry-cfml
  • https://github.com/jmacul2/raven-cfml

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.ortussolutions.com


HONOR GOES TO GOD ABOVE ALL

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. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

CHANGELOG

1.0.0

  • Create first module version

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Download
1.3.18-snapshot May 17 2019 01:46 PM May 17 2019 01:46 PM Ortus Solutions (ortus)
1.3.17+80 May 17 2019 01:45 PM May 17 2019 01:45 PM Ortus Solutions (ortus)
1.3.17-snapshot May 17 2019 12:04 PM May 17 2019 12:04 PM Ortus Solutions (ortus)
1.3.16+72 May 17 2019 12:04 PM May 17 2019 12:04 PM Ortus Solutions (ortus)
1.3.16-snapshot May 17 2019 12:10 AM May 17 2019 12:10 AM Ortus Solutions (ortus)
1.3.15+67 May 17 2019 12:09 AM May 17 2019 12:09 AM Ortus Solutions (ortus)
1.3.15-snapshot May 16 2019 10:40 PM May 16 2019 10:40 PM Ortus Solutions (ortus)
1.3.14+63 May 16 2019 10:40 PM May 16 2019 10:40 PM Ortus Solutions (ortus)
1.3.14-snapshot May 16 2019 05:54 PM May 16 2019 05:54 PM Ortus Solutions (ortus)
1.3.13+61 May 16 2019 05:53 PM May 16 2019 05:53 PM Ortus Solutions (ortus)
1.3.12-snapshot May 16 2019 12:34 AM May 16 2019 12:34 AM Ortus Solutions (ortus)
1.3.11+55 May 16 2019 12:33 AM May 16 2019 12:33 AM Ortus Solutions (ortus)
1.3.11-snapshot May 15 2019 11:02 PM May 15 2019 11:02 PM Ortus Solutions (ortus)
1.3.10+52 May 15 2019 11:00 PM May 15 2019 11:00 PM Ortus Solutions (ortus)
1.3.10-snapshot May 15 2019 05:28 PM May 15 2019 05:28 PM Ortus Solutions (ortus)
1.3.9+48 May 15 2019 05:28 PM May 15 2019 05:28 PM Ortus Solutions (ortus)
1.3.9-snapshot May 15 2019 05:08 PM May 15 2019 05:08 PM Ortus Solutions (ortus)
1.3.8+45 May 15 2019 05:08 PM May 15 2019 05:08 PM Ortus Solutions (ortus)
1.3.8-snapshot May 15 2019 03:07 PM May 15 2019 03:07 PM Ortus Solutions (ortus)
1.3.7+40 May 15 2019 03:07 PM May 15 2019 03:07 PM Ortus Solutions (ortus)
1.3.7-snapshot May 15 2019 01:39 PM May 15 2019 01:39 PM Ortus Solutions (ortus)
1.3.6+37 May 15 2019 01:38 PM May 15 2019 01:38 PM Ortus Solutions (ortus)
1.3.6-snapshot May 14 2019 03:33 PM May 14 2019 03:33 PM Ortus Solutions (ortus)
1.3.5+33 May 14 2019 03:33 PM May 14 2019 03:33 PM Ortus Solutions (ortus)
1.3.5-snapshot May 13 2019 11:11 PM May 13 2019 11:11 PM Ortus Solutions (ortus)
1.3.4+30 May 13 2019 11:11 PM May 13 2019 11:11 PM Ortus Solutions (ortus)
1.3.4-snapshot May 13 2019 05:40 PM May 13 2019 05:40 PM Ortus Solutions (ortus)
1.3.3+27 May 13 2019 05:40 PM May 13 2019 05:40 PM Ortus Solutions (ortus)
1.3.3-snapshot May 13 2019 04:00 PM May 13 2019 04:00 PM Ortus Solutions (ortus)
1.3.2+24 May 13 2019 04:01 PM May 13 2019 04:01 PM Ortus Solutions (ortus)
1.3.2-snapshot May 11 2019 07:08 PM May 11 2019 07:08 PM Ortus Solutions (ortus)
1.3.1+19 May 11 2019 07:03 PM May 11 2019 07:03 PM Ortus Solutions (ortus)
1.3.1-snapshot May 11 2019 06:30 PM May 11 2019 06:30 PM Ortus Solutions (ortus)
1.3.0+16 May 11 2019 06:26 PM May 11 2019 06:26 PM Ortus Solutions (ortus)
1.3.0-snapshot May 11 2019 06:22 PM May 11 2019 06:22 PM Ortus Solutions (ortus)
1.2.0+13 May 11 2019 06:22 PM May 11 2019 06:22 PM Ortus Solutions (ortus)
1.2.0-snapshot May 10 2019 06:01 PM May 10 2019 06:01 PM Ortus Solutions (ortus)
1.1.1+11 May 10 2019 06:22 PM May 10 2019 06:22 PM Ortus Solutions (ortus)
1.1.0+8 May 10 2019 05:57 PM May 10 2019 05:57 PM Ortus Solutions (ortus)
1.1.0-snapshot May 10 2019 05:00 PM May 10 2019 05:00 PM Ortus Solutions (ortus)
1.0.0+4 May 10 2019 04:59 PM May 10 2019 04:59 PM Ortus Solutions (ortus)
1.0.0-snapshot May 10 2019 04:51 PM May 10 2019 04:51 PM Ortus Solutions (ortus)

 

No collaborators yet.
     
  • May 10 2019 04:51 PM
  • May 17 2019 01:46 PM
  • 207
  • 56
  • 155