Sensors

Sensors — Sensor support functions

Synopsis


#include <monitor/producer/sensor.h>


#define     PROD_SYMBOL_SENSOR
#define     PROD_SENSOR_MODULE              (desc)
#define     PROD_SENSOR_API
            prod_sensor_module;
int         (*prod_metric_sample)           (prod_metric_instance *mi,
                                             void *measurement_id,
                                             mon_ctx *ctx);
            prod_metric_desc;
int         prod_sensor_add                 (prod_sensor_module *module,
                                             prod_module_type type);
int         prod_sensor_register            (mon_module *module);
void        prod_sensor_unregister          (mon_module *module);
void        prod_sensor_done                (prod_sensor_module *sensor);
void        prod_sensor_ref                 (prod_sensor_module *sensor);
int         prod_sensor_get                 (mon_metric_def *def,
                                             mon_arg_list *arg,
                                             mon_module **sensor,
                                             uint32_t *sensor_id,
                                             mon_ctx *ctx);
int         prod_sensor_set_priority        (prod_sensor_module *sensor,
                                             int priority);
            prod_sensor_param;
int         prod_sensor_param_register      (prod_sensor_param *p);
void        prod_sensor_param_unregister    (prod_sensor_param *p);
prod_sensor_param* prod_sensor_param_query  (const char *s);

int         prod_sensor_check_metric        (prod_sensor_module *sensor,
                                             mon_metric_def *def,
                                             mon_arg_list *args,
                                             uint32_t *sensor_id,
                                             mon_ctx *ctx);
int         prod_sensor_start_instance      (prod_metric_instance *mi,
                                             mon_ctx *ctx);
int         prod_sensor_send_int32          (prod_metric_instance *mi,
                                             void *measurement_id,
                                             int32_t val);
int         prod_sensor_send_uint32         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             uint32_t val);
int         prod_sensor_send_int64          (prod_metric_instance *mi,
                                             void *measurement_id,
                                             int64_t val);
int         prod_sensor_send_uint64         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             uint64_t val);
int         prod_sensor_send_string         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             const char *val);

            prod_metric_instance;
enum        prod_metric_flags;
enum        prod_metric_event;
prod_metric_instance* prod_metric_instance_new
                                            (prod_sensor_module *sensor,
                                             mon_metric_def *md,
                                             mon_arg_list *args,
                                             uint32_t sensor_id);
void        prod_metric_instance_done       (prod_metric_instance *mi);
void        prod_metric_instance_ref        (prod_metric_instance *mi);
void        prod_metric_instance_mid_del    (prod_metric_instance *mi,
                                             prod_metric_id *mid);
int         prod_metric_instance_mid_add    (prod_metric_instance *mi,
                                             prod_metric_id *mid);
prod_metric_instance* prod_metric_instance_lookup
                                            (mon_metric_def *md,
                                             mon_arg_list *args);
void        prod_metric_instance_set_sample (prod_metric_instance *mi,
                                             prod_metric_sample sample);
void        prod_metric_instance_set_aux    (prod_metric_instance *mi,
                                             void *user_data,
                                             GDestroyNotify user_data_done);
void        prod_metric_instance_kill       (prod_metric_instance *mi);
void        prod_metric_instance_send_dropped
                                            (prod_metric_instance *mi,
                                             uint32_t count);

            prod_metric_value;
prod_metric_value* prod_metric_value_new    (prod_metric_instance *mi,
                                             void *measurement_id);
prod_metric_value* prod_metric_value_new_time
                                            (prod_metric_instance *mi,
                                             void *measurement_id,
                                             struct timespec *timestamp);
void        prod_metric_value_done          (prod_metric_value *mv);
void        prod_metric_value_ref           (prod_metric_value *mv);
void        prod_metric_value_send          (prod_metric_value *mv);

            prod_metric_id;
enum        prod_metric_id_flags;
int         prod_mid_new                    (prod_user *u,
                                             prod_metric_instance *mi,
                                             prod_metric_id **mid);
