[Developer Guide Audit] Instrumentation

[mrbobbytables]

Documentation is the go-to reference for contributors. Parts of the developer guide have been cited as vastly out of date (e.g. referencing VERY outdated versions of docker). We are asking each SIG that owns a portion of the developer guide to audit their devel guide documentation.

This does not have to include updating it.
(although if you want to, please go ahead 😄 )

If you could, update this issue with items that are out of date or you think should be added to the Instrumentation portion of the devel guide.

Assigning to leads, but please feel free to re-assign and delegate.
/assign @ehashman @logicalhan @brancz @dashpole

---

Parent Tracking Issue: #5229
/sig instrumentation
/sig contributor-experience
/area developer-guide
/milestone v1.20

[mrbobbytables]

Additional Related Item (just stumbled across it):

• Instrumentation quickstart should use or mention wrappers for prometheus

[ehashman]

Overhauling the instrumentation docs is not a trivial thing and I suspect we're unlikely to get this done before doc freeze. I'll add this to our next SIG meeting agenda.

[mrbobbytables]

@ehashman No worries, this is out of band for user facing docs :) This is our devel docs only.

[ehashman]

Ah okay! Still, will take time, energy, and careful effort :)

[ehashman]

@logicalhan will take the lead on the doc review, and we've also identified some other areas for improvement/development in the dev docs.

[sftim]

Very much relevant to kubernetes/contributor-site#204

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle rotten

[dashpole]

/remove-lifecycle rotten

[dashpole]

cc @CatherineF-dev

[dashpole]

@CatherineF-dev can you read through the existing documentation, and document what you find confusing, or questions you have about how to contribute? Thanks!

[ehashman]

also cc @husky-parul who is interested in working on this

[CatherineF-dev]

• I have read markdown files under https://github.com/kubernetes/community/tree/master/contributors/devel/sig-instrumentation. These docs are well-written! They include the most important parts in a short page and give related context in the links. In addition, code examples in the docs are helpful.

• There are two kinds of suggestions I added:

1. Optional
   They are a little important, which need reviewed first.
2. Non-optional
   They are related to formatting/consistency/non-important issues, which could be ignored if it doesn't matter. I marked (Optional) in the title.

If there are other docs need review, please let me know.

[CatherineF-dev]

instrumentation.md

1. need descriptions for kind in kube_<kind>_<metric> (Optional)

Suggestion: add kind in the description. produced by different controllers -> produced by different kinds of controllers

instrumentation.md#exception-for-object-state-metric

... even when they are produced by different controllers. Metrics describing the state of a built-in Kubernetes object take the form:
kube_<kind>_<metric> <-------------------- here

2. miss metrics value 1

Suggestion: append 1.
Replace kube_pod_info{pod=...,namespace=...,pod_ip=...,host_ip=..,node=..., ...}
with kube_pod_info{pod=...,namespace=...,pod_ip=...,host_ip=..,node=..., ...} 1.
instrumentation.md#normalization

kube_pod_info{pod=...,namespace=...,pod_ip=...,host_ip=..,node=..., ...} <-------------------- here

3. unfinished sentence

I failed to figure out the meaning of This leads to....

instrumentation.md#normalization
The metric system can later denormalize those along the identifying labels “pod” and “namespace” labels. This leads to...

migration-to-structured-logging.md

1. titles are not same (Optional)

Use klog.KObj and klog.KRef for Kubernetes object references V.S. Use klog.KObj and klog.KRef for Kubernetes objects

migration-to-structured-logging.md#migration

1. Change log functions to structured equivalent
2. Remove string formatting from log message
3. Name arguments
4. Use `klog.KObj` and `klog.KRef` for Kubernetes object references <-------------------- here
5. Verify log output

And here migration-to-structured-logging.md#use-klogkobj-and-klogkref-for-kubernetes-objects

event-style-guide.md

1. code examples (Optional)

instrumentation.md and migration-to-structured-logging.md provides code examples. It will be great if event-style-guide.md has code examples also.
event-style-guide.md#how-to-structure-an-event

[ehashman]

Closed by #5915.

/close

[k8s-ci-robot]

@ehashman: Closing this issue.

In response to this:

Closed by #5915.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.