1MMV_STATS_INIT(3) Library Functions Manual MMV_STATS_INIT(3)
2
6 mmv_stats_init, mmv_stats2_init - create and initialize Memory Mapped
7 Value file
8
10 #include <pcp/pmapi.h>
11 #include <pcp/mmv_stats.h>
12 void *mmv_stats_init(const char *name, int cluster,
14 mmv_stats_flags_t flags, const mmv_metric_t *stats, int nstats,
15 mmv_indom_t *indoms, int nindoms);
16 void *mmv_stats2_init(const char *name, int cluster,
17 mmv_stats_flags_t flags, const mmv_metric2_t *stats2,
18 int nstats2, mmv_indom2_t *indoms2, int nindoms2);
19 cc ... -lpcp_mmv -lpcp
21
23 Note: these functions are deprecated - see mmv_stats_registry(3).
24 mmv_stats_init creates and initializes the content of the MMV(5) file,
26 returning a handle that is used in subsequent MMV API calls.
27 mmv_stats2_init is equivalent to mmv_stats_init except that it provides
29 an option for longer metric and instance names.
30 mmv_stats_stop performs an orderly shutdown of the mapping handle re‐
32 turned by an earlier initialization call.
33 The file is created in the $PCP_TMP_DIR/mmv directory, name argument is
35 expected to be a basename of the file, not the full path. The metadata
36 content of the file does not change after the file has been created.
37 The old file is removed unconditionally unless there was an error.
39 cluster is the preferred MMV PMDA cluster ID to be used for the metrics
41 originating from this call to mmv_stats_init. The flags provide addi‐
42 tional control over the behaviour of the MMV PMDA - e.g. use of
43 MMV_FLAG_PROCESS will ensure values are only exported when the instru‐
44 mented application is running - this is verified on each request for
45 new values.
46 stats is the array of mmv_metric_t elements of length nstats. Each ele‐
48 ment of the array describes one PCP metric.
49 typedef struct {
51 char name[MMV_NAMEMAX]; /* Name of the metric */
52 __uint32_t item; /* Item component of PMID */
53 mmv_metric_type_t type; /* Type of the metric */
54 mmv_metric_sem_t semantics; /* Semantics of the metric */
55 pmUnits dimension; /* Dimensions (TIME,SPACE,etc) */
56 __uint32_t indom; /* Instance domain identifier */
57 char *shorttext; /* Optional, one-line help */
58 char *helptext; /* Optional, full help text */
59 } mmv_metric_t;
60 stats2 is the array of mmv_metric2_t elements of length nstats2. Each
62 element of the array describes one PCP metric, the only difference to
63 stats is the lifting of the restriction on name length (previously
64 MMV_NAMEMAX, which is 64 bytes).
65 typedef struct {
67 char *name; /* Name of the metric */
68 __uint32_t item; /* Item component of PMID */
69 mmv_metric_type_t type; /* Type of the metric */
70 mmv_metric_sem_t semantics; /* Semantics of the metric */
71 pmUnits dimension; /* Dimensions (TIME,SPACE,etc) */
72 __uint32_t indom; /* Instance domain identifier */
73 char *shorttext; /* Optional, one-line help */
74 char *helptext; /* Optional, full help text */
75 } mmv_metric2_t;
76 If indom is not zero and not PM_INDOM_NULL, then the metric has multi‐
78 ple values and there must be a corresponding indom entry in the indom
79 list (uniquely identified by serial number).
80 The stats and stats2 arrays cannot contain any elements which have no
82 name - this is considered an error and no metrics will be exported in
83 this case.
84 indoms is the array of mmv_indom_t elements of length nindoms. Each el‐
86 ement of the array describes one PCP instance domain.
87 typedef struct {
89 __int32_t internal;
90 char external[MMV_NAMEMAX];
91 } mmv_instances_t;
92 typedef struct {
94 __uint32_t serial; /* Unique serial number */
95 __uint32_t count; /* Number of instances */
96 mmv_instances_t *instances; /* Internal/external IDs */
97 char *shorttext; /* Short help text */
98 char *helptext; /* Long help text */
99 } mmv_indom_t;
100 indoms2 is the array of mmv_indom2_t elements of length nindoms2. Each
102 element of the array describes one PCP instance domain, and the only
103 difference to indoms is the lifting of the restriction on external in‐
104 stance name lengths (previously MMV_NAMEMAX, which is 64 bytes).
105 typedef struct {
107 __int32_t internal;
108 char *external;
109 } mmv_instances2_t;
110 typedef struct {
112 __uint32_t serial; /* Unique serial number */
113 __uint32_t count; /* Number of instances */
114 mmv_instances2_t *instances; /* Internal/external IDs */
115 char *shorttext; /* Short help text */
116 char *helptext; /* Long help text */
117 } mmv_indom2_t;
118
120 These functions return the address of the memory mapped region on suc‐
121 cess. On failure, NULL is returned and errno is set to a value suit‐
122 able for decoding with strerror(3).
123
125 mmv_stats_registry(3), mmv_lookup_value_desc(3), mmv_inc_value(3), str‐
126 error(3) and mmv(5).
127Performance Co-Pilot MMV_STATS_INIT(3)