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