Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Comparing changes

Choose two branches to see what's changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
  • 7 commits
  • 1 file changed
  • 0 commit comments
  • 2 contributors
Showing with 73 additions and 100 deletions.
  1. +73 −100 readme.md
View
173 readme.md
@@ -1,115 +1,28 @@
Guardian Management
===================
-This project contains various helpers to ease administrative management
-of production java apps.
+In order to simplify their management, Guardian web-apps should conform to our [web applications specification]
+(https://docs.google.com/document/d/12ckZC0fGtilntcsJy6mBUylvohLoxUKjkwGDaur-pE8/edit).
+This library provides standard management pages and makes it easy to create new
+app-specific ones in order to fulfill those criteria.
-Our policy is that each app exposes its user facing pages on a sub url,
-and administrative pages on `/management`. So, for example, `content-api.war`
-when deployed to a container has the actual api under `/content-api/api` and
-the management pages on `/content-api/management`.
-
-The `/management` url should return a html page that links to all management
-pages.
-
-This simple framework aims to make it simple to generate the standard management
-pages and easy to create new app-specific ones.
-
-
-Note for the Old Skool
-======================
-
-The old web-framework specific management libraries, can be found in the
-[3.x](https://github.com/guardian/guardian-management/tree/3.x) branch of this project.
-There is no intention to maintain these further.
-
-Going from CACTI to GANGLIA
-=====================
-There is a major, breaking, change when you use the ganglia (5.x) version of guardian management.
-
-(1) When you initialise your StatusPage object, you need to name it as being the status page of your app:
-
-`new StatusPage("My App Name", Metrics.....)`
-
-So for example identity has 2 status pages:
-
-`new StatusPage("identity-webapp", Metrics.....)`
-`new StatusPage("identity-api", Metrics.....)`
-
-(2) Creating A Metric
-
-You need to provide four arguments, with an optional fifth.
-
-`new TimingMetic("group", "name", "title", "description")`
-
- GROUP: this is used as a logical grouping. Think of it as a noun. For example "emails"
- NAME: This is a verb related to the noun defined in group. For example "sent"
- TITLE: This is a text string used to title the graphs. Keep it short. For example "Emails Sent"
- DESCRIPTION: This is a longer description of the metric. Used on the hover over.
- For example "Total number of emails sent"
-
-Group and Name are munged together in ganglia to give the actual name used on the console.
-There is another console in Graphite (graphing tool) which will allow subdivision on group.
-Allowing you to see all the "emails" metrics and to create mash ups of all of these.
-Using the groups as it's top level option.
-
-As a rule use underscores (_) not hyphens (-) as delimiters.
-
-So in scala:
-
-`object SuccessfulEmails extends CountMetric("emails", "sent", "Emails Sent", "Number of emails sent")`
-
-The fifth metric is the field master. This takes Option[Metric] with a default of None.
-This is used to indicate that the metric you are creating is a child of a
-another metric. The parameter is the metric you wish to be a child of
-
-For example. Imagine there is a time taken for a request metric:
-
-`object Requests extends TimingMetric("requests", "api", "Api Requests Timer", "Total number and time taken for API request")`
-
-You may have a mongoDB requests metric, which is a child of the overall HTTP request:
-
-`object MongoRequests extends TimingMetric("requests", "mongodb", "Mongodb Requests", "Mongo request timer", Some(Requests))`
-
-This allows Ganglia to give the proportion of time of the HTTP request taken talking to mongo. You could have another:
-
-`object MongoRequests extends TimingMetric("requests", "oracle", "Oracle Requests", "Oracle request timer", Some(Requests))`
-
-Ganglia would now be able to show you propertions of each DB request as a proportion of total HTTP time.
-
-
-(3) Types of metric
-
- - Timing: standard timing metric, takes number of events over a time period.
- - Count: Constantly incrementing counter.
- - Gauge: Count at a particular point in time.
-
-(4) Extra docs:
-
-See guardian google docs for "Web Applications Specifications"
+The library is intended to be web framework agnostic and currently has support for
+anything using the servlet API or the Play framework. A small adapter library
+for the request and response abstractions, blatantly inspired by/ripped off from
+[lift](http://www.liftweb.net), needs to be added to support other frameworks.
Getting Started (Servlet API)
===============
-The management pages are web framework agnostic: they use their own mini
-framework, blatently inspired/ripped off from [lift](http://www.liftweb.net).
-
-It is incorrect to assume the Serlvet API as has been done in previous
-versions of this library because not all the web frameworks we want to use
-are necessarily written on a Serlvet API stack, eg Play, Blueeyes. In practice,
-the management library is web framework agnostic to a large extent but you will
-need a small adapter library to adapt the request and response abstractions to
-the HTTP interface in use in your desired web framework.
-
Add the dependency to your build
-----------------------------------
In your build.sbt:
- resolvers += "Guardian Github Snapshots" at "http://guardian.github.com/maven/repo-snapshots"
- libraryDependencies += "com.gu" %% "management-servlet-api" % "5.7-SNAPSHOT"
+ resolvers += "Guardian Github Snapshots" at "http://guardian.github.com/maven/repo-releases"
+ libraryDependencies += "com.gu" %% "management-servlet-api" % "5.7"
As of 5.7, Scala 2.8.1 and 2.9.0-1 are no longer supported. Upgrade your project
to Scala 2.9.1.
@@ -188,7 +101,6 @@ and a more complex page that supports POSTs is
-
Getting Started (Play Framework)
===============
@@ -197,8 +109,8 @@ Add the dependency to your build
In your build.sbt for sbt 0.10:
- resolvers += "Guardian Github Snapshots" at "http://guardian.github.com/maven/repo-snapshots"
- libraryDependencies += "com.gu" %% "management-play" % "5.7-SNAPSHOT"
+ resolvers += "Guardian Github Snapshots" at "http://guardian.github.com/maven/repo-releases"
+ libraryDependencies += "com.gu" %% "management-play" % "5.7"
As of 5.7, Scala 2.8.1 and 2.9.0-1 are no longer supported. Upgrade your project
to Scala 2.9.1.
@@ -254,3 +166,64 @@ the
and a more complex page that supports POSTs is
[the switchboard](https://github.com/guardian/guardian-management/blob/master/management/src/main/scala/com/gu/management/switchables.scala).
+
+Providing metrics for GANGLIA
+=====================
+Since version 5, guardian-management has been designed to allow application to simply provide metrics for consumption by the [Ganglia monitoring system](http://ganglia.sourceforge.net/).
+
+ * Metrics are presented by a StatusPage object, the name of which should be the name of your app:
+
+`new StatusPage("My App Name", Metrics.....)`
+
+So for example identity has 2 status pages:
+
+`new StatusPage("identity-webapp", Metrics.....)`
+`new StatusPage("identity-api", Metrics.....)`
+
+ * There are three types of metric currently supported:
+
+ * Timing: standard timing metric, takes number of events over a time period. Also provides a count of those events.
+ * Count: Constantly incrementing counter.
+ * Gauge: Count at a particular point in time.
+
+ * Creating A Metric
+
+You need to provide four arguments, with an optional fifth.
+
+`new TimingMetic("group", "name", "title", "description")`
+
+ GROUP: this is used as a logical grouping. Think of it as a noun. For example "emails"
+ NAME: This is a verb related to the noun defined in group. For example "sent"
+ TITLE: This is a text string used to title the graphs. Keep it short. For example "Emails Sent"
+ DESCRIPTION: This is a longer description of the metric. Used on the hover over.
+ For example "Total number of emails sent"
+
+Group and Name are munged together in ganglia to give the actual name used on the console.
+There is another console in Graphite (graphing tool) which will allow subdivision on group.
+Allowing you to see all the "emails" metrics and to create mash ups of all of these.
+Using the groups as it's top level option.
+
+As a rule use underscores (_) not hyphens (-) as delimiters.
+
+So in scala:
+
+`object SuccessfulEmails extends CountMetric("emails", "sent", "Emails Sent", "Number of emails sent")`
+
+The fifth metric is the field master. This takes Option[Metric] with a default of None.
+This is used to indicate that the metric you are creating is a child of a
+another metric. The parameter is the metric you wish to be a child of
+
+For example. Imagine there is a time taken for a request metric:
+
+`object Requests extends TimingMetric("requests", "api", "Api Requests Timer", "Total number and time taken for API request")`
+
+You may have a mongoDB requests metric, which is a child of the overall HTTP request:
+
+`object MongoRequests extends TimingMetric("requests", "mongodb", "Mongodb Requests", "Mongo request timer", Some(Requests))`
+
+This allows Ganglia to give the proportion of time of the HTTP request taken talking to mongo. You could have another:
+
+`object MongoRequests extends TimingMetric("requests", "oracle", "Oracle Requests", "Oracle request timer", Some(Requests))`
+
+Ganglia would now be able to show you propertions of each DB request as a proportion of total HTTP time.
+

No commit comments for this range

Something went wrong with that request. Please try again.