Last updated Mar 22, 2022

Rate this page:

Adding metrics

Supported products

Your app can emit metrics to JMX while working with any product and version, no restrictions are placed on the platform MBean server. It's possible to create MBeans manually, but a metrics library like Micrometer Metrics or Dropwizard Metrics can speed up the development time.

Intended usage

Atlassian products emit metrics to JMX and we recommend our customers set up a monitoring solution for them. Customers can then either alert on metrics to proactively monitor the product and application, or refer to them to diagnose performance issues. You may wish for your app to also emit metrics in a similar fashion to ease adoption for customers.

Performance concerns

Every combination of metrics and tags (i.e. every resulting MBean in JMX) consumes memory. It's reasonable to assume that each MBean consumes an additional 300KB of memory. We recommend running a performance test with real data to ensure usage won't result in runaway memory consumption. To illustrate; if there are two metrics with different names, and they both have a tag with two possible values then the total memory consumption would be: (300KB * 2 tag values) + (300KB * 2 tag values) = 1.2MB.

Using Micrometer and Atlassian profiling to emit to JMX

  1. Add a dependency on Micrometer and Atlassian profiling's micrometer utilities. e.g if using maven;
1
2
<dependency>
    <groupId>com.atlassian.profiling</groupId>
    <artifactId>atlassian-profiling-micrometer</artifactId>
    <version>4.5.0</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-core</artifactId>
    <version>1.8.3</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-jmx</artifactId>
    <version>1.8.3</version>
    <scope>compile</scope>
</dependency>
  1. Avoid exporting the packages; com.atlassian.util.profiling.micrometer, io.micrometer, and com.codehale.metrics to OSGi. Learn more.

  2. Choose a unique domain for your app, all metrics created will appear under this domain e.g com.atlassian.teamcalendars

  3. Create a Micrometer MeterRegistry bean to be reused for creating all metrics, e.g

1
2
// Package imports here to show the relationships between Atlassian Profiling, Micrometer, and Dropwizard
import com.atlassian.jira.monitoring.jmx.JmxMetricsExposer;
import com.atlassian.util.profiling.micrometer.util.QualifiedCompatibleHierarchicalNameMapper;
import com.atlassian.util.profiling.micrometer.util.UnescapedObjectNameFactory;
import com.codahale.metrics.MetricRegistry;
import com.codahale.metrics.jmx.JmxReporter;
import io.micrometer.core.instrument.Clock;
import io.micrometer.core.instrument.composite.CompositeMeterRegistry;
import io.micrometer.jmx.JmxConfig;
import io.micrometer.jmx.JmxMeterRegistry;

// ...

@Bean
public MeterRegistry jmxMeterRegistry() {
    final MetricRegistry jmxMetricRegistry = new MetricRegistry();
    final JmxReporter jmxReporter = JmxReporter.forRegistry(jmxMetricRegistry)
        .inDomain("com.atlassian.teamcalendars")
        .createsObjectNamesWith(new UnescapedObjectNameFactory())
        .build();
    final JmxMeterRegistry jmxMeterRegistry = new JmxMeterRegistry(
        JmxConfig.DEFAULT,
        Clock.SYSTEM,
        new QualifiedCompatibleHierarchicalNameMapper(),
        jmxMetricRegistry,
        jmxReporter);
    jmxMeterRegistry.config().namingConvention(NamingConvention.dot)
    jmxMeterRegistry.start();
    return jmxMeterRegistry;
}
  1. Follow the Micrometer documentation to add the metric you want using the jmxMeterRegistry, e.g
1
2
addEvent();
jmxMeterRegistry.counter("addEvent").increment(1L);

Example in JConsole

You can use JConsole to attach to a running JVM to see the metric emitted to JMX. In this particular example com.atlassian.confluence is the domain, name=getFooCount is the metric name, and tag.entity=foo is a tag with the key "entity" and the value "foo".

Rate this page: