Using BugLogHQ

BugLogHQ is meant to be used on a client/server or distributed model. The idea is that you have one BugLogHQ server that receives bug reports from any number of other applications, which may live on their own servers.

Each application can send bug reports via three different ways:

• Web Service call (SOAP)
• Regular HTTP Post (via url/form parameters or a Json encoded body)
• Direct CFC call (only works if the app and BugLog are on the same server)

Using plain HTTP to communicate, allows BugLogHQ to be integrated with applications running on any language or platform. Applications that report to BugLogHQ do not even need to be web-based applications!

Integrating with CFML Applications

BugLogHQ provides a CFC that can be used to send the bug reports. This CFC is located in /bugLog/client/bugLogService.cfc. This is the only file that needs to be distributed with any application that wants to submit reports to BugLogHQ.

You may instantiate and keep the instance of this CFC in some a scope such as Application and then just call the notifyService() method in it whenever the application needs to submit a bug report.

To initialize the bugLogService, call the Init method. This method is used to configure the client, and takes multiple arguments, however the main ones are:

• bugLogListener: The location of the listener where to send the bug reports
• bugEmailRecipients: A comma-delimited list of email addresses to which send the bug reports in case there is an error submitting the report to the bugLog listener.
• bugEmailSender: The sender address to use when sending the emails mentioned above.

The bugLogListener parameter can be any of:

• WSDL pointing to /bugLog/listeners/bugLogListenerWS.cfc (to submit the report using a webservice),
• Full URL pointing to /bugLog/listeners/bugLogListenerREST.cfm (to submit as an http post)
• path to /bugLog/listeners/bugLogListenerWS.cfc in dot notation (i.e. bugLog.listeners.bugLogListenerWS)

If an error occurs while submitting the report to the listener, then bugLogService will automatically send the same information as an email to the addresses provided in the init() method.

TIP: Check the file /bugLog/test/client.cfm for an example of how to use the bugLog client CFC

Data Sanitization/Cleanup

BugReports can include any additional data you wish to send, so it is possible to be on a situation in which unwanted/sensitive data is sent to your BugLogHQ server. For example, including a dump of the form scope on your bug report may end up sending passwords or credit cards, or any other piece of data that is not a good idea to have unsecured.

To prevent this, the BugLog client provides two additional arguments to the init() method:

• sensitiveFieldNames: This is a list of struct keys whose values will be excluded when composing the bug report. For example, you may have things as "password" or "credit_card_number". By default this is empty, so it is up to each application to determine what keys are required to be excluded.

• sanitizeExpressions: This is an array of regular expressions which will be removed/replaced from the entire generated output. Each item can be either a simple value or a struct with the elements 'expr' and 'replace'. Out of the box the BugLog client excludes any Javascript code, credit card numbers and S3 passwords.

Checkpoints

The BugLogHQ client allows the caller application to keep track of 'checkpoints' or milestones on a request, so that if an exception occurs and a bug is sent to the server, it can include a list of which checkpoints (and their timing) were reached before the error happened.

To mark a checkpoint the instance of the BugLog client needs to be available at any point. The best practice is to keep the instance on a persistent scope such as the Application scope, so this should not be a problem. Whenever you want to mark a checkpoint, just call the checkpoint() method. This method takes a single string as argument, to use as a checkpoint label.

Checkpoints are stored only for the duration of the request and then discarded.

---

Using BugLog with Non-CFML Applications

Since BugLog listens for bug reports through standard protocols via HTTP (REST and SOAP), you can use it to aggregate bug reports from any application, not just ones made in CFML. An application just needs to point to the right listener endpoint and pass the necessary parameters.

On the /bugLog/client folder you can find a few client-side libraries in multiple languages that can be used to have an easier integration between apps and BugLog.

In the clients folder you will find BugLogHQ clients for:

• CFML
• Python
• PHP
• Javascript

NOTE: If you have experience with other languages, please consider forking the BugLogHQ repo and contributing a new client library.