Inside Brightspot's packaged debugging tools

Brightspot's Background Tasks tool, as the name implies, lists all miscellaneous tasks (as well as periodic caches) that your instance of Brightspot has running in the background. These tasks might be back-end Brightspot tasks or those related to integrations that a Brightspot instance has configured. Having all of them listed out in a centralized location helps developers understand what tasks are running, when they last ran, and perhaps most importantly, their last exception (which can serve as an indicator if an error is discovered). Every task can be paused, resumed, or stopped altogether at the developer's discretion.
As for periodic caches, maybe there's a piece of data that a developer wants to calculate every five seconds—but it can be expensive to do so. With a tool like this, a developer can run that calculation behind the scenes and store the result in memory. Because it's on a cycle, as the data in the database changes, the value will refresh and remain reasonably up to date.

Without the Background Tasks tool, developers would likely rely on logging statements that come with the system they're using; however, this can be a little removed from the developer. Not an issue for developers working with Brightspot, though, thanks to this tool. A developer can get a quick overview in a centralized location.

Speaking of, if a developer happens to be in Brightspot and needs to check background tasks, this is also possible to do inside the CMS in the Developer menu.

Also handy for debugging is the Build Information tool. Often, developers want to know the current version of the the software they're using. The Build Information tool tells them. Not only that, but the tool also lists out the versions of each plugin—third-party or otherwise—that their instance has installed.

The Build Information tool also provides a widget that lists the most recent Github commit messages and a full MD5 hash of every file inside of the .war file for a build, allowing developers to double check that everything they think is in the current build is, in fact, in the current build. Developers are then also able to break the data down by different modules that are installed, so they will be able to see commits to an individual module, like analytics, for example.

Much like the aforementioned Background Tasks tool, build information is also accessible from inside the CMS, giving the developer another quick path to this information depending on whichever context they are already in.

The Settings tool aggregates not only every setting that is configured directly for a developer's instance of Brightspot, but also every setting configured on the server itself. Developers can easily differentiate between Brightspot-specific settings and other settings. What makes the Settings tool unique, though, is that for any given setting, developers can click a link to dig down in real time to the exact code where that setting is being used, preventing them from having to rely on documentation that may not be up to date.

The Database Query tool is helpful since Brightspot is built on an underlying abstraction layer (Dari). This abstraction layer helps make Brightspot as powerful and user-friendly as it is; however, as a result, the traditional process of running queries against the database becomes less straightforward. The Database Query tool makes it more so by giving developers a toolkit to look into the abstraction.
A developer who wants to look at the article content type can run a query and look at the all of the raw data, whether that data is coming from MySQL, Solr, or anything else. They may already have a tool they are already using to query databases, but due to the abstraction layer, those tools wouldn't be as useful. As a result, Brightspot provides this tool to bridge that gap.

If a developer is already in Brightspot and doesn't want to change context, this tool—much like the Background Tasks and Build Information tools—have been put into the CMS for easy access as well.

Of course, Brightspot still provides a view into the actual underlying MySQL or Solr if a developer wants to go that deep.

The Statistics page, as one would expect, lays out information about throughput and latency, but it also lists different response codes throughout your system. If a developer is running Brightspot locally and sees an abundance of 404 errors, or maybe the response time is particularly high, this Statistics tool is helpful by providing a way to look into the code in real time and ensure it is running as expected.

The Database Schema Viewer tool gives developers an easy look into data models and the relationships between things. Not only that, but Java developers can actually make changes to the code from the Database Schema Viewer tool.

Notice in the screenshot how there is a hyperlink included on the page. This brings the developer to another Dari tool—the Code Editor—that allows them to edit the source code. That means that a developer can change a data model and save it, and then when they refresh, Brightspot will detect and reflect that change. This change is also reflected in the developer's IDE where they are writing the code. The Schema, too, will reflect the change.

Any JavaScript developers reading this may not be all that impressed—they can execute code whenever they want by opening up a browser's inspector tool; however, this isn't always as easy to do with Java code.

On any front-end page, Brightspot also offers some front-end oriented features that may assist developers during their day-to-day. URL parameters, for example, can be added to any Brightspot page that spit back information, like _renderer=json, which gets the JSON version of a particular page (versus its HTML).

Another handy parameter is _debug=true which reloads the page with a Profiler tool that a developer can click on to open a list view of everything that is happening to render and process the page, including but not limited to CDN fetching, database reads, handlebar renderings, text localization, underlying SQL queries, and more, as well as how many times they ran, their length, etc.

Every single event that occurred on the page is listed. This list isn't finite, either, since a developer might want to create their own events—maybe part of their code needs to make an API call to a third-party service, and it's doing that on the server. The developer can have that event show up in this list and thereby better understand the performance implications of it.
One handy use for the profiler is in situations where a slow query is detected. Slow queries are notoriously difficult to fix because while an Ops team can record them at the database level in MySQL, they can't always connect them to the code base from where they came. As a result, there's a gap between Ops reporting slowness and the developer who wrote the code.

Not the case here—Brightspot automatically inserts a comment in every query which includes file names and line numbers, which would be visible to the Ops team in their slow query log. In most other systems, the Ops team would only see the query itself, not where it lives in the code.