From 5bed4d180d32b82b6b49efbb485a3892139c2614 Mon Sep 17 00:00:00 2001 From: Ivan Topolnjak Date: Thu, 10 Apr 2014 13:13:13 -0300 Subject: + site: improve StatsD documentation and a few minor fixes --- site/src/main/jekyll/_includes/navigation-bar.html | 5 +- site/src/main/jekyll/changelog.md | 26 +++++++--- site/src/main/jekyll/get-started.md | 33 +++++------- site/src/main/jekyll/index.html | 14 +++-- site/src/main/jekyll/statsd/index.md | 59 ++++++++++++++-------- 5 files changed, 77 insertions(+), 60 deletions(-) (limited to 'site/src/main') diff --git a/site/src/main/jekyll/_includes/navigation-bar.html b/site/src/main/jekyll/_includes/navigation-bar.html index 22a2ecb6..1abdaea3 100644 --- a/site/src/main/jekyll/_includes/navigation-bar.html +++ b/site/src/main/jekyll/_includes/navigation-bar.html @@ -21,11 +21,8 @@ class="caret"> diff --git a/site/src/main/jekyll/changelog.md b/site/src/main/jekyll/changelog.md index 71de60fd..52dbfb2c 100644 --- a/site/src/main/jekyll/changelog.md +++ b/site/src/main/jekyll/changelog.md @@ -4,16 +4,28 @@ layout: default --- Changelog -=============== +========= +
-Version 0.0.15 (2014-04-09) ----------------- +Version 0.0.15 (2014-04-10) +--------------------------- + * kamon - * prepared to publish in maven central repository + * Now publishing to Sonatype and Maven Central + * `reference.conf` files are now "sbt-assembly merge friendly" + * kamon-core - * control of AspectJ weaving messages through kamon configuration -* kamon-statsd (Experimental) + * Control of AspectJ weaving messages through Kamon configuration + * Avoid the possible performance issues when calling `MessageQueue.numberOfMessages` by keeping a external counter. + +* kamon-statsd + * Now you can send Actor and Trace metrics to StatsD! Check out our [StatsD documentation](/statsd/) for more + details. + * kamon-play (Experimental) + * Experimental support to trace metrics collection, automatic trace token propagation and HTTP Client request + metrics is now available for Play! applications. +
Version 0.0.14 (2014-03-17) @@ -22,8 +34,10 @@ Version 0.0.14 (2014-03-17) * Improved startup times * Remake of trace metrics collection * Support for custom metrics collection (Experimental) + * kamon-play * Initial support (Experimental) + * site * [logging](/core/logging/) (WIP) * [tracing](/core/tracing/) (WIP) diff --git a/site/src/main/jekyll/get-started.md b/site/src/main/jekyll/get-started.md index bed0deb0..5bd0f9f8 100644 --- a/site/src/main/jekyll/get-started.md +++ b/site/src/main/jekyll/get-started.md @@ -6,8 +6,8 @@ layout: default Get Started with Kamon ====================== -Kamon is distributed as a set of libraries that you include in your application classpath. This libraries contain all -the required pointcuts and advices (yeap, Kamon uses Aspectj!) for instrumenting Akka actors message passing, +Kamon is distributed as a core and a set of modules that you include in your application classpath. This modules contain +all the required pointcuts and advices (yeap, Kamon uses Aspectj!) for instrumenting Akka actors message passing, dispatchers, futures, Spray components and much more. To get started just follow this steps: @@ -16,28 +16,19 @@ To get started just follow this steps: First: Include the modules you want in your project. ---------------------------------------------------- -All Kamon libraries are available through the official Kamon repository: +All Kamon components are available through Sonatype and Maven Central and no special repositories need to be configured. +If you are using SBT, you will need to add something like this to your build definition: ```scala - "Kamon Repository" at "http://repo.kamon.io" +libraryDependencies += "io.kamon" % "kamon-core" % "0.0.15" ``` -Then, add the libraries to your project. If you are using SBT this minimal build.sbt file should be helpful: +Then, add any additional module you need: -```scala - -resolvers += "Kamon Repository" at "http://repo.kamon.io" - -libraryDependencies += "kamon" % "kamon-core" % "0.0.14" - -``` - -Additionally you can add any modules you want to your app: - -- kamon-core (only compatible with Akka 2.2.3) -- kamon-spray (only compatible with Spray 1.2.0) -- kamon-newrelic -- kamon-dashboard (coming soon) +* kamon-core (only compatible with Akka 2.2.x) +* kamon-spray (only compatible with Spray 1.2.x) +* kamon-statsd +* kamon-newrelic Second: Start your app with the AspectJ Weaver @@ -57,4 +48,6 @@ at the [sbt-aspectj](https://github.com/sbt/sbt-aspectj/) plugin. Third: Enjoy! ------------- -Refer to modules documentation (coming soon) to find out what Kamon is doing for you. +Refer to module's documentation to find out more about core concepts like [tracing](/core/tracing/), +[metrics](/core/metrics/) and [logging](/core/logging/), and learn how to report your metrics data to external services +like [StatsD](/statsd/) and [New Relic](/newrelic/). diff --git a/site/src/main/jekyll/index.html b/site/src/main/jekyll/index.html index f8accbf3..eba6146b 100644 --- a/site/src/main/jekyll/index.html +++ b/site/src/main/jekyll/index.html @@ -57,19 +57,17 @@ title: Kamon - Tools for Reactive Applications Monitoring
-

NewRelic Reporting

+

StatsD Reporting

-

If you are using NewRelic, Kamon can get all your metrics there: +

StatsD is everywhere, let your metrics data be everywhere too:

-

Tell me more »

+

Tell me more »

diff --git a/site/src/main/jekyll/statsd/index.md b/site/src/main/jekyll/statsd/index.md index 63a94a91..a44550a4 100644 --- a/site/src/main/jekyll/statsd/index.md +++ b/site/src/main/jekyll/statsd/index.md @@ -3,37 +3,38 @@ title: Kamon | StatsD | Documentation layout: default --- -What is StatsD? -======= +Reporting Metrics to StatsD +===========================
-StatsD is a simple network daemon that continuously receives metrics pushed over UDP and periodically sends aggregate metrics to upstream services -like Graphite. Because it uses UDP, clients can send metrics to it very fast with little to no overhead. -This means that a user can capture multiple metrics for every request to a web application, even at a rate of thousands of requests per second. -Request-level metrics are aggregated over a flush interval (default 10 seconds) and pushed to an upstream metrics service. +[StatsD](https://github.com/etsy/statsd/) is a simple network daemon that continuously receives metrics over UDP and +periodically sends aggregate metrics to upstream services like (but not limited to) Graphite. Because it uses UDP, +sending metrics data to StatsD is very fast with little to no overhead. -Getting Started with StatsD ----------- - Installation -------------- +------------ -To use the StatsD module just make sure you put the `kamon-statsd` library in your classpath and start your application the Aspectj Weaver and Newrelic agents. Please refer to our [get started](/get-started) page -for more info on how to add the AspectJ Weaver. +To use the StatsD module just add the `kamon-statsd` dependency to your project and start your application using the +Aspectj Weaver agent. Please refer to our [get started](/get-started) page for more info on how to add dependencies to +your project and starting your application with the AspectJ Weaver. Configuration ------------- -Currently you will need to add a few settings to your `application.conf` file for the module to work: +First, include the Kamon(StatsD) extension under the `akka.extensions` key of your configuration files as shown here: ```scala akka { - // Make sure the StatsD extension is loaded with the ActorSystem extensions = ["kamon.statsd.StatsD"] } +``` +Then, tune the configuration settings according to your needs. Here is the `reference.conf` that ships with kamon-statsd +which includes a brief explanation of each setting: + +``` kamon { statsd { # Hostname and port in which your StatsD is running. Remember that StatsD packets are sent using UDP and @@ -52,26 +53,40 @@ kamon { # collection for your desired entities must be activated under the kamon.metrics.filters settings. includes { actor = [ "*" ] + trace = [ "*" ] } simple-metric-key-generator { # Application prefix for all metrics pushed to StatsD. The default namespacing scheme for metrics follows # this pattern: # application.host.entity.entity-name.metric-name - application = "Kamon" + application = "kamon" } } } ``` -Installing Graphite ----------- -In the Graphite documentation we can find the [Graphite overview](http://graphite.readthedocs.org/en/latest/overview.html#what-graphite-is-and-is-not). It sums up Graphite with these two simple points. -* Graphite stores numeric time-series data. -* Graphite renders graphs of this data on demand. +Integration Notes +----------------- + +* Contrary to many StatsD client implementations, we don't flush the metrics data as soon as the measurements are taken + but instead, all metrics data is buffered by the `Kamon(StatsD)` extension and flushed periodically using the + configured `kamon.statsd.flush-interval` and `kamon.statsd.max-packet-size` settings. +* Currently only Actor and Trace metrics are being sent to StatsD. +* All timing measurements are sent in nanoseconds, make sure you correctly set the scale when plotting or using the + metrics data. +* It is advisable to experiment with the `kamon.statsd.flush-interval` and `kamon.statsd.max-packet-size` settings to + find the right balance between network bandwidth utilization and granularity on your metrics data. + + + +Visualization and Fun +--------------------- -Show data with [Grafana](http://grafana.org) ----------- +StatsD is widely used and there are many integrations available, even alternative implementations that can receive UDP +messages with the StatsD protocol, you just have to pick the option that best suits you. For our internal testing we +choose to use [Graphite](http://graphite.wikidot.com/) as the StatsD backend and [Grafana](http://grafana.org) to create +beautiful dashboards with very useful metrics. Have an idea of how your metrics data might look like in Grafana: ![statsD](/assets/img/kamon-statsd-grafana.png "Grafana Screenshot") -- cgit v1.2.3