open-telemetry / open-telemetry/opentelemetry-python-contrib
Monkey patching vs upstream in-library instrumentation?
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 1.1k
- Avg merge
- 4d 15h
- Merged PRs (30d)
- 16
Description
I got curious about the recommended way to add instrumentation to a new third party library.
Looking at many of the instrumentors here, they are based on monkey patching, which is generally frowned upon, for many good reasons.
Is this the recommended approach? Or is it purely by necessity? - For example upstream library do not want to accept adding more dependencies? (With log4j in recent memory this could be understandable)
Maybe there are more reasons behind that I'm not aware of.
Personally i would think that keeping the instrumentation in the library main repository would ease maintenance and avoid incompatibilities arising from changes in the instrumented library. For basic decorators of public apis it's maybe not such a big risk, but ideally in-tree code will always be easier and safer to maintain than external patches. See https://github.com/open-telemetry/opentelemetry-python/discussions/1729 for an example of version conflict that could be avoided by keeping instrumentation in tree.
If OpenTelemetry is aiming to be universal, it should be an easy choice for a library to say that yes we want to support this. Compare it to logging, it is usually universal and kept in the main library together with the main source code, nobody does monkey-patching to add logging :)
So rather than maintaining patches for all the libraries in the world here, should the first step be an attempt to upstream telemetry into the library? Taking this even further, linking to a rejected upstream attempt could even be a prerequisite before one is allowed to add a monkeypatch here?
I'm very happy to see so many popular libraries having instrumentation available via this repository, and guess it would not have been possible in such short time frame without patching, especially during the early stages of establishing reputation. My main question is more about the guidelines and best-practices one should follow when adding new instrumentation in future. Both when writing own libraries and when communicating with third party library maintainers.
- Should the guideline provide directions on preferred approach to upstreaming in-library instrumentation vs monkey patching? (Together with guideline-for-instrumentations )
- Should opentelemetry provide a standard template with justification for library authors to integrate telemetry? Of course it will always be the library who in the end decides and there shouldn't be bullying into accepting, but a friendly knowledge sharing and motivation could be good. otel-mission-vision-and-values does a quite good job at this already.
- Should instrumentors in this project require some more strict acceptance criteria on the maintenance plan and alternative approaches already tried, preferably with some voice from the upstream library maintainers?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the guideline-for-instrumentations section in CONTRIBUTING.md, then review the linked OpenTelemetry discussion and mission, vision, and values document. Done would require a maintainer decision on upstreaming guidance, acceptance criteria, and whether supporting documentation or templates should be added.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, observability
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100