Some notes from the PG draft:
- page ix, "Reader Comments", should include the email address
- page 1, "several ways to extend PCP", the MMV stuff should also
end up being documented in as much detail as the trace stuff
- page 6, "warning" how about a "note" or suggestion instead?
- page 6, "calls to exit(1) ... have grave implications" is too
vague. Instead, mention that the pmcd process would exit.
(It's elaborated well on page 12, maybe xref?)
- page 9, step 5, add "assign unique domain numbers, xref section
2.3.2 (page 14).
- page 10, step 11, pmgadgets doesn't exist in OSS pcp yet
- page 16, metrictab[] trivial PMDA, the PMID sentence (cluster 0 item 1)
should spell out that this is not a complete PMID, in that the pmda's
own number will be inserted at some point. (This bit me once or twice
earlier.)
- page 17, the example 2.6 counter/instantaneous rows suggests
rate-conversion is being done (at the pmda end) for the "counter"
value. Is this conversion to be done per-client-context, so that
the rate is well-defined ("average rate since the last time this
same client asked") as opposed to "average rate since ... when?".
In the former case, each client can accumulate the instantaneous
values from the rate deltas. In the latter, then it seems like many
rate-"counter" metrics should also be exported as instantaneous
values.
- page 19, pmda instances, need names be unique, or only numbers?
- page 20, "dp->version.two ..." that .two. bit should be introduced,
and choice of .two. vs. others be outlined.
- page 21, the caveat under the warning relates to the page 17 issue
above, maybe xref?
- page 25, was expecting something about the version.* bits early on
here; why use pmdaSet*CallBack here instead of changing the
->version.*.* variables?
- page 26, for the cluster/item conditions, might want to note that
we're not also checking the idp->domain number, because it's not
necessary; or perhaps add an assertion instead of a wordy
explanation
- page 26, should expand on the choice of "appropriate field in
the pmAtomValue", ie., tabulate the fields as a function of the TYPE
- page 28, store, should note implications of security, reliable-logging,
credentials
- page 28, simple.color store example; should explain the meaning of the
loop over j (vsp->numval) at the for loop as a teaser for the info
on page 29, like for (j=...) /* loop over instances */
- page 30, PMDA_INTERFACE_* are mentioned here for the first time;
earlier & more details please; but maybe we don't need to
document older interfaces at all
- page 30 PMDA structures, aha, here is where the .one/.two,
PMDA_INTERFACE_* bits are described. Perhaps move this section way
ahead, ahead of 2.4 perhaps
- page 32 ... maybe move the whole PMDA setup section up ahead too; it
just makes a little more sense to me to cover the PMDA operation
from initialization onward (in a temporal sequence)
- page 34, mind a small elaboration about why the pmda might want to
handle both simple_fetch and simple_fetchCallBack?
- page 35, should mention when pmdaMain might return -> exit
- page 36, pmstore pmcd.control.debug, is that credential-controlled?
- page 37, looking forward to scox's sys/sdt.h macros being mentioned
before too long, as an additional pmda debugging technique, with
some systemtap samples; maybe in general, stub placeholders for
sections we know are needed/coming (like the python/etc. bindings,
pmwebapi, etc.) would be helpful
- page 39, .pmchart files; I didn't realize we did that. Is there
analogous handling for pmieconf / pmlogconf fragments?
- page 45, Current PMAPI Context, should mention pmUseContext to switch
(and maybe pmReconnectContext, since we haven't automated that yet)
- page 46, typo "unpackaing"
- page 50, programming style topics should include memory management,
specifically the styles of handing over ownership of this or that
snippet of data structure to libpcp vs. the app; this is particularly
tricky for those AGGREGATE / EVENT / _STATIC values; the error handling
section should mention general policies involving partial failures
(like pmLookupNames that partly fail, partly succeed; or other cases)
- page 51.., general re. section 3.8, dunno how much value a direct
man-page-extract type reference dump for all these functions has;
for a tutorial, one might want to see these functions being used,
(like the pmda/simple examples were) rather than simply enumerated
- page 54, if the PMNS operations are rarely required in modern PCP
code, consider dropping their details from these docs; maybe just
mention and refer to the man pages
- page 56, PMAPI context services, now we're talking ... this kind of
tabular overview is totally apropos for the manual
- page 57, 3.8.1 ... back to man-page-extracts, hmm.
- page 60, sample code, yummy
- page 61, pmGetContextHostName ... I guess thread-unsafe?
- page 65, record-mode is newly introduced here; maybe elaborate before
(or instead of) lunging into the API
- page 69, the ...InDomArchive functions, it'd be good to get a motivation
for using these functions
- page 70, "pmview" mystery superhero
- page 76..77, some sample code, yummy
- page 78, programming issues & examples, now we're talking!
- page 83, it'd be good to get a sense as to why the trace library is
considered heavyweight, some relative-to-printf costs or something?
can't some of our own code use them?
|