Metric path "CharSequence" replacements in extensions: What do I need to know?

[Bhuvnesh.Kumar]

What do I need to know to use the metricPath CharSequence replacement feature of the Java SDK for AppDynamics extensions?

Contents

• When and how can I use the metricChar replacement?
• How do I configure the metricChar feature?

When and how can I use the metricChar replacement?

The AppDynamics Controller currently supports only ASCII characters in the metric path. Several reserved characters are not supported and can cause undesirable behavior if present in the metric path.

The characters separated by "|" in the metric path are called tokens. The Metric Char Replacement can be used on all metric paths that belong to any of the following scenarios :

• The tokens have characters outside ASCII range (unicode characters)
• The tokens have some reserved characters
• The user wants to replace some text across all tokens with shorter or more meaningful text

These are things to consider when forming a metric path:

• Non-ASCII characters are not allowed.
• The default metric separator for any metric is “|” and an occurrence of “|” creates a new level of hierarchy in the metric tree. Therefore, unless “|” is actually meant for creating hierarchies, it should not be part of a metric token.
• “:” is similar to “|” in that it will create a new hierarchy.
• “,” is a special character and cannot be used in the metric path.

How do I configure the CharSequence feature?

In order to use the metricPath CharSequence replacement feature of the Java SDK for AppDynamics Extensions, the following section must be included in your config.yml:

metricPathReplacements:
  - replace:
    replaceWith:

In the section:

• The “replace” value cannot be empty.
• The “replaceWith” value cannot contain:
  • non-ASCII characters
  • “|”
  • “,”
  • “:”

For example: 

metricPathReplacements:
  - replace: "&"
    replaceWith: ""
  - replace: "-"
    replaceWith: "_"

This example configures two replacements: replace “&” with “” and replace “-” with “_”. So, if a metric has tokens like “Read&Write”, it will be converted to “ReadWrite”, and tokens like “wait-time” will get converted to “wait_time”.

The metric replacement module also loads some default replacements:

•  “|”, “,”, “:” are replaced with “” (empty string).
• These default values can be overridden by configuring them in your config.yml to be replaced with another character.

For the “metricChar” replacement to work correctly, the path should not be formed in the extension’s code. Rather, the extensions commons library methods should be used to form the metric path. There are two ways to do this:

1. Directly use the Metric constructor with signature.
   public Metric(String metricName, String metricValue, Map<String, ?> metricProperties, String metricPrefix, String... tokens)
   
   
2. Use MetricPathUtils.buildMetricPath(String metricPrefix, String... metricTokens) to first build the metric path and then create the Metric object using the Metric constructor that accepts the metric path created earlier.