Metrics SDK specification: what should this document contain?

[jmacd]

This draft PR #347 is six months old and quite out of date. I am committed to revising this document and finishing it, but I am concerned that I--standing near the center of this project for so long--will either write about things that are not important or fail to write about things that are important.

This issue is meant to collect requirements for the final SDK specification document. What MUST it contain? These are the topics I am aware of:

Architectural diagram: Accumulator, Integrator, Export path
Aggregators: Which SHOULD and which MUST be included. Define their semantics.
Resources: ??
Configuration: ??

@jkwatson

[jkwatson]

Glossary, for sure (if that's not already somewhere).
How to configure Resources seems like a big one that's currently absent.
What is configurable at runtime seems like an important item, as well.

One question I have: how prescriptive is the accumulator/integrator/etc naming? I ask because the Java SDK doesn't have things named that at this point, and different languages might want different structures for performance reasons. Can those things be conceptual, rather than prescriptive, I wonder?

[cijothomas]

I'd love to see customization points in the SDK spec. For example, Tracing Spec has well defined SpanProcessor, SpanExporter and user can write their own ones looking at the spec, and plug it into TracerProviders.

Would love to have metrics SDK specify - what are the things which one can customize, and how. eg: can I change Aggregator to a custom defined one? If yes, how to write one (which interface to implement), and how to plug it in.

I assume Views are going to be covered in SDK spec as well.

[jmacd]

@cijothomas Yes, a lot of the document will go toward extension points. Those points are named Integrator, Exporter, and Aggregator. Thanks.

[andrewhsu]

discussed this at the spec sig mtg today, and looks like @jmacd is working on this with #347 so initially assigning to him