1MMV_STATS_REGISTRY(3) Library Functions Manual MMV_STATS_REGISTRY(3)
2
6 mmv_stats_registry - Initialize the Memory Mapped Value file
7
9 #include <pcp/pmapi.h>
10 #include <pcp/mmv_stats.h>
11 mmv_registry_t *mmv_stats_registry(const char *file, int cluster,
13 mmv_stats_flags_t flags);
14 void *mmv_stats_start(mmv_registry_t *registry);
16 void mmv_stats_stop(const char *fname, void *addr);
17 cc ... -lpcp_mmv -lpcp
19
21 mmv_stats_registry initializes an opaque structure that defines various
22 aspects of a memory mapped file. This file is used for lightweight in‐
23 terprocess communication between an instrumented application and pm‐
24 dammv(1).
25 The mmv_stats_registry interface is used to allocate a registry, and
27 allows the name of the MMV(5) file, the cluster identifier and the
28 flags (if any) to be set. It returns a handle that is used in subse‐
29 quent MMV API calls when adding metrics, indoms, instances and labels
30 to the registry - before actually creating the file.
31 mmv_stats_start is the call that creates the MMV(5) file with the han‐
33 dle that returns mmv_stats_registry. It returns the mapped memory han‐
34 dle used in subsequent MMV API calls, such as mmv_inc_value(3).
35 mmv_stats_stop performs an orderly shutdown of the mapping handle re‐
37 turned by an earlier initialization call and also frees the registry
38 structure.
39 The combination of mmv_stats_registry and mmv_stats_start do the same
41 as the deprecated calls mmv_stats(2)_init. However, now, one should
42 first call mmv_stats_registry and then the API calls that add in‐
43 stances, indoms, metrics and labels. In this way, there is no need to
44 know in advance which version of the MMV(1|2|3) mapping will be used as
45 it is calculated automatically.
46 The file is created in the $PCP_TMP_DIR/mmv directory, the name argu‐
48 ment is expected to be a basename of the file, not the full path. The
49 metadata content of the file does not change after the file has been
50 created.
51 The old file is removed unconditionally unless there was an error.
53 cluster is the preferred MMV PMDA cluster ID to be used for the metrics
55 the originates the call mmv_stats_start. The flags provide additional
56 control over the behaviour of the MMV PMDA - e.g. use of
57 MMV_FLAG_PROCESS will ensure values are only exported when the instru‐
58 mented application is running - this is verified on each request for
59 new values.
60 The next sections explain how to add metrics, indoms, instances and la‐
62 bels.
63
65 int mmv_stats_add_metric(mmv_registry_t *registry, const char *name,
66 int item,
67 mmv_metric_type_t type, mmv_metric_sem_t sem,
68 pmUnits units,
69 int serial, const char *shorthelp, con‐
70 st char *longhelp);
71 When adding a metric, internally it is being handled using the next
73 struct. sem match in the struct is semantics. units match in the
74 struct is dimension. serial match in the struct is indom.
75 typedef struct {
77 char *name; /* Name of the metric */
78 __uint32_t item; /* Item component of PMID */
79 mmv_metric_type_t type; /* Type of the metric */
80 mmv_metric_sem_t semantics; /* Semantics of the metric */
81 pmUnits dimension; /* Dimensions (TIME,SPACE,etc) */
82 __uint32_t indom; /* Instance domain identifier */
83 char *shorttext; /* Optional, one-line help */
84 char *helptext; /* Optional, full help text */
85 } mmv_metric2_t;
86
88 int mmv_stats_add_indom(mmv_registry_t *registry, int serial,
89 const char *shorthelp, const char *longhelp);
90 When adding an indom, internally it is being handled using the next
93 struct.
94 typedef struct {
96 __uint32_t serial; /* Unique serial number */
97 __uint32_t count; /* Number of instances */
98 mmv_instances2_t *instances; /* Internal/external IDs */
99 char *shorttext; /* Short help text */
100 char *helptext; /* Long help text */
101 } mmv_indom2_t;
102
105 int mmv_stats_add_instance(mmv_registry_t *registry, int serial,
106 int instid, const char *instname);
107 When adding an instance, internally it is being handled using the next
109 struct. instid match in the struct is internal while instname is ex‐
110 ternal.
111 typedef struct {
113 __int32_t internal;
114 char *external;
115 } mmv_instances2_t;
116 It is worth mentioning that if the indom of the instance is not found
119 it returns an error.
120
122 int mmv_stats_add_registry_label(mmv_registry_t *registry,
123 const char *name, const char *value,
124 mmv_value_type_t type, int optional);
125 int mmv_stats_add_indom_label(mmv_registry_t *registry, int serial,
127 const char *name, const char *value,
128 mmv_value_type_t type, int optional);
129 int mmv_stats_add_metric_label(mmv_registry_t *registry, int item,
131 const char *name, const char *value,
132 mmv_value_type_t type, int optional);
133 int mmv_stats_add_instance_label(mmv_registry_t *registry, int serial,
135 int instid, const char *name, const
136 char *value,
137 mmv_value_type_t type, int optional);
138 registry is the handle obtained from mmv_stats_registry. name and value
141 are the strings that will form the label.
142 type specifies the value type that can be: MMV_STRING_TYPE,
144 MMV_NUMBER_TYPE, MMV_BOOLEAN_TYPE, MMV_NULL_TYPE, MMV_ARRAY_TYPE and
145 MMV_MAP_TYPE.
146 At the moment there is a simple check of the correctness of the value.
148 After adding a label, it is called a function to verify if it is
149 correct.
150 Additionally, if optional is set, it is added the flag
152 PM_LABEL_OPTIONAL.
153 serial is the serial of the indom when adding an indom or instance
155 label. item is the metric identifier when adding a metric label.
156 Finally, when adding a registry label it is not necessary to give the
157 cluster id because it will be taken from the internal registry struct
158 already created.
159 mmv_stats_add_registry_label adds a PM_LABEL_CLUSTER.
161 mmv_stats_add_indom_label adds a PM_LABEL_INDOM.
163 mmv_stats_add_metric_label adds a PM_LABEL_ITEM.
165 mmv_stats_add_instance_label adds a PM_LABEL_INSTANCES.
167
169 When adding metrics, indoms, instances and labels, if correct returns
170 0
171 and if not it returns an errno code. The other functions return the
172 address
173 of the memory mapped region on success. On failure, NULL is returned
174 and
175 errno is set to a value suitable for decoding with strerror(3).
176
178 mmv_inc_value(3), mmv_lookup_value_desc(3), strerror(3) and mmv(5).
179Performance Co-Pilot MMV_STATS_REGISTRY(3)