About

Fathom-Metrics provides your application with a DropWizard Metrics service for runtime collection and reporting of usage & activity.

Installation

Add the Fathom-Metrics artifact…

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-metrics</artifactId>
    <version>${fathom.version}</version>
</dependency>

… and optionally a Fathom-Metrics reporter:

Reporter Module
InfluxDB com.gitblit.fathom:fathom-metrics-influxdb
Graphite com.gitblit.fathom:fathom-metrics-graphite
Ganglia com.gitblit.fathom:fathom-metrics-ganglia
Librato com.gitblit.fathom:fathom-metrics-librato

Configuration

metrics {
  # Collect JVM metrics
  jvm = true

  # Report metrics via MBeans for JConsole, VisualVM, or JMX
  mbeans = true
}

Usage

The most elegant way to use Fathom’s DropWizard Metrics integration is with annotations.

Annotation Description
@Counted A counter increments on method execution and optionally decrements at execution completion.
@Metered A meter measures the rate of events over time (e.g., “requests per second”)
@Timed A timer measures both the rate that a particular piece of code is called and the distribution of its duration.

In the following example we will annotate several methods for metrics collection and the activity data will be transparently collected.

@Singleton
public class EmployeeDao {

    private static final Logger log = LoggerFactory.getLogger(EmployeeDao.class);

    public EmployeeDao() {
    }

    @Metered
    public Employee get(int id) {
        log.info("Getting employee #{} by id", id);
        Employee employee = employees.get(id);
        return employee;
    }

    @Timed
    public List<Employee> getAll() {
        log.info("Getting all employees");
        return new ArrayList<>(employees.values());
    }

    @Counted
    public Employee delete(int id) {
        Employee employee = employees.get(id);
        employees.remove(id);
        return employee;
    }

    @Metered
    public Employee save(Employee employee) {
        return put(employee);
    }
  }

You may also inject the Fathom Metrics service or the MetricRegistry to manually manage your metrics.

@Singleton
public class ItemDao {

  @Inject
  Metrics metricsService;

  @Inject
  MetricRegistry metricRegistry;

}

VisualVM or JConsole

As long as metrics.mbeans = true in your runtime configuration, your metrics will be visible to VisualVM or JConsole.

Note

VisualVM does not ship with an MBeans viewer however there is an MBeans plugin that can be installed from within VisualVM to enable display of MBeans.


InfluxDB

InfluxDB is a self-hosted or cloud-hosted metrics database and dashboard service.

Installation

Add the Fathom-Metrics-InfluxDB artifact.

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-metrics-influxdb</artifactId>
    <version>${fathom.version}</version>
</dependency>

Configuration

metrics {
  influxdb {
    enabled = true
    address = localhost
    port = 8086
    database = mydb
    username = root
    password = root
    period = 60 seconds
  }
}

Graphite

Graphite is a self-hosted or cloud-hosted metrics database and dashboard service.

Installation

Add the Fathom-Metrics-Graphite artifact.

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-metrics-graphite</artifactId>
    <version>${fathom.version}</version>
</dependency>

Configuration

metrics {
  graphite {
    enabled = true
    address = localhost
    port = 8086
    pickled = false
    period = 60 seconds
  }
}

Ganglia

Ganglia is a self-hosted metrics database and dashboard service.

Installation

Add the Fathom-Metrics-Ganglia artifact.

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-metrics-ganglia</artifactId>
    <version>${fathom.version}</version>
</dependency>

Configuration

metrics {
  ganglia {
    enabled = true
    address = localhost
    port = 8086
    period = 60 seconds
  }
}

Librato

Librato is a cloud-based metrics database and dashboard service.

Installation

Add the Fathom-Metrics-Librato artifact.

<dependency>
    <groupId>com.gitblit.fathom</groupId>
    <artifactId>fathom-metrics-librato</artifactId>
    <version>${fathom.version}</version>
</dependency>

Configuration

metrics {
  librato {
    enabled = true
    username = person@example.com
    apikey = 12345cafebabe
    period = 60 seconds
  }
}