Cinnamon 2.0 migration guide

This is a guide for migrating from Cinnamon 1.2 to Cinnamon 2.0.

The major change between 1.2 and 2.0 is that Cinnamon uses an agent to instrument code in the latter. Also, the actor configuration has changed context so it is important to move this configuration section into its new location for things to be instrumented.

Running with the Cinnamon Agent

To run with the agent, you need to move your project from the Instrumented Lightbend Platform to the normal Lightbend Platform using the customer portal installation instructions.

Now you are ready to follow the installation instructions for the Cinnamon Agent.

Dependency Changes

Repository

The repository for the cinnamon artifacts have changed to https://repo.lightbend.com/commercial-releases. Please update this in your build description following the instructions in Getting Started.

Artifact Organization

The organisation for the artifacts have changed from com.typesafe.cinnamon to com.lightbend.cinnamon. Please update this in your build description following the instructions in Getting Started.

Package Names

The package names for all classes have changed from com.typesafe.cinnamon to com.lightbend.cinnamon. This is most visible in the user facing APIs for the Spans that has moved from com.typesafe.cinnamon.akka.Tracer to com.lightbend.cinnamon.akka.Tracer and the Coda Hale Metrics reporters.

Configuration Changes

Actor Configuration

The actor configuration in 2.0 is done in one common place regardless of underlying integration:

cinnamon.akka {
  actors {
    # actor config
  }
}

In the 1.2 version the actor configuration was done in the context of the selected integration, e.g.:

cinnamon.chmetrics {
  actors {
    # actor config
  }
}

or

cinnamon.takipi
  actors {
    # actor config
  }
}

Simply move the actors configuration into the context of cinnamon.akka, e.g.

cinnamon.akka {
  actors {
    "*" {
      report-by = class
    }
  }
}

Trace Configuration

The trace configuration in 2.0 is done in one common place regardless of underlying integration:

cinnamon.trace {
  thresholds {
    # thresholds config
  }
}

In the 1.2 version the trace configuration was done in the context of the selected integration, e.g.:

cinnamon.chmetrics {
  trace.thresholds {
    # thresholds config
  }
}

or

cinnamon.takipi {
  trace.thresholds {
    # thresholds config
  }
}

Simply move the trace configuration into the context of cinnamon.trace, e.g.

cinnamon.trace {
  thresholds {
    "hotpath" = 3s
  }
}

StatsD format

In Cinnamon 2.0 the metrics data reported to StatsD includes JVM main class and dispatcher information in the identifier. This means that all dashboards must reflect the new identifier format. The old way to store metrics data was servers.<IP>.apps.<ACTOR-SYSTEM>.metrics.<ACTOR> and this has now been updated to servers.<IP>.apps.<JVM-MAIN-CLASS>.metrics.akka.systems.<ACTOR-SYSTEM>.dispatchers.<DISPATCHER>.actors.<ACTOR>.

Here is part of an example identifier that reflects the new format: servers.192_168_1_4.apps.cinnamon_sample_bottleneck_BottleneckDemo.metrics.akka.systems.BottleneckSample.dispatchers.frontend-dispatcher.actors.cinnamon_sample_bottleneck_FrontEndRouter.

Ensure that you update all queries, in Grafana or similar dashboard, to reflect the new format.

Reporter interface change

The com.lightbend.cinnamon.chmetrics.reporter.Reporter interface has changed, so if you have implemented your own reporter you will need to make the following change:

void start(String applicationId);

has been replaced by:

void start();

Filter interface change

The com.lightbend.cinnamon.chmetrics.reporter.Filter interface has changed, so if you have implemented your own formatter you will need to make the following change:

MetricFilter create(Config config);

is now:

MetricFilter getMetricFilter();

The configuration will be passed to the filter as a constructor argument so that you can get to filter specific configuration there.

Formatter interface change

The com.lightbend.cinnamon.chmetrics.reporter.Formatter interface has changed, so if you have implemented your own formatter you will need to make the following change:

String format(String categoryName, String identifier, String metricName);

has been replaced by two methods:

/**
 * Encode a single name element within a full identifier.
 * This allows delimiters in the name, or special characters,
 * to be encoded differently. Such as replacing '.' with '_'.
 *
 * @param name single name element within full identifier
 * @return encoded name to be included in full identifier
 */
String encode(String name);

/**
 * Join names into a single delimited identifier.
 *
 * @param names the parts of the full identifier to join together
 * @return a single delimited identifier
 */
String join(List<String> names);