void        prod_mid_done                   (prod_metric_id *mid);
void        prod_mid_ref                    (prod_metric_id *mid);
int         prod_mid_ctx_add                (prod_metric_id *mid,
                                             prod_conn *conn,
                                             mon_ctx *ctx);
void        prod_mid_ctx_del                (prod_metric_id *mid,
                                             mon_ctx *ctx);
int         prod_mid_conn_add               (prod_metric_id *mid,
                                             prod_conn *conn);
void        prod_mid_conn_del               (prod_metric_id *mid,
                                             prod_conn *conn);
void        prod_mid_send_metric            (prod_metric_id *mid,
                                             prod_metric_value *mv);

Description

Details

PROD_SYMBOL_SENSOR

#define PROD_SYMBOL_SENSOR	MON_MODSYM(prod_module_sensor)

Defines the symbol name of the sensor module descriptor table in a loadable module.


PROD_SENSOR_MODULE()

#define     PROD_SENSOR_MODULE(desc)

Declares a sensor module.

desc :the name of the prod_sensor_module descriptor.

PROD_SENSOR_API

#define PROD_SENSOR_API		2

Defines the sensor API version implemented by the library.


prod_sensor_module

typedef struct {
	mon_module		header;

	unsigned int		priority;

	const prod_metric_desc	*metric_table;
	const char		*metric_glob;

	int			(*check_metric)(prod_sensor_module *s,
					mon_metric_def *def,
					mon_arg_list *args,
					uint32_t *sensor_id,
					mon_ctx *ctx);
	int			(*start_instance)(prod_metric_instance *mi,
					mon_ctx *ctx);
	void			(*notify)(prod_metric_instance *mi,
					prod_metric_event event,
					void *event_data);
} prod_sensor_module;

Represents a sensor module. The start_instance method is called only if the check_metric method returned success, so it does not need to repeat parameter checks already performed in check_metric.

mon_module header;the general module header.
unsigned int priority;priority of the sensor.
const prod_metric_desc *metric_table;a table containing metrics supported by this sensor. This is needed only if the module wants to use prod_sensor_check_metric().
const char *metric_glob;a pattern matching all the metrics supported by this sensor. This is used by libproducer to make sensor lookup for a given metric name faster.
check_metric ()checks that the metric definition and parameters are acceptable by the sensor.
start_instance ()the local constructor for metric instances. This method should allocate any resources the sensor needs to perform measurements for this metric instance.
notify ()notifies the sensor module about prod_metric_event events.

prod_metric_sample ()

int         (*prod_metric_sample)           (prod_metric_instance *mi,
                                             void *measurement_id,
                                             mon_ctx *ctx);

Metric sampling function prototype.

mi :a prod_metric_id.
measurement_id :an opaque cookie identifying the measurement.
ctx :a mon_ctx execution context.
Returns :0 if successful, MON_CONTINUE in case of asynchronous execution, or an error code.

prod_metric_desc

typedef struct {
	const char		*name;
	prod_metric_sample	sample;
	uint32_t		sensor_id;
} prod_metric_desc;

Describes a metric supported by a sensor.

const char *name;the name of the metric.
prod_metric_sample sample;the sampling function for this metric (may be NULL for event-like metrics).
uint32_t sensor_id;opaque identifier that may be used by the sensor.

prod_sensor_add ()

int         prod_sensor_add                 (prod_sensor_module *module,
                                             prod_module_type type);

Registers a new sensor module.

module :the prod_sensor_module to register.
type :the type of the module.
Returns :0 if successful or an error code.

prod_sensor_register ()

int         prod_sensor_register            (mon_module *module);

Wrapper around prod_sensor_add() for registering dynamically loaded sensors.

module :a prod_sensor_module to register.
Returns :0 if successful or an error code.

prod_sensor_unregister ()

void        prod_sensor_unregister          (mon_module *module);

Unregisters a sensor module.

module :a prod_sensor_module to unregister.

prod_sensor_done ()

void        prod_sensor_done                (prod_sensor_module *sensor);

Decrements the reference count for a prod_sensor_module. If the reference count reaches zero, the module is deallocated (or unloaded if it was a DSO).

