Tagging existing metrics

Supported products

This API is available from com.atlassian.profiling:atlassian-profiling-api introduced in Atlassian profiling 4.6.0. To see which version of Atlassian profiling products are on, refer to Atlassian profiling's adoption table. This also relies on each product adding metrics which can be tagged. Jira 9.1 and Confluence 7.17 or higher have support.

Intended usage

By providing metadata through tags, a product admin can opt-in to outputting those tags to be able to better understand why an app is performing some operation and hopefully be better placed to troubleshoot performance issues.

Performance concerns

Every combination of metrics and tags (i.e. every resulting MBean in JMX) consumes memory. It's reasonable to assume that each consumes an additional 1MB of memory. For this reason all tags will be disabled by default and need to be enabled by the admin. Learn more about optional tags. Keep in mind the worst case is any metric tagged with your app's plugin keys and any metric not tagged with plugin keys can be multiplied by every possible value of the tag.

Tagging using the Atlassian profiling API

1. Add com.atlassian.profiling:atlassian-profiling-api as a dependency. e.g if using maven:

1
2
<dependency>
    <groupId>com.atlassian.profiling</groupId>
    <artifactId>atlassian-profiling-api</artifactId>
    <version>4.6.0</version>
    <!-- We want this to come from the products -->
    <scope>provided</scope>
</dependency>

2. Setup a TagFactory

2.1. Import TagFactoryFactory using the preferred method. There are four methods; using Spring Java configuration, using Spring scanner, using the plugin module descriptors, and using the OSGi namespace in Spring XML. e.g if using Spring Java configuration

1
2
@Bean
public TagFactoryFactory tagFactoryFactory() {
    return importOsgiService(TagFactoryFactory.class);
}

2.2. Create a TagFactory bean

1
2
@Bean
public TagFactory teamCalendarTagFactory(final TagFactoryFactory tagFactoryFactory) {
    return tagFactoryFactory.prefixedTagFactory("teamCalendar-");
}

3. Create an OptionalTag for some metadata that can be useful for product administrators. e.g

1
2
public class EventRestResource {
    private final TagFactory teamCalendarTagFactory;
    // ...
    public Response someAction(@Queryparam eventName) {
        final OptionalTag eventNameTag = teamCalendarTagFactory.createOptionalTag("eventName", eventName)
        // ...
    }
}

4. Put the OptionalTag in context

4.1. Import MetricContext similar to importing TagFactoryFactory above. e.g if using [Spring Java configuration]

1
2
@Bean
public MetricContext metricContext() {
    return importOsgiService(MetricContext.class);
}

4.2. Create a ContextFragment using MetricContext around some action where downstream metrics would benefit from the metadata provided by the tag. e.g

1
2
public class EventRestResource {
    private final MetricContext metricContext;
    // ...
    public Response someAction(@Queryparam eventName) {
        final OptionalTag eventNameTag = teamCalendarTagFactory.optional("eventName", eventName)
        // ...
        try(ContextFragment fragment = MetricContext.put(eventNameTag)) {
            persistToDatabase();
            // ...
        }
        // ...
    }
}

5. To see the results, the optional tag will need to be enabled for each metric desired with tag key. In this example the full tag key is teamCalendar-eventName.