[Python] Add documentation of auto-instrumenting Python services using the operator

[TylerHelmuth]

Adds a new section for Python automatic docs detailing how to use the OpenTelemetry operator to inject auto-instrumentation.

If we like this I can do something similar for the other languages the operator can inject.

[cartermp]

Round of copy-edits and some questions. Really happy to see this come together.

[svrnm]

thanks @TylerHelmuth

I am wondering if this should live below https://opentelemetry.io/docs/k8s-operator/ ? Where do you think people might expect it?

cc @pavolloffay

[pavolloffay]

I am wondering if this should live below https://opentelemetry.io/docs/k8s-operator/ ? Where do you think people might expect it?

I would prefer to keep it in the operator docs, but crosslink it from the python instrumentation docs.

[pavolloffay]

Good work,

as mentioned in another comment. A better place might be directly under operator docs.

We should also think how other operator auto-instrumentations will be documented and try to reuse common sections (collector deployment etc.)

[cartermp]

@pavolloffay Yes, agreed. I think we can iterate on this. We can extract various sections as subpages and share (e.g., collector stuff, some commentary) or break some of it up into separate articles (although only if it doesn't complicate the end-user experience).

@TylerHelmuth how would you like to proceed? We can take it in as-is and I can tweak from there, or we can try to make adjustments in this PR. I can PR against your branch if that works.

[chalin]

Hi all. If someone could run the markdown Prettifier over the new file before it is merged, that would be great! Otherwise it can be handled later (esp. since @cartermp is considering iterative improvements).

[TylerHelmuth]

I can update this PR on Tuesday to reorganize the content.

[cartermp]

Some copy-edits. Mainly reducing header sizes, since there's a top-level walkthrough but all the content is in subsections, so we can probably just move those subsections up one level.

[cartermp]

This sparks joy.

@pavolloffay and @open-telemetry/python-approvers can you take a look please?

[TylerHelmuth]

@pavolloffay @svrnm @cartermp @chalin

Moved content under k8s-operator and tried to keep the "walkthrough" feel of the doc. My thought was that the ins and outs of the different operator CRs and other configuration options is best handled in the operator's documentation and this section should be used as a "I want to auto-instrument a language, give me step by step instructions".

[svrnm]

just as a final remark: k8s idiots like me have no idea where and how to apply those annotations, I think I have googled that now a few times and still can not remember, so as a follow up to this it would be good to have an example for that as well.

[TylerHelmuth]

@svrnm each section of yaml is already ready to be copy and pasted into a terminal and use kubectl to apply the resource. Is there more you think we should add?

I purposefully added the ability to copy and paste the sections but didn't want to get into details about kubectl itself or the various methods of applying resource in k8s. My thinking was that if the reader feels comfortable using an operator (which I view as an advanced k8s technique), then they should already know how to apply resources using kubectl.

[svrnm]

@svrnm each section of yaml is already ready to be copy and pasted into a terminal and use kubectl to apply the resource. Is there more you think we should add?

I purposefully added the ability to copy and paste the sections but didn't want to get into details about kubectl itself or the various methods of applying resource in k8s. My thinking was that if the reader feels comfortable using an operator (which I view as an advanced k8s technique), then they should already know how to apply resources using kubectl.

I know plenty of people that use the operator without really knowing a lot of basics for k8s ;-) ... but I get your point. Giving one way of many and calling out that there are alternatives would be my preferred solution, but that's optional and from my point of view we should be good to get this into the docs?

@open-telemetry/operator-approvers any concerns?

[srikanthccv]

Thanks @TylerHelmuth

[cartermp]

@open-telemetry/operator-approvers -- any feedback? I'll merge within the week since it's been vetted by several folks at this point

[svrnm]

🎉