sensor :a prod_sensor_module.

prod_sensor_ref ()

void        prod_sensor_ref                 (prod_sensor_module *sensor);

Increments the reference count for a prod_sensor_module.

sensor :a prod_sensor_module.

prod_sensor_get ()

int         prod_sensor_get                 (mon_metric_def *def,
                                             mon_arg_list *arg,
                                             mon_module **sensor,
                                             uint32_t *sensor_id,
                                             mon_ctx *ctx);

Initiates a search for a prod_sensor_module that supports the metric def.

def :a mon_metric_def.
arg :the metric arguments.
sensor :pointer to store the sensor module if successful.
sensor_id :pointer to store an opaque internal identifier returned by the check_metric method.
ctx :a mon_ctx execution context.
Returns :0 if successful or an error code.

prod_sensor_set_priority ()

int         prod_sensor_set_priority        (prod_sensor_module *sensor,
                                             int priority);

Sets the priority of a sensor.

sensor :a prod_sensor_module.
priority :the new priority of the sensor.
Returns :0 if successful or an error code.

prod_sensor_param

typedef struct {
	char			*name;
	mon_basic_type		type;
	int			(*check)(prod_metric_id *mid,
					mon_simple_val *value);
} prod_sensor_param;

Defines an operational parameter for sensors.

char *name;the name of the parameter.
mon_basic_type type;type of the parameter.
check ()function to call if this parameter is encountered. If this function returns an error, the request for the metric will be rejected.

prod_sensor_param_register ()

int         prod_sensor_param_register      (prod_sensor_param *p);

Registers an operational sensor parameter.

p :a prod_sensor_param.
Returns :0 if successful or an error code.

prod_sensor_param_unregister ()

void        prod_sensor_param_unregister    (prod_sensor_param *p);

Unregisters an operational sensor parameter.


prod_sensor_param_query ()

prod_sensor_param* prod_sensor_param_query  (const char *s);

Returns the definition of an operational parameter.

s :the name of the parameter.
Returns :a prod_sensor_param or NULL if s is not an operational parameter.

prod_sensor_check_metric ()

int         prod_sensor_check_metric        (prod_sensor_module *sensor,
                                             mon_metric_def *def,
                                             mon_arg_list *args,
                                             uint32_t *sensor_id,
                                             mon_ctx *ctx);

Checks if a given metric is valid. It only checks if the metric name appears in the metric_table of sensor, no parameter checks are performed. If the metric name is found in the table, the SAMPLE data key in ctx will hold the sample function, and the SENSOR_ID data key will hold the sensor_id that was specified in the metric_table.

sensor :the sensor to validate the metric name against.
def :a metric definition.
args :metric arguments (not used by this function).
sensor_id :pointer to store an opaque internal identifier that may be used by the sensor to identify the metric.
ctx :a mon_ctx.
Returns :0 if the metric name is supported by the sensor or MON_ERR_UNKNOWN_METRIC otherwise.

prod_sensor_start_instance ()

int         prod_sensor_start_instance      (prod_metric_instance *mi,
                                             mon_ctx *ctx);

Sets the metric sampling function for a prod_metric_instance. It is inteded as a helper function for sensors. The sampling function must either be set by the check_metric method in ctx using the "SAMPLE" key, or it must be defined in the sensor's metric table.

mi :a prod_metric_instance.
ctx :a mon_ctx.
Returns :0 if successful or an error code.

prod_sensor_send_int32 ()

int         prod_sensor_send_int32          (prod_metric_instance *mi,
                                             void *measurement_id,
                                             int32_t val);

Sends a 32-bit integer metric value.

mi :a prod_metric_instance.
measurement_id :an opaque measurement id.
val :the value to send.
Returns :0 if successful or an error code.

prod_sensor_send_uint32 ()

int         prod_sensor_send_uint32         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             uint32_t val);

Sends an unsigned 32-bit integer metric value.

mi :a prod_metric_instance.
measurement_id :an opaque measurement id.
val :the value to send.
Returns :0 if successful or an error code.

