We are happy to announce that with Eclipse Neon.0 every project (not just eclipse.org projects) can now sign-up to receive error reports for their plug-ins.
To support that, the Eclipse Automated Error Reporting Client (AERI) has undergone a major rewrite. As of 2.0.0 it offers a new server extension point where plugins can register themselves as interested parties for error log events.
To ensure a consistent UI where it is always transparent to the user to which party his error reports will be sent, AERI allows projects to customize their icons and labels. The rest of the entire UI is fixed.
Tip! You can use AERI in your own custom Eclipse RCP applications. There you can of course completely customize the UI workflows as needed. Check out AERI examples to see how to set up AERI for an in-house Eclipse RCP application. The figure below gives a brief example how your extension should look like. The extension point is named org.eclipse.epp.logging.aeri.ide.servers.
Inside the extension declaration you can add one or more servers. A server has a set of common attributes like an id, a name, a description, an icon (in multiple resolutions) and several links (to which I’ll get back to later). Finally, you have to specify a class implementing org.eclipse.epp.logging.aeri.core.IServerConnection.
As the interface name already suggests, AERI does not provide a central service for all projects, but leaves it to the provider to decide where an error report should be sent to – and in which format. This means that every project has to have its own error reporting server. I’ll get back to this later. Before that, let’s walk through the interface methods of IServerConnection first.
IServerConnection declares 4 methods:
- interested(IStatus, IEclipseContext, IProgressMonitor)
- transform(IStatus, IEclipseContext)
- submit(IStatus, IEclipseContext, IProgressMonitor),
- discarded(IStatus, IEclipseContext), and
That’s it. As you can see, IServerConnection is pretty much a headless API, i.e, it does not offer any UI related methods. In fact, the whole UI workflow inside the Eclipse IDE is covered by AERI. Extension providers thus can (or, more accurately, must) focus on the server-communication only.
So, how does the general workflow then look like?
Whenever an event is logged, AERI polls all server-connections to check whether they are interested in the recently logged IStatus object by calling the server-connection’s interested(IStatus)method . If a server-connection expresses an interest, the IStatus event is put into the review-queue where it sits until the user decides to send the event (if it waits too long, then it will fall out of the queue).
If the user wants to send the error report to your project, the server-connection’s submit(IStatus…) method is called. If the user decides to discard the report, the server-connection’s discarded(IStatus…) method is called.
The last method, transform(IStatus), takes an IStatus object and creates the final error report that will be sent to your server. The result of this method is presented to the user in the Error Report Review dialog – before the user decides whether or not to send the report.
What does AERI’s UI look like when multiple projects want to receive an error report?
The UI is pretty straight forward. If multiple projects are interested in the same log event, the notification popup qualifies every interested project with its logo (icon16) and a message returned by the server-connections interested(…) method:
If the user clicks on View Details…, the review dialog pops up which displays the project’s logo in front of each report:
The server responses are rendered in the same way as error notifications. Every server response is rendered in a separate section:
How do I set up my own error reporting server?
By reading so far, you probably understood that you have to BYO (bring your own) server, because, due to potential legal issues, the Eclipse Foundation will not collect error reports from arbitrary third-parties.
For that reason, AERI’s server extension was designed with the least possible restrictions in mind when it comes to sending error reports: Neither the format nor the protocol for sending the error report over the wire is defined by AERI, and thus, completely left up to you.
However, there are SaaS solutions available you may use to set up a cheap (or even free) error reporting service for your project. Check out Codetrails Error Analytics for details – and the best part of using Codetrails Error Analytics is, that it is pretty easy to use in Eclipse: You can simply reuse the Eclipse.org ServerConnection class since Ctrlflow is 100% compatible with the Eclipse Error Reporting. Check out this webinar for details.
That’s it. This article provided you with a top-level view on how to extend the Eclipse IDE so that it sends error reports for your own projects. For low-level details check out the API documentation and make sure to give the project examples a spin.
AERI comes with several utility classes like filters, histories, and caches. You can also customize AERI to run it in your own Eclipse RCP Application (instead of inside the IDE). I’ll elaborate on each of these topics in subsequent blog posts.