The short story

Idea: Attach an events listener to the running iterations, and use the events data flow for any kind of analysis.

The slightly longer story

public final class MyControler {
	public static void main(String[] args) {
		Controler controler = new Controler( args ) ;
		final Scenario sc = controler.getScenario() ;
		ControlerListener startupListener = new StartupListener() {
			@Override
			public void notifyStartup(StartupEvent event) {
				EventHandler myEventHandler = new MyEventHandler() ;
				event.getControler().getEvents().addHandler(myEventHandler);
			}
		};
		controler.addControlerListener(startupListener);
		controler.run();
	}
}

and then

class MyEventHandler implements ActivityEndEventHandler {
    public void handleEvent( ActivityEndEvent ev ) {
        // do any kind of api-based analysis with the event
    }
}    

This second part is fully api-based (except that some material is still under core.api.experimental) .

The long story

Some material (not fully consistent with the above) is under src/tutorial/programming/example6EventsHandling.  This should also be used to obtain hints with respect to the correct syntax ... since it is automatically part of all refactorings.