prod_sensor_send_int64 ()

int         prod_sensor_send_int64          (prod_metric_instance *mi,
                                             void *measurement_id,
                                             int64_t val);

Sends a 64-bit integer metric value.

mi :a prod_metric_instance.
measurement_id :an opaque measurement id.
val :the value to send.
Returns :0 if successful or an error code.

prod_sensor_send_uint64 ()

int         prod_sensor_send_uint64         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             uint64_t val);

Sends an unsigned 64-bit integer metric value.

mi :a prod_metric_instance.
measurement_id :an opaque measurement id.
val :the value to send.
Returns :0 if successful or an error code.

prod_sensor_send_string ()

int         prod_sensor_send_string         (prod_metric_instance *mi,
                                             void *measurement_id,
                                             const char *val);

Sends a string metric value.

mi :a prod_metric_instance.
measurement_id :an opaque measurement id.
val :the value to send.
Returns :0 if successful or an error code.

prod_metric_instance

typedef struct {
	/* Fields controlled by the sensor module */
	prod_metric_sample	sample;
	void			*user_data;
	GDestroyNotify		user_data_done;
	uint32_t		sensor_id;

	/* Fields controlled by the producer library */
	prod_metric_flags	flags;
	mon_metric_def		*metric;
	mon_arg_list		*args;
	mon_list		mids;
	prod_sensor_module	*sensor;

	int			refcnt;
} prod_metric_instance;

Describes a metric instance.

prod_metric_sample sample;the sampling function. May be NULL for event-like metrics.
void *user_data;sensor-specific data.
GDestroyNotify user_data_done;destructor for user_data.
uint32_t sensor_id;opaque identifier used by the sensor.
prod_metric_flags flags;metric instance flags.
mon_metric_def *metric;the metric definition.
mon_arg_list *args;the metric arguments.
mon_list mids;list of prod_metric_id elements belonging to this metric.
prod_sensor_module *sensor;the prod_sensor_module providing this metric.
int refcnt;reference count.

enum prod_metric_flags

typedef enum {
	PROD_METRIC_STARTED	= (1 << 0),
	PROD_METRIC_DONTSHARE	= (1 << 1),
	PROD_METRIC_SHARED	= (1 << 2)
} prod_metric_flags;

Flags for prod_metric_instance.

PROD_METRIC_STARTEDthe sensor's start_instance method was successfully called for this prod_metric_instance.
PROD_METRIC_DONTSHAREthe metric instance cannot be shared between different users.
PROD_METRIC_SHAREDthe metric instance is shared between (possibly different) users.

enum prod_metric_event

typedef enum {
	PROD_METRIC_EVENT_STARTED,
	PROD_METRIC_EVENT_SUBSCRIBED
} prod_metric_event;

Metric instance events.

PROD_METRIC_EVENT_STARTEDsent when the producer has finished the setting up of a metric instance.
PROD_METRIC_EVENT_SUBSCRIBEDsent when a new prod_metric_id is created. The event data contains the measurement ID cookie that can be used with prod_metric_value_new().

prod_metric_instance_new ()

prod_metric_instance* prod_metric_instance_new
                                            (prod_sensor_module *sensor,
                                             mon_metric_def *md,
                                             mon_arg_list *args,
                                             uint32_t sensor_id);

Create a new metric instance using md as the metric definition and args as the values of the formal parameters.

sensor :a prod_sensor_module.
md :a mon_metric_def.
args :a mon_arg_list.
sensor_id :opaque identifier used by the sensor.
Returns :a prod_metric_instance or NULL on error.

prod_metric_instance_done ()

void        prod_metric_instance_done       (prod_metric_instance *mi);

Decrements the reference count of a prod_metric_instance. If the reference count reaches zero, the metric instance is destroyed.


prod_metric_instance_ref ()

void        prod_metric_instance_ref        (prod_metric_instance *mi);

Increments the reference count of a prod_metric_instance.


prod_metric_instance_mid_del ()

void        prod_metric_instance_mid_del    (prod_metric_instance *mi,
                                             prod_metric_id *mid);

