|
FireSync API
|
Represents a health probe.
Health probes are intended to allow applications to report values that can be collected and presented as part of periodic health snapshots. Construction-time options can be used to specify the types of health snapshots in which a probe will be included:
Construction-time options only specify desired behavior; actual behavior is limited by the capabilities of the environment in which the application is running. E.g., if the environment does not support persistence, then the kHEALTH_OPTION_PERSIST flag will have no effect; probe construction will succeed as though this option had not been specified.
For persistent probes, if the probe value was previously logged to non-volatile storage, then the probe's initial value can be automatically loaded from the most recently-logged value at construction time by adding the kHEALTH_OPTION_RESTORE option. Alternatively, the most recently-logged value can be loaded to the probe's baseline property with the kHEALTH_OPTION_BASELINE option.
Health probes are identified within health snapshots via two distinct mechanisms. First, every health probe must have a unique string identifier (name). By convention, probe names consist of multiple forward-slash-separated components. E.g., "Camera/0/ExposureCount" might be used to represent the number of exposures on the first camera (camera 0) within a FireSync node. Second, health probes are also typically expected to have unique numeric identifiers. E.g., the probe with name "Camera/0/ExposureCount" is represented by the unique pair (id=kHEALTH_ID_CAMERA_EXPOSURE_COUNT, instance=0). Unique application-defined identifiers must have numeric values greater than kHEALTH_ID_APPLICATION_BASE; lower-numbered IDs are reserved for use by the FireSync platform.
While it is necessary to provide a unique name for every probe, it is only strictly required to define unique numeric identifiers for persistent probes (kHEALTH_OPTION_PERSIST). For streamed probes, kHEALTH_ID_NULL can be used to create anonymous probes. The health statistics associated with anonymous probes will appear in streamed health snapshots, but may not be recognizable by software tools that mine data via numeric IDs. Most often, anonymous probes are used informally, e.g., to avoid allocating a temporary unique ID.
Internally, health probes maintain two fields that contribute to the current value reported by the probe: 'value' and 'baseline'. The value and baseline fields can be specified independently (e.g., via the SetValue and SetBaseline methods). The quantity reported by the probe's public Value method is the sum of these two internal fields. E.g., the sequence SetBaseline(5), SetValue(10) produces a reported Value() of 15.
Use of baseline-related API features is strictly optional. The purpose of the baseline feature is to enable health indicators to express the current value of the probe in relation to a reference (baseline) value. If the kHEALTH_OPTION_BASELINE option is specified at construction time, then the most recent value from persistent storage will be used to initialize the probe baseline. This approach is most commonly used with persistent counters, relieving the client of the need to consider the value loaded from persistent storage when setting the current value of the probe. The previously-logged amount will automatically be added to the latest specified amount whenever the probe value is reported.
Health probes are associated with a health provider, which is the engine that periodically collects and summarizes health data. A default health provider may be installed by the application environment (e.g., physical, stand-alone FireSync node environments always include a default health provider). If not, or if a more specific collection provider is desired (e.g., in an application that instantiates multiple software-only nodes, where each node has its own health provider), use a kHealthProbe constructor that accepts a health provider reference as an input argument.
Public Member Functions | |
| kStatus | kHealthProbe_AddValue (kHealthProbe probe, k64s value) |
| Adds an amount to the current value of a health probe. More... | |
| kStatus | kHealthProbe_Construct (kHealthProbe *probe, const kChar *name, k32u id, k32u instance, k64s initialValue, kAlloc allocator) |
| Constructs a kHealthProbe object with default provider and options. More... | |
| kStatus | kHealthProbe_Construct (kHealthProbe *probe, const kChar *name, k32u id, k32u instance, k64s defaultValue, kHealth provider, kHealthOption options, kAlloc allocator) |
| Constructs a kHealthProbe object with the specified provider and options. More... | |
| k32u | kHealthProbe_Id (kHealthProbe probe) |
| Reports the ID of the health probe. More... | |
| k32u | kHealthProbe_Instance (kHealthProbe probe) |
| Reports the instance of the health probe. More... | |
| const kChar * | kHealthProbe_Name (kHealthProbe probe) |
| Reports the name of the health probe. More... | |
| kHealthOption | kHealthProbe_Options (kHealthProbe probe) |
| Reports the options associated with the indicator. More... | |
| kStatus | kHealthProbe_SetBaseline (kHealthProbe probe, k64s baseline) |
| Sets the baseline value. More... | |
| kStatus | kHealthProbe_SetValue (kHealthProbe probe, k64s value) |
| Sets the current value of a health probe. More... | |
| kStatus | kHealthProbe_UpdateBaseline (kHealthProbe probe) |
| Transfers the current probe value to the baseline. More... | |
| k64s | kHealthProbe_Value (kHealthProbe probe) |
| Reports the current value of the health probe. More... | |
