Home

Awesome

WSO2 Carbon Metrics


BranchBuild Status
masterBuild Status

"WSO2 Carbon Metrics" provides an API for WSO2 Carbon Components to use the Metrics library.

Configuring Metrics

The metrics is configured via a YAML file. The Metrics is enabled by default and it can be disabled from the configuration. The Metrics is also configured to register a standard Java MBean for management operations.

All reporters are also configured using the same configuration file. By default, the JMX Reporter will be enabled.

Metric Levels

The WSO2 Carbon Metrics APIs associate a Level with each Metric. These levels are similar to the Levels used in Logging Libraries.

Metrics Levels are organized from most specific to least:

The levels are configured in YAML file.

Similar to Apache Log4j, the WSO2 Carbon Metrics implementation uses a Metric Hierarchy. The hierarchy is maintained via the Metric names.

The levels in Metrics configuration can be configured to any hierarchy. For example, if we use jvm.memory.heap=INFO, all metrics under jvm.memory.heap memory will have INFO as the configured level.

If there is no configured level for specific metric name hierarachy, the level configured in "rootLevel" will be used.

Components

This repository has multiple components.

Maven Dependency

In order to use WSO2 Carbon Metrics in your components, you need to add following dependency to your pom.xml

<dependency>
    <groupId>org.wso2.carbon.metrics</groupId>
    <artifactId>org.wso2.carbon.metrics.core</artifactId>
    <version>${carbon.metrics.version}</version>
</dependency>

Usage

The APIs to create Metrics are defined in org.wso2.carbon.metrics.core.MetricService. The APIs to manage Metrics, such as setting metric levels and adding reporters are defined in org.wso2.carbon.metrics.core.MetricManagementService.

In Carbon (OSGi) environment, these APIs are available as OSGi services.

See the sample ServiceComponent.

When using Metrics in standalone application, the Metrics can be initialized as follows.

Metrics metrics = new Metrics(<ConfigProvider>);
metrics.activate();

MetricService metricService = metrics.getMetricService();
MetricManagementService metricManagementService = metrics.getMetricManagementService();

After getting a reference to the MetricService, the Metrics can be created as follows.

// Create a Gauge
metricService.gauge(MetricService.name("test", "gauge"), Level.INFO, () -> number);

// Create a Counter
Counter counter = metricService.counter(MetricService.name("test", "count"), Level.INFO);
// Increment
counter.inc();
// Decrement
counter.dec();

// Create a Meter
Meter meter = metricService.meter(MetricService.name("test", "meter"), Level.INFO);
// Mark an event
meter.mark();

// Create a Histogram
Histogram histogram = metricService.histogram(MetricService.name("test", "histogram"), Level.INFO);
// Update the histogram
histogram.update(value);

// Create a Timer
Timer timer = metricService.timer(MetricService.name("test", "timer"), Level.INFO);
// Start the timer
Timer.Context context = timer.start();
// Stop the timer
context.stop();

See the sample RandomNumberServiceImpl.

License

Copyright 2014 WSO2 Inc.

Licensed under the Apache License, Version 2.0