Removes a prod_metric_id from a prod_metric_instance.


prod_metric_instance_mid_add ()

int         prod_metric_instance_mid_add    (prod_metric_instance *mi,
                                             prod_metric_id *mid);

Adds a prod_metric_id to a prod_metric_instance.

mi :a prod_metric_instance.
mid :a prod_metric_id.
Returns :0 if successful or an error code.

prod_metric_instance_lookup ()

prod_metric_instance* prod_metric_instance_lookup
                                            (mon_metric_def *md,
                                             mon_arg_list *args);

Searches for an already existing metric instance with the same definition and argument list as md and args.

md :a mon_metric_def.
args :metric arguments.
Returns :a cached prod_metric_instance or NULL if it does not exist yet.

prod_metric_instance_set_sample ()

void        prod_metric_instance_set_sample (prod_metric_instance *mi,
                                             prod_metric_sample sample);

Sets the sampling function of a prod_metric_instance.

mi :a prod_metric_instance.
sample :the sampling function.

prod_metric_instance_set_aux ()

void        prod_metric_instance_set_aux    (prod_metric_instance *mi,
                                             void *user_data,
                                             GDestroyNotify user_data_done);

Sets the sensor-private data of a prod_metric_instance.

mi :a prod_metric_instance.
user_data :opaque sensor-private data.
user_data_done :destructor for user_data.

prod_metric_instance_kill ()

void        prod_metric_instance_kill       (prod_metric_instance *mi);

Kills a prod_metric_instance. A MON_MID_KILLED message will be sent for every prod_metric_id belonging to the instance.


prod_metric_instance_send_dropped ()

void        prod_metric_instance_send_dropped
                                            (prod_metric_instance *mi,
                                             uint32_t count);

Sends a MON_MID_DROPPED message for this metric instance indicating that metric values were lost.

mi :a prod_metric_instance.
count :the number of dropped messages to report.

prod_metric_value

typedef struct {
	int			refcnt : 16;
	mon_metric_def_domain	domain : 16;
	void			*measurement_id;
	struct timespec		timestamp;
	mon_buffer		data;

	union
	{
		prod_metric_instance	*mi;
		prod_ctrl_instance	*ci;
	};
} prod_metric_value;

Describes a metric value generated by a sensor.

int refcnt : 16;reference count.
mon_metric_def_domain domain : 16;either MON_DOM_METRIC or MON_DOM_CTRL.
void *measurement_id;opaque identifier of the measurement that generated this metric value. Inside the producer library, measurement_id is actually a prod_metric_id. measurement_id is NULL for event-like metrics.
struct timespec timestamp;time of the generation of this metric value.
mon_buffer data;a mon_buffer containing the actual data.
prod_metric_instance *mi;a prod_metric_instance if domain is MON_DOM_METRIC.
prod_ctrl_instance *ci;a prod_ctrl_instance if domain is MON_DOM_CTRL.

prod_metric_value_new ()

prod_metric_value* prod_metric_value_new    (prod_metric_instance *mi,
                                             void *measurement_id);

Allocates a new prod_metric_value.

The mi parameter specifies the metric instance this value belongs to. When the value should go only to one channel (e.g. as a result of a GET command), mid specifies the prod_metric_id where it should go. If the value should go to every subscribed channels, mid is NULL.

mi :the prod_metric_instance this value belongs to.
measurement_id :inside libproducer, the prod_metric_id this value belongs to. Inside module_loader, just an opaque cookie.
Returns :a prod_metric_value.

prod_metric_value_new_time ()

prod_metric_value* prod_metric_value_new_time
                                            (prod_metric_instance *mi,
                                             void *measurement_id,
                                             struct timespec *timestamp);

Allocates a new prod_metric_value like prod_metric_value_new() but allows to specify the timestamp (and thus save a gettimeofday() call).

mi :the prod_metric_instance this value belongs to.
measurement_id :inside libproducer, the prod_metric_id this value belongs to. Inside module_loader, just an opaque cookie.
timestamp :the timestamp to use.
Returns :a prod_metric_value.

