Document how to create new subsegments inside a ThreadPoolExecutor thread

Inizia dalla documentazione sul threading collegata nell’issue e rivedi i punti di ingresso capture e in_segment dopo set_trace_entity. Chiarisci il pattern supportato per creare sottosegmenti nei thread di lavoro, inclusa la pulizia, e aggiorna l’esempio in modo che il lettore possa distinguere gli approcci validi.

The current documentation shows how to set the parent thread's X-ray entity in the worker thread:

def load_url(url, trace_entity):
    # Set the parent X-Ray entity for the worker thread.
    xray_recorder.set_trace_entity(trace_entity)
    # Subsegment captured from the following HTTP GET will be
    # a child of parent entity passed from the main thread.
    resp = requests.get(url)
    # prevent thread pollution
    xray_recorder.clear_trace_entities()
    return resp

However it's not clear how this interacts with capture/in_segment. For example, I assume this isn't correct, as the capture starts before we call set_trace_entity:

@xray_recorder.capture('subsegment_name')
def load_url(url, trace_entity):
    # Set the parent X-Ray entity for the worker thread.
    xray_recorder.set_trace_entity(trace_entity)
    # Subsegment captured from the following HTTP GET will be
    # a child of parent entity passed from the main thread.
    resp = requests.get(url)
    # prevent thread pollution
    xray_recorder.clear_trace_entities()
    return resp

However, are these two OK?

def load_url(url, trace_entity):
    # Set the parent X-Ray entity for the worker thread.
    xray_recorder.set_trace_entity(trace_entity)
    with xray_recorder.capture('subsegment_name'):
        # Subsegment captured from the following HTTP GET will be
        # a child of parent entity passed from the main thread.
        resp = requests.get(url)
    # prevent thread pollution
    xray_recorder.clear_trace_entities()
    return resp

def load_url(url, trace_entity):
    # Set the parent X-Ray entity for the worker thread.
    xray_recorder.set_trace_entity(trace_entity)
    with xray_recorder.in_segment('segment_name') as segment:
        segment.put_metadata('key', dict, 'namespace')
        # Subsegment captured from the following HTTP GET will be
        # a child of parent entity passed from the main thread.
        resp = requests.get(url)
    # prevent thread pollution
    xray_recorder.clear_trace_entities()
    return resp

It would be great if the docs on threading had a more complete example.