Sketch out how metrics should be documented for each language SIG #1746
Comments
I would like seeing traces & metrics (and later logs and other potential signals) being combined in one "getting started", starting with traces for sure, but then going on with metrics is the natural flow and also shows that we think as them belonging together.
I think some of the SIGs are working on automatic things, so we can do it again like with traces: here is what you get automatically, here is what you can do manually, etc.
Some/Most languages have a http example already, so doing some calls per minute, average response time, error rate, etc is a good starting point.
if possible: same. |
|
(follow python example for each language: https://opentelemetry.io/docs/instrumentation/python/getting-started/) Getting startedwords Installationinstall everything you need / set up an environment for it if the language calls for it Create sample http serverNo instrumentation; just an http server that does a dice roll Add automatic instrumentation / Add instrumentation libraries(title differs depending on if language has autoinstrumentation) At a minimum, instruments the http call. Most likely to create a span since most libraries do that today. Run the instrumented appShow how to run, show sample output Add manual instrumentation to automatic instrumentationwords Add tracingShow how to create a span that connects with autoinstrumentation, run the app again, show example output Add metrics✨✨ HELP NEEDED! ✨✨ Show how to create a counter and up that counter on every request Send telemetry to an OpenTelemetry Collectorwords Configure and run a local collectorexample of configuring and running the collector such that it logs telemetry output Modify the command to export spans and metrics via OTLPshow how to export to the collector via otlp exporter Run the applicationsame as previous run, but this time shows collector output Next stepsPoint to autoinstrumentation/libraries article(s) and manual instrumentation article and exporters article |
|
(In existing manual instrumentation article) Manual instrumentationwords Tracing...all the tracing stuff that's mostly documented now Metricswords Initialization✨✨ HELP NEEDED! ✨✨ Show how to correctly initialize metrics for manual instrumentation. Some things to consider:
Example (likely not very good, but illustrative): from opentelemetry import metrics
# probably some code that sets up resources?
# something else?
meter = metrics.get_meter(__name__)Synchronous and asynchronous instruments✨✨ Help needed less, but still appreciated ✨✨ Explain synchronous and asynchronous instruments? Or should this just go into language-agnostic concept docs? work_counter = meter.create_counter(
"work.counter", unit="1", description="Counts the amount of work done"
)
work_counter.add(1)Using Counters✨✨ Help needed less, but still appreciated ✨✨ Briefly say what a counter is/link to a definition, show code sample on how to create and use Using Asynchronous Counters✨✨ Help needed less, but still appreciated ✨✨ Briefly say what an async counter is/link to a definition, show code sample on how to create and use Using Histograms✨✨ Help needed less, but still appreciated ✨✨ Briefly say what a histogram is/link to a definition, show code sample on how to create and use Using UpDownCounters✨✨ Help needed less, but still appreciated ✨✨ Briefly say what a UpDownCounters is/link to a definition, show code sample on how to create and use Using Asynchronous UpDownCounters✨✨ Help needed less, but still appreciated ✨✨ Briefly say what a async UpDownCounters is/link to a definition, show code sample on how to create and use Using Asynchronous Gauges✨✨ Help needed less, but still appreciated ✨✨ Briefly say what a async gauge is/link to a definition, show code sample on how to create and use Adding attributes to an instrument✨✨ Help needed less, but still appreciated ✨✨ Show example(s) of adding attributes to one or more of the above instruments, with a code sample Next stepsLink to exporters page |
|
ok... that's much more than metrics 😆 but I like it... can you put that maybe in 2 markdown files (maybe in archetypes or some "temp" place), so that commenting is a little bit easier? |
awesome! There's already a bunch of stuff for python on tracing, and a little bit on metrics. So, while you work on that, double check if the python tracing stuff is up-to-date & if things can be added and for the metrics extend it to whatever is missing. |
|
This one can get closed, as we have a format now (and several documented languages!) |
In the last maintainer's meeting, we discussed the looming lack-of-metrics problem. Several SIG maintainers said that they won't consider metrics as fully released until there's docs. Yay! But they'd like some help.
The ask was that we come up with the general framework by which they can contribute some code. For example:
If we can get this sketched out, then several SIG maintainers (Go, JS) offered to contribute some basic docs and code samples that demonstrate how to initialize and use metrics APIs correctly. I mentioned that I can usually run with things once I have the initialization code done right, since it's not too hard to use APIs in a sample app and produce copy-pasteable snippets from there.
We can then go to a language SIG with this and work with them to get metrics documented soon!
The text was updated successfully, but these errors were encountered: