Examples of com.google.sitebricks.stat.StatModule

This module enables publishing values annotated with {@link Stat} to a givenservlet path.

Example of Use

As an example, consider the following class:

 class QueryServlet extends HttpServlet { {@literal @}Stat("search-hits") private final AtomicInteger hits = new AtomicInteger(0); {@literal @}Inject QueryServlet(....) { } {@literal @}Override void doGet( HttpServletRequest req, HttpServletResponse resp) { .... String searchTerm = req.getParameter("q"); SearchResult result = searchService.searchFor(searchTerm); if (result.hasHits()) { hits.incrementAndGet(); } ... } }

This class registers a stat called {@code search-hits}. To configure the server to publish this stat, install a {@link StatModule}, such as:

 public class YourServerModule extends AbstractModule { {@literal @}Override protected void configure() { install(new StatsModule("/stats"); ... } }

Then, to query the server for its stats, hit the url that was registered with the module (which was {@code /stats}, in the example above).

Registering Stats

The simplest way of registering a stat is to use the @Stat annotation. Members of a class annotated by @Stat are registered automatically when an instance of the class is created by Guice. The value of the member is read when a snapshot of the stats is requested, most likely by the {@link StatsServlet} upon a request to {@code /stats}.

At times it is convenient to "manually" register a stat. To do this, inject an instance of {@link StatRegistrar} and use it to register a stat.For example:

 class RegistersLocalVariableAsStat { private final StatRegistrar statRegistrar; {@literal @}Inject RegistersLocalVariableAsStat( StatRegistrar statRegistrar) { this.statRegistrar = statRegistrar; } void initialize() { long start = System.currentTimeMillis(); doInitialization(); statRegistrar.registerSingleStat( "init-time-in-ms", "Initialization time of a class", System.currentTimeMillis() - start); } }

There are other convenience methods on {@link StatRegistrar} to facilitateregistering annotated static members on classes and registering all annotated members on instances as well.

Exposing Stats

It's important to consider, if only to be careful, how to prevent a mutable reference of a stat from leaking into the stat publishing logic. For instance, if you were to publish a deeply mutable reference to a List, then a stat publisher could inadvertently (or purposely) mutate it.

It is the role of a {@link StatExposer} to guard against such leaks: Anexposer is given the raw value of a stat, and should return a safe view of it. This view is then passed to the {@link StatsPublishers publishers}.

By default, a {@link StatExposers.InferenceExposer} is used to guard statsregistered via {@link Stat @Stat}. This implementation should handle the majority of common use cases. If, however, you want to use a different {@link StatExposer} for your stat, then you may do so byspecifying its class within the {@link Stat @Stat} annotation.For example:

 class ServiceStat implements Cloneable { int calls; AtomicLong<Long> latencyInMs; {@literal @}Override protected Object clone() { return new ServiceStat(calls, latencyInMs); } } class ServiceStatExposer implements StatExposer<ServiceStat> { {@literal @}Override Object expose(ServiceStat serviceStat) { return serviceStat.clone(); } } class Service { {@literal @}Stat(value = "service-stat", exposer = ServiceStatExposer.class) private final ServiceStat serviceStat; ... }

Published Formats

By default, published stats are available in several formats:

html - a formatted html page
json - well formed json
text - simple plaintext page

To request stats in a given format, include a value for the {@value StatsServlet#DEFAULT_FORMAT} parameter in the {@code /stats} request.For the formats above, the value for this parameter should correspond to the type of output (i.e., pass "html", "json", or "text"). If no parameter is given, then html is returned.

Extensions

You may extend the default set of publishers by adding and binding another implementation of {@link StatsPublisher}. To add your implementation, add a binding to a {@link MapBinder MapBinder<String, StatsPublisher>}. For example:

 public class CustomPublisherModule extends AbstractModule { {@literal @}Override protected void configure() { MapBinder<String, StatsPublisher> mapBinder = MapBinder.newMapBinder(binder(), String.class, StatsPublisher.class); mapBinder.addBinding("custom").to(CustomStatsPublisher.class); } }

You can then retrieve stats from your custom publisher by hitting {@code /stats?format=custom}. @author dhanji@gmail.com (Dhanji R. Prasanna) @author ffaber@gmail.com (Fred Faber)