Integrating the Eclipse IDE Client

Since Eclipse 4.6 (Neon, released June 2016), the Eclipse IDE ships a default client for the Codetrails Error Analytics Server. Now, all your Eclipse plug-ins, whether commercial or Open Source, can send error reports to your own Codetrails Error Analytics service.

How it Works

Once you have configured the client, it will analyze any error message that is added to Eclipse’s platform log (which can be found in the Error Log view). The client is smart enough to recognize if an error occurred in your code and will ask the user to send an error report to your service, not to the public Automated Error Reporting server hosted by the Eclipse Foundation.

Note
Only messages with a log level of ERROR are handled by the Error Reporting client.

How to Send an Error Report

To send an error report to your service yourself, simply log an error using the platform log:

package com.example.plugin;

import org.eclipse.core.runtime.*;

public class Plugin {

  public static final String PLUGIN_ID = "com.example.plugin";

  public void report() {
    ILog log = Platform.getLog(Platform.getBundle(PLUGIN_ID));
    IStatus error = new Status(IStatus.ERROR, PLUGIN_ID,
      "Encountered an error");
    log.log(error);
  }
}

If you have a Throwable, i.e. because you are in a catch-block, add it to the Status object to get its stack trace included in the error log entry. Otherwise, the Error Reporting client will fill in a stack trace toward the log.log(error) call, ensuring the error error log entry is matched to your software.

How to Send Error Reports for Uncaught Exceptions

For most exceptions that are not caught by your own code you don’t have to do any work to send error reports. If an uncaught exceptions occurs, it is likely going to be caught by the Eclipse platform. For example, if a NullPointerException occurs in the run() method of a Job, the Eclipse Job Manager will catch and log this.

If you are executing code completely outside of the Eclipse platform’s control, for example because you create and run your own Thread, you can define an UncaughtExceptionHandler that will take care of logging any uncaught exceptions:

public class MyThread extends Thread {

    public static final String PLUGIN_ID = "com.example.plugin";

    @Override
    public void run() {
        ILog log = Platform.getLog(Platform.getBundle(PLUGIN_ID));

        Thread.setDefaultUncaughtExceptionHandler((Thread t, Throwable e) -> {
            IStatus error = new Status(IStatus.ERROR, PLUGIN_ID, "Encountered an error", e);
            log.log(error);
        });
    }
}

How to Install the Client

The Eclipse Automated Error Reporting client version 2.0 has been released with Eclipse Neon (4.6.0) and ships with all packages by default. Thus, you don’t have to do anything special to install the client.

However, in case you’d like to add it to your target platform, you can find the feature on the official Eclipse Neon update site.

eclipse aeri p2 install dialog.png
Figure 1. Installing the Eclipse Automated Error Reporting client.
Caution
Eclipse Mars (4.5.0) contains the Eclipse Automated Error Reporting client in version 1.0. That version is restricted to send error reports to eclipse.org; it cannot send reports to your Codetrails Error Analytics service.

How to Configure the Client

Most of the client settings are retrieved from the server using the discovery URL of your Codetrails Error Analytics service, which you must to pass to the org.eclipse.epp.logging.aeri.ide.servers extension point. You can find this URL on the Help > System Information page:

client rest api urls.png
Figure 2. Help > System Information > REST API URLs panel.

You can further customize the look (labels, icons, etc.) of the client in one of your plug-in’s plugin.xml files.

plugin.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
  <extension point="org.eclipse.epp.logging.aeri.ide.servers">
    <server id="com.example.plugin"
      name="Example Project"
      description="Example project wishes to..."
      class="org.eclipse.epp.internal.logging.aeri.ide.server.mars.ServerConnection"
      icon16="icons/obj16/logo.png"
      icon32="icons/obj32/logo.png">

      <link rel="provider"
        title="Example Project"
        href="https://www.example.com"/>

      <!-- The discovery URL of your Codetrails Error Analytics service. -->
      <link rel="discovery"
        title="Discovery URL"
        href="https://aer.ctrlflow.com/example/community/discovery"/>
    </server>
  </extension>
  ...
</plugin>

Finally, you have to add an (optional) dependency to the Error Reporting Client. Copy and paste the following line to your MANIFEST.MF file’s Required Bundle section:

MANIFEST.MF
org.eclipse.epp.logging.aeri.ide;bundle-version=\"[2.0.0,3.0.0)\";resolution:=optional
eclipse aeri configure projects dialog.png
Figure 3. Configure Automated Error Reporting dialog.

That’s it. Now that you have configured the client, your plug-in can start reporting errors.

How to Test the IDE Client in a Runtime Eclipse

Most of the time you test your own software in a runtime Eclipse, you don’t want to report errors you encounter. When testing the integration of the IDE Client for the first time, however, it may be useful to do so in a runtime environment. If you want to be able to send error reports in a runtime Eclipse, you need to provide a value for the system property eclipse.buildId. Any non-empty value will do, for example runtime-eclipse.

results matching ""

    No results matching ""