prod_metric_value_done ()

void        prod_metric_value_done          (prod_metric_value *mv);

Drop a reference to a prod_metric_value. When the last reference is gone, the memory allocated to mv will be freed.


prod_metric_value_ref ()

void        prod_metric_value_ref           (prod_metric_value *mv);

Increase the reference count of a prod_metric_value.


prod_metric_value_send ()

void        prod_metric_value_send          (prod_metric_value *mv);

Sends a prod_metric_value to all channels it is either SUBSCRIBEd to or BUFFEREd on. This function takes care of freeing the metric value when it is no longer needed. Callers should not use the metric value after calling this function.


prod_metric_id

typedef struct {
	uint32_t		id;
	prod_metric_instance	*mi;
	prod_user		*user;
	GList			*filters;
	GList			*connections;
	GList			*pending_ctxs;
	int			refcnt : 16;
	prod_metric_id_flags	flags : 16;

	/* Used by the user object */
	prod_metric_id		*next;
} prod_metric_id;

Represents data bound to a metric id.

uint32_t id;the numerical metric id used by the monitoring protocol.
prod_metric_instance *mi;the prod_metric_instance this id belongs to.
prod_user *user;the prod_user this id belongs to.
GList *filters;list of filters (see prod_filter) active on this id.
GList *connections;list of connections this id is associated with.
GList *pending_ctxs;list of mon_ctx execution contexts belonging to commands being performed on this id.
int refcnt : 16;reference count.
prod_metric_id_flags flags : 16;flags.
prod_metric_id *next;pointer used by prod_user to chain its metric ids.

enum prod_metric_id_flags

typedef enum {
	PROD_MID_SINGLESHOT	= (1 << 0)
} prod_metric_id_flags;

Flags for prod_metric_id.

PROD_MID_SINGLESHOTthe metric id must be destroyed after the first metric value has been sent to it. This flag is used for implementing the QUERY and EXECUTE commands.

prod_mid_new ()

int         prod_mid_new                    (prod_user *u,
                                             prod_metric_instance *mi,
                                             prod_metric_id **mid);

Allocates a prod_metric_id.

u :a prod_user.
mi :a prod_metric_instance.
mid :pointer to store the prod_metric_id if successful.
Returns :0 if successful or an error code.

prod_mid_done ()

void        prod_mid_done                   (prod_metric_id *mid);

Decrements the reference count of a prod_metric_id. If the reference count reaches zero, the structure is deallocated.

mid :a prod_metric_id.

prod_mid_ref ()

void        prod_mid_ref                    (prod_metric_id *mid);

Increments the reference count of a prod_mid_ref.

mid :a prod_metric_id.

prod_mid_ctx_add ()

int         prod_mid_ctx_add                (prod_metric_id *mid,
                                             prod_conn *conn,
                                             mon_ctx *ctx);

Adds a pending mon_ctx execution context to a prod_metric_id.

mid :a prod_metric_id.
conn :the connection the command arrived on.
ctx :a mon_ctx.
Returns :0 if successful or an error code.

prod_mid_ctx_del ()

void        prod_mid_ctx_del                (prod_metric_id *mid,
                                             mon_ctx *ctx);

Removes a pending mon_ctx from a prod_metric_id.

mid :a prod_metric_id.
ctx :a mon_ctx.

prod_mid_conn_add ()

int         prod_mid_conn_add               (prod_metric_id *mid,
                                             prod_conn *conn);

Adds a prod_conn to a prod_metric_id.

mid :a prod_metric_id.
conn :a prod_conn.
Returns :0 if successful or an error code.

prod_mid_conn_del ()

void        prod_mid_conn_del               (prod_metric_id *mid,
                                             prod_conn *conn);

Removes a prod_conn from a prod_metric_id.

mid :a prod_metric_id.
conn :a prod_conn.

prod_mid_send_metric ()

void        prod_mid_send_metric            (prod_metric_id *mid,
                                             prod_metric_value *mv);

Sends a metric value to a specific metric id.