Stats Manager

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(General Concepts)
(Operations)
Line 42: Line 42:
 
* '''stat => stat.Value = RequestNumber''' - This is the anonymous function used to generate the stat on a pull request.  In this case, the RequestNumber within the HTTP management code is inserted into the stat value.
 
* '''stat => stat.Value = RequestNumber''' - This is the anonymous function used to generate the stat on a pull request.  In this case, the RequestNumber within the HTTP management code is inserted into the stat value.
 
* '''StatVerbosity.Debug''' - StatVerbosity can be Debug or Info.  Info should be used for stats that the user will always be interested in seeing (e.g. number of users on a region) and Debug for debugging stats (such as HTTP requests served).  However, right now stat display is not filtered on verbosity.
 
* '''StatVerbosity.Debug''' - StatVerbosity can be Debug or Info.  Info should be used for stats that the user will always be interested in seeing (e.g. number of users on a region) and Debug for debugging stats (such as HTTP requests served).  However, right now stat display is not filtered on verbosity.
 +
 +
== Registering a stat==
 +
A created stat must then be registered with the StatsManager.  In the case of our example above, this is done as follows.
 +
 +
<source lang="csharp">
 +
StatsManager.RegisterStat(m_requestsProcessedStat);
 +
</source>
 +
 +
== Deregistering a stat==
 +
If your code is never disabled during runtime then you don't need to worry about deregistering the stat.  However, if it can be removed (e.g. because it is in a region module) then you can deregister a stat as follows.
 +
 +
<source lang="csharp">
 +
StatsManager.DeregisterStat(m_requestsProcessedStat);
 +
</source>

Revision as of 13:03, 29 December 2014

Contents

Introduction

The OpenSimulator stats manager system is the most modern stats implementation in OpenSimulator and will eventually replace all legacy systems. It allows statistics to be added, updated and removed at runtime. Statistics can be viewed via the console "show stats" command and recorded periodically to file for later analysis.

General Concepts

The full name of a stat has three components, separated by periods (.). In order, these are

  • category - The category of the stat (e.g. server, scene)
  • container - The containing object for this stat. For example, on scene this is the scene name (e.g. region 1). For server, this is the component to which the stat relates (e.g. memory, processor).
  • name - The stat itself. For example, ClientLogoutsDueToNoReceives or SimFPS.

Full names must be unique.

Operations

Creating a stat

A statistic is represented by an instance of the OpenSim.Framework.Monitoring.Stat class or one of its descendant classes. Here's an example that creates a stat for recording all the HTTP requests served by the webserver embedded in OpenSimulator.

m_requestsProcessedStat 
    = new Stat(
        "HTTPRequestsServed",
        "Number of inbound HTTP requests processed",
        "The number of inbound HTTP requests processed by the builtin HTTP server.",
        "requests",
        "httpserver",
        Port.ToString(),
        StatType.Pull,
        MeasuresOfInterest.AverageChangeOverTime,
        stat => stat.Value = RequestNumber,
        StatVerbosity.Debug);

This breaks down as follows

  • HTTPRequestsServed - The short name of this stat. This is the name used when the stat is displayed or recorded.
  • Number of inbound HTTP requests processed - The full name of this stat.
  • The number of inbound HTTP requests processed by the builtin HTTP server. - A description of this stat.
  • requests - The unit name for this stat.
  • httpserver - The category for this stat.
  • container - The container for this stat within the category. In this case, we use the port number as the "container" since this distinguishes this data from similar stats on other ports. Another example of a distinguishing container is the region name.
  • StatType.Pull - The statistic type. This is either Pull or Push. If Pull, then when a stat is required (e.g. if the user requests the information or it needs to be recorded), then it is gathered by the given pullAction (of which more below). If a statistic if push, then the pull action is null (or will be ignored) and the code registering the stat is responsible for updating the value directly on an ongoing basis.
  • MeasuresOfInterest.AverageChangeOverTime - This can be None or ChangeOverTime. If None, then only the raw stat is recorded. If ChangeOverTime, then StatsManager also derives the moving average over the last 24 samples.
  • stat => stat.Value = RequestNumber - This is the anonymous function used to generate the stat on a pull request. In this case, the RequestNumber within the HTTP management code is inserted into the stat value.
  • StatVerbosity.Debug - StatVerbosity can be Debug or Info. Info should be used for stats that the user will always be interested in seeing (e.g. number of users on a region) and Debug for debugging stats (such as HTTP requests served). However, right now stat display is not filtered on verbosity.

Registering a stat

A created stat must then be registered with the StatsManager. In the case of our example above, this is done as follows.

StatsManager.RegisterStat(m_requestsProcessedStat);

Deregistering a stat

If your code is never disabled during runtime then you don't need to worry about deregistering the stat. However, if it can be removed (e.g. because it is in a region module) then you can deregister a stat as follows.

StatsManager.DeregisterStat(m_requestsProcessedStat);
Personal tools
General
About This Wiki