com.atlassian.jira.util.stats

Interface JiraStatsListener

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface JiraStatsListener

Registered implementations are notified on each JiraStats snapshot creation with total and snapshot data in raw form(nested maps with strings representations of stats values).

Main intended usage - sending stats data to analytics.

Using Stats listener to send analytics

Can be applied whenever analytics event you want to send require same data with same structure as the stats you already have. For simplistic, low boilerplate way to send parts of actual stats data to jira analytics follow this instruction:

• create regular analytics event (using EventName annotation) with 1 or 2 (depends whether you need snapshot data total data or both see JiraStats ) Map type fields
• Implement JiraStatsListener and register it to ManagedStats implementation of your interest
• explicitly declare the parts of nested map(convention of key names "mapFieldname.key1level.key2level") you want to go through the analytics filters in jira-analytics-whitelist-plugin-whitelist.json. Be extra careful not to whitelist aynything that will become useless after analytics safety filters (cutting our strings values and such) or might expose some customer internal data
• in your com.atlassian.jira.util.stats.onStats(Map, Map) implementation simply instatiate your analytic event and send it via EventPublisher

See Also:

JiraStats, ManagedStats, ManagedStats.addJiraStatsListener(JiraStatsListener), JiraStatsListener

Method Summary

Modifier and Type	Method and Description
void	onStats(Map snapshotMap, Map totalMap) Both snapshot and total might consist of nested maps - structure and names of the keys are derived from the particular ManagedStats implementation.

Method Detail

onStats

void onStats(Map snapshotMap,
             Map totalMap)

Both snapshot and total might consist of nested maps - structure and names of the keys are derived from the particular ManagedStats implementation.

Maps on each nesting level have string keys but can have either String value(for single value params) or nested Map(following the same content rules) representing more complex objects with many field.

Fields of simple types (like AtomicLong map directly to records that have keys same as name of the field and the value as string the representation of fields value;

Examples

Example 1

Call by stats FlatClassImplementation

 
 class FlatClassImplementation implements SomeManagedStatsInterface {
      private AtomicLong field1;
      private AtomicLong field2;
      // no more fields
      //rest of implementation
 }
 

Will result with total/snapshot maps with keys "field1" and "field2", each pointing to a value containing string value of an integer

Fields of more complex types, composed of multiple fields (like MutableLongStats are represented as nested maps, with same rules for content as top level map.

Example 2

 class TopClass implements SomeManagedStatsInterface{
     private AtomicLong field1;
     private EmbeddedClass field2;
     // no more fields
     // rest of implementation
 }

 class EmbeddedClass {
     private AtomicLong field3;
     private AtomicLong field4;
     // no more fields
     // rest of implementation
 }
 
 

Call by stats TopClass will results with

• top level map with two keys "field1"(value for which will be string representation of integer value) and "field2"
• under key "field2" value will be nested map with keys "field3" and "field4", each with value of string representation of an integer

  Nesting can reach multiple levels, depending on the level of nesting in source stats objects.

Parameters:

snapshotMap - - snapshot of stats values from recent period

totalMap - - stats values accumulated since the stat was instantiated

See Also:

for more about structure of {@link ManagedStats} implementation