The Sampler API allows modules to easily collect and store calculated pieces of data. It's designed primarily to assist in collection, storage, and display of metrics.

Modules provide the API with a metric to track (eg. 'Number of comments added to a node') a listing of objects to be tracked (for example, you may only want to track that for certain nodes) , a sampling strategy (eg. 'every 3 days'), and a method that returns the calculated values for the metric (eg. 'give me the values that you want to store for the period of January 1st midnight to January 4th midnight).

Based on the provided data, the framework:

• Performs calculations to determine the how to sample for the metric
• Calls the necessary functions to gather the calculated values
• Handles all storage of the metrics
• Provides default views of the metrics

Metrics are made available to the API via plugins, and are responsible for handling the calculations that the API tracks. This architecture allows for a large amount of flexibility in what can be collected and stored -- there are thousand of things that could be measured, and the API makes no attempt to decide which ones matter.

Metrics can take arbitrary options to assist in making the calculation functionality even more flexible -- and sampling strategies, adjustments to sample sets and sample results, and storage of the calcuated values are all pluggable.

A Drush plugin is included which is used to trigger the sampling, and can be used to pull the custom samples mentioned above.

An example module is included to help get you up to speed on how to create new metrics.