Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Finished README, pom.xml for Sonatype

  • Loading branch information...
commit 30d8e7dfbb7c247eeac27991534fd9b983dfaa7c 1 parent 1db30e9
@jakubholynet authored
Showing with 231 additions and 53 deletions.
  1. +125 −25 README.md
  2. +106 −28 pom.xml
View
150 README.md
@@ -1,34 +1,134 @@
-INTRO
-Light-weight, minimalistic, low-overhead lib for collecting and publishing performance statistics in production systems.
-Calls to the lib are usually injected via AOP.
+About perfstats-lib
+===========
-Overview:
-- code calls Statistics.recordMeasurement(String metricName, long duration [, unit])
-- the measurement is added to a list of values to process and the call returns
-- a background thread processes new measurement, updating aggregate values etc.
-- the collected values are made available via publishers such as JmxPublisher and PeriodicalLogPublisher
+What it is
+--------
-USAGE
+Perfstats-lib is a light-weight, minimalistic, low-overhead library for collecting and publishing performance statistics
+in production systems, written in Java. Calls to the library can be performed manually but are expected to be injected
+automatically to the production code via AOP. (That's one of the reasons for keeping the public API minimal.)
-Statistics.recordMeasurement("myBizMethod", 60);
-// => asynch. stored and updated count, avg, min, max, std.dev, ...
-// Computation strategy: rolling window x all values
+*Beware*: Most of the stuff written below is a plan. To see what is actually implemented, check the History section at the end.
-STATS
+Vision:
-- ignore lowest and highest N values (random extreems far behind normal values)
-- count avg, 10 min, 10 max, std.dev.
+- The production code calls measurement = PerfStats.startFor("myMethod"); ... measurement.stop() to record a duration
+ of a method execution
+- The measurement is added to a list of values to process and the call returns immediately
+- A background thread processes new measurement, updating aggregate values etc.
+- The collected values are made available via publishers such as JmxPublisher and PeriodicalLogPublisher
+
+What it is not
+-----------
+
+Perfstats-lib isn't a profiler, a generic monitoring software (i.e. no memory, JVM, CPU, etc. stats), a full-featured performance
+monitoring solution storing data to a DB, monitoring for multiple JVMs.
+
+When to use
+----------
+
+If you need to collect performance statistics of (few) known methods in your production code
+(i.e. using a profiler isn't feasible) and want to minimize the dependencies added to your production code.
+It's also useful if you need to collect performance statistics only temporarily.
+
+If you want performance monitoring to be an integral part of your application then you may prefer a more
+feature-rich solution such as NewRelic or Stajistics, that support data persistence.
+
+### Alternatives
+
+- A profiler
+- Perf4j
+- Integration into generic monitoring solutions such as NewRelic, Hyperic, Zabbix, or Nagios
+- Likely some more
+
+Usage
+====
+
+```
+OngoingMeasurement measurement = PerfStats.startFor("myBizMethod");
+// myBizMethod executes ...
+measurement.stop();
+...
+System.out.println(PerfStats.getMetric("myBizMethod").getMax());
+System.out.println(PerfStats.getMetric("myBizMethod").reportAsCsv());
+```
+
+Stats
+====
+
+Planned/implemented
+------------------
+
+- Count, avg, 10 quickest, 10 slowest, mean, std.dev., min, max
+- Perhaps we should ignore N (1-10 or a percent?) lowest and highest values so that mean and std. dev. aren't distorted too much
+ by a random and very rare extreme (such as an operating taking 30 min while average is 10s).
- running avg/dev or based on all values
-ATTRS OF INTEREST
+Aggregation strategies
+------------------
+
+1. Aggregation based on the complete history, i.e. all measurements collected (most accurate, unbounded memory growth)
+2. Running aggregates - only keep an aggregation of the historical values and use that to compute approximate values of the statistics
+ (only approximate results, limited memory use; the preferred strategy)
+3. Extremes-ignoring aggregation meta-strategy - ignore few smallest/largest measurements as described above
+
+Statistics considered for inclusion
+---------------------------
+
+(Partly copied from a source I do not remember anymore, perhaps NewRelic.)
+
+- Count The number of times this event has occurred.
+- ErrorCount The number of times this event ended in error.
+- AverageTime The average execution time, in the selected unit.
+- MaxTime The maximum execution time, in the selected unit.
+- MinTime The minimum execution time, in the selected unit.
+- StandardDeviation The standard deviation from the mean, in the selected unit.
+- LastInvocation The most recent date and time at which this event occurred.
+- Units The unit of measure for max, min, average, and stddev. Valid values are seconds, milliseconds, and nanoseconds. Defaults to milliseconds if unspecified.
+- The period when the logs were collected
+- Number of calls during a period (transactions per period)
+
+License
+=====
+
+[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
+
+Future & History
+==========
+
+Future plans
+----------
+
+- Support for non-invasive injection of the PerfStats calls via AOP (likely Javassist or similar) at build- (and perhaps also run-) time
+- Implementation of the Running Aggregates strategy
+- More stats (primarily mean and std. dev.)
+- Support for counters in addition to durations (e.g. to count the number of errors, possibly keeping last N of them)
+- Add more publishers (PeriodicalMetaPublisher, ScheduledMetaPublisher, JavaUtilLoggingPublisher, JmxPublisher, SysoutPublisher, ...)
+- That's it, folks. I told you it's minimalistic, haven't I? :-)
+
+History
+------
+
+### Current limitations
+
+- There is only one instance of PerfStats per JVM (you might prefer e.g. one per webapp)
+
+### 1.0 (5/2012)
+
+- Collect basic statistics (min, max, avg, count)
+- Return all the collected stats as a comma-separated values (CSV) string
+- Aggregation based on the complete history
+- All the processing is done synchronously (but the aggregates are only computed on-demand)
+
+Related projects
+-------------
-Count attribute The number of times this event has occurred.
-ErrorCount attribute The number of times this event ended in error.
-AverageTime attribute The average execution time, in the selected unit.
-MaxTime attribute The maximum execution time, in the selected unit.
-MinTime attribute The minimum execution time, in the selected unit.
-StandardDeviation attribute The standard deviation from the mean, in the selected unit.
-LastInvocation attribute The most recent date and time at which this event occurred.
-Units attribute The unit of measure for max, min, average, and stddev. Valid values are seconds, milliseconds, and nanoseconds. Defaults to milliseconds if unspecified.
-reset operation Reset statistics for this type of event.
+- [Perf4j](http://perf4j.codehaus.org/) - integrates tightly with a logging framework and its appenders for recording/aggregating stats;
+ some good stuff to copy :-) such as real-time graphs and JMX support
+- [Stajistics](http://code.google.com/p/stajistics/wiki/Introduction) - a powerful monitoring and runtime performance statistics collection library
+ intended for continuous use in production systems with support for persistence and historical comparisons
+
+Closing words
+-----------
+Contribution and feedback are welcomed :-).
View
134 pom.xml
@@ -2,13 +2,49 @@
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.sonatype.oss</groupId>
+ <artifactId>oss-parent</artifactId>
+ <version>7</version>
+ </parent>
+
<groupId>net.jakubholy.jeeutils</groupId>
<artifactId>perfstats-lib</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>perfstats-lib</name>
- <url>http://maven.apache.org</url>
+ <url>https://github.com/jakubholynet/perfstats-lib</url>
+ <description>A light-weight, minimalistic, low-overhead library for collecting and publishing performance statistics.</description>
+
+ <scm>
+ <connection>scm:git:git@github.com:jakubholynet/perfstats-lib.git</connection>
+ <developerConnection>scm:git:git@github.com:jakubholynet/perfstats-lib.git</developerConnection>
+ <url>git@github.com:jakubholynet/perfstats-lib.git</url>
+ </scm>
+
+ <licenses>
+ <license>
+ <name>The Apache Software License, Version 2.0</name>
+ <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
+ </license>
+ </licenses>
+
+ <developers>
+ <developer>
+ <id>jakubholynet</id>
+ <name>Jakub Holy</name>
+ <organization>Iterate AS</organization>
+ <organizationUrl>http://iterate.no/</organizationUrl>
+ <url>http://theholyjava.wordpress.com/</url>
+ </developer>
+ <developer>
+ <id>mortenberg80</id>
+ <name>Morten Berg</name>
+ <organization>Iterate AS</organization>
+ <organizationUrl>http://iterate.no/</organizationUrl>
+ </developer>
+ </developers>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@@ -16,12 +52,6 @@
<dependencies>
-<!-- <dependency> -->
-<!-- <groupId>org.codehaus.gmaven.runtime</groupId> -->
-<!-- <artifactId>gmaven-runtime-1.8</artifactId> -->
-<!-- <version>1.4</version> -->
-<!-- </dependency> -->
-
<dependency>
<groupId>junit</groupId>
<artifactId>junit-dep</artifactId>
@@ -45,24 +75,72 @@
</dependency>
</dependencies>
-<!--
- <build>
- <plugins>
- <plugin>
- <groupId>org.codehaus.gmaven</groupId>
- <artifactId>gmaven-plugin</artifactId>
- <executions>
- <execution>
- <goals>
- <goal>generateStubs</goal>
- <goal>compile</goal>
- <goal>generateTestStubs</goal>
- <goal>testCompile</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- -->
-</project>
+
+
+ <profiles>
+
+ <profile>
+ <id>release-sign-artifacts</id>
+
+ <properties>
+ <gpg.keyname>8A7E15EF</gpg.keyname>
+ <!-- GPG Key ID to use for signing -->
+ </properties>
+
+ <build>
+ <plugins>
+ <!-- Build, sign and deploy: mvn -DperformRelease=true deploy -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-gpg-plugin</artifactId>
+ <version>1.3</version>
+ <executions>
+ <execution>
+ <id>sign-artifacts</id>
+ <phase>verify</phase>
+ <goals>
+ <goal>sign</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Publish also javadocs when releasing - required by Sonatype -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>2.6.1</version>
+ <configuration>
+ <show>public</show>
+ </configuration>
+ <executions>
+ <execution>
+ <id>attach-javadocs</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+ <!-- Publish also sources when releasing - required by Sonatype -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-source-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>attach-sources</id>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+ </build>
+
+ </profile>
+ </profiles>
+
+</project>
Please sign in to comment.
Something went wrong with that request. Please try again.