Improve documentation for Python

[kamzil]

trafficstars

Hi, I spent a day hitting my head against the wall as I couldn't get annotations working for our FastAPI app that uses ADOT to push traces to X-Ray via otel-collector. There's very little info in the main docs about anything than just using the default auto-instrumentation, and the docs about annotations just say that hey you can add this attribute to the span and it should work.

In reality, there are several hoops to jump through to get annotations to X-Ray. I finally found a doc that describes this in enough detail (https://docs.aws.amazon.com/xray/latest/devguide/migrate-xray-to-opentelemetry-python.html), but only after I had already almost managed to brute-force my way through by reading source code of different instrumentation providers and other sources around the internet.

Could you please update your main documentation for how to properly use OpenTelemetry with Python for X-Ray, instead of hiding all the useful info within deeply nested and hard to find migration subguides?

In case anyone else is struggling to get custom annotations working, here's an example working snippet borrowed from the migration guide:

with tracer.start_as_current_span("parent", kind=SpanKind.SERVER) as parent_span:
    parent_span.set_attribute("TransactionId", "qwerty12345")
    parent_span.set_attribute("AccountId", "1234567890")

    # This will convert the TransactionId and AccountId to be searchable X-Ray annotations
    parent_span.set_attribute("aws.xray.annotations", ["TransactionId", "AccountId"])

    with tracer.start_as_current_span("child", kind=SpanKind.CLIENT) as child_span:

        # The MicroTransactionId will be converted to X-Ray metadata for the child subsegment
        child_span.set_attribute("MicroTransactionId", "micro12345")   

Note the mandatory aws.xray.annotations step, and also starting a new SERVER span (without it, you'll be inside a NonRecordingSpan, and you can't add attributes to it)