https://github.com/oarevalo/BugLogHQ
BugLogHQ is a tool to centralize the handling of automated bug reports from multiple applications. BugLogHQ provides a unified view of error messages sent from any number of applications, allowing the developer to search, graph, forward, and explore the bug reports submitted by the applications.
Copyright 2009-2013 - Oscar Arevalo (http://www.oscararevalo.com)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
About BugLogHQ
Release Notes
Integrating BugLogHQ into your Applications
BugLogHQ Interface
Installation and Usage Notes:
Supported Databases
Acknowledgements / Thanks / Credits
Bugs, suggestions
Using BugLog with Non ColdFusion Applications
CORS
BugLogHQ is a tool to centralize the handling of automated bug reports from multiple applications. BugLogHQ provides a unified view of error messages sent from any number of applications, allowing the developer to search, graph, forward, and explore the bug reports submitted by the applications. All bug reports received by BugLogHQ are stored on a normalized database, thus providing the option to the developers to further extend the application to leverage this information.
Applications can send bug reports to BugLogHQ via three different ways:
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. The client cfc requires at least a CFML engine compatible with Adobe ColdFusion 8.
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 takes three parameters:
The bugLogListener parameter can be any of:
/bugLog/listeners/bugLogListenerWS.cfc
(to submit the report using a webservice), /bugLog/listeners/bugLogListenerREST.cfm
(to submit as an http post)/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
To access the BugLogHQ interface, go to /bugLog/
on your bugLog server; the interface is password protected. The default username and password is: admin / admin. From here you can have an overview of every bug report that has been received. Everything is pretty self-explanatory, and there are lots of things you can click to visualize the data in different ways.
NOTE: If you want to install bugLog on a location other than the default (/bugLog/), you will need to update the setting general.externalURL
with the path to where you installed BugLog. The path must always end with a "/". Examples: "/", "/mybuglog/", "/bugtrackingthingy/", etc.
NOTE: The BugLogHQ webapp requires a CFML engine compatible with at least Adobe ColdFusion 9; however it can receive bug reports from any version of CFML engines (or pretty much anything that can make an HTTP post)
Run the corresponding SQL script for your database. The script can be found in the /install
directory. This will create the necessary tables.
By default bugLogHQ uses a datasource named "bugLog" with no password, to change this go to:
/bugLog/config/buglog-config.xml.cfm
Change the <setting />
tags for:
db.dsn: datasource name as defined in the CF administrator (by default is bugLog)
db.dbtype: database type. Can be mysql, mssql (for Microsot SQL Server), pgsql (for PostgreSQL) or oracle. The default is mysql
db.username: username for the datasource (if needed)
db.password: password for the datasource (if needed)
To access the bugLogHQ interface, go to /bugLog. The default username/password is:
username: admin password: admin
IMPORTANT: To change the admin password or to create additional users click on the "Settings" link on the upper right corner of the screen.
TIP: Changing the setting general.externalURL
in the main config you can tell BugLog the URL to use when referring to itself. By default buglog will try to guess it from the CGI scope, but in some cases you may want to override this. For example if you have a clustered deployment. This value can be either a relative path starting with "/", or a full URL (i.e. "http://www.someserver.com/bugLog/")
After installation use your browser to go to /bugLog/test
and follow the links to test both the client and server side of buglog.
You can override any setting on the main config on a per-environment basis. To determine which is the current environment, BugLog will look for a file named severkey.txt
on your /bugLog/config
directory. This file should only contain a single word that is used to name the environment. For example: "dev" or "prod-server-1" or something like that.
Then on your buglog-config.xml.cfm add an <envSettings />
section like the following example:
<envSettings name="dev">
<setting name="db.dsn">bugLog_dev</setting>
<setting name="general.adminEmail">devteam@somedomain.org</setting>
</envSettings>
Where the "name" attribute of the envSettings tag must match what you provide on your serverkey.txt file. Inside you can place any number of <settings/>
tags you want. These will override the settings of the same name defined on the general part of the config.
You can have as many <envSettings/>
sections as you want. However only one will be used (the one that matches your serverkey.txt).
If none matches the serverkey, then BugLog will use the default settings.
An alternative way of providing the "serverkey" value is by using a Context Parameter. The advantage is that this method does not require you to add any new files to your BugLog installation. Of course, this only works if you have access to the config files of your application server.
For example in Tomcat, to set your serverkey as "dev", you would set a context parameter by editing "{Tomcat Path}/conf/context.xml"
like this:
<Context>
...
<Parameter name="serverkey" value="dev" override="false" />
...
</Context>
To create a new instance, just create a new directory under the webroot with the name you want for your neq instance (i.e. "/buglogdev").
On the new directory copy the contents of /bugLog/install/named-instance-template.
NOTE: don't copy the directory itself, only its contents.
Change the new Application.cfc to properly name your application, and modify the config/buglog-config.xml.cfm
on your new instance to set its appropriate configuration (datasource, etc).
After that you can just go to /buglogdev (in this case) to access your new instance.
To submit bugs to this instance, just point your buglog client to /buglogdev/listener.cfm
Currently BugLogHQ supports the following databases:
IMPORTANT: Make sure you enable CLOB/BLOB support on the CF datasource settings in the ColdFusion Administrator, otherwise your bug reports might get truncated.
There is now a Google Groups for the BugLogHQ project. Use them to ask any questions, ask for help if you get stuck, or if you have any contributions that you would like to share.
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 /client folder you can find basic versions of PHP, Python and JavaScript clients that can be used to have an easier integration between your applications and BugLog. Please note that this scripts are on an "experimental" state, so they are a bit more simpler than the CFML version. They also use only the REST listener, not the SOAP one.
When using the REST endpoint, you have the option to provide a bit of additional security by providing a CORS configuration.
To enable CORS, you must have the following entries on your config/buglog-config.xml.cfm
file:
<setting name="cors.enabled">true</setting>
<setting name="cors.allowOrigin">*</setting>
The * in allowOrigin
tells that any domain is accepted for requests, however you may change this to a more restrictive value if desired.
Additionally, you may use the following optional settings for more specific configurations:
<setting name="cors.allowMethods"></setting>
<setting name="cors.allowHeaders"></setting>
<setting name="cors.allowCredentials"></setting>
<setting name="cors.maxAge"></setting>