chore(span): make fields immutable after serialization

[mabdinur]

Description

Currently a span object object can be modified after the trace data has been encoded and sent to the agent.

This PR attempts to resolve this issue by introducing a _serialized Span property and @_is_serialized() annotation. Span._serialized is set to True after a span is encoded and sent to the TraceWriter.

ddtrace will log a warning if a Span is modified after serialization. It will not raise an exception. This is to maintain backwards compatibility and prevent ddtrace from crashing applications.

Risks

• Performance
• Generating noisy debug logs that are not actionable (ex: if spans are modified after Span.finish(...) in a ddtrace integration).
• Custom implementation of _ImmutableDict and _ImmutableList are incomplete/buggy/slow

Checklist

• PR author has checked that all the criteria below are met
• The PR description includes an overview of the change
• The PR description articulates the motivation for the change
• The change includes tests OR the PR description describes a testing strategy
• The PR description notes risks associated with the change, if any
• Newly-added code is easy to change
• The change follows the library release note guidelines
• The change includes or references documentation updates if necessary
• Backport labels are set (if applicable)

Reviewer Checklist

• Reviewer has checked that all the criteria below are met
• Title is accurate
• All changes are related to the pull request's stated goal
• Avoids breaking API changes
• Testing strategy adequately addresses listed risks
• Newly-added code is easy to change
• Release note makes sense to a user of the library
• If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment
• Backport labels are set in a manner that is consistent with the release branch maintenance policy

[github-actions]

CODEOWNERS have been resolved as:

ddtrace/_trace/processor/__init__.py                                    @DataDog/apm-sdk-api-python
ddtrace/_trace/span.py                                                  @DataDog/apm-sdk-api-python
ddtrace/_trace/types.py                                                 @DataDog/apm-sdk-api-python
tests/contrib/djangorestframework/test_appsec.py                        @DataDog/asm-python
tests/tracer/test_span.py                                               @DataDog/apm-sdk-api-python

[pr-commenter]

Benchmarks

Benchmark execution time: 2024-12-19 21:51:03

Comparing candidate commit 72629fc in PR branch munir/make-span-immutable-in-aggregator with baseline commit a4f0e38 in branch main.

Found 1 performance improvements and 10 performance regressions! Performance is the same for 367 metrics, 2 unstable metrics.

scenario:otelspan-add-metrics

• 🟥 execution_time [+106.678ms; +111.396ms] or [+33.478%; +34.958%]

scenario:otelspan-add-tags

• 🟥 execution_time [+66.174ms; +70.274ms] or [+22.590%; +23.990%]

scenario:otelspan-start

• 🟥 execution_time [+2.714ms; +3.465ms] or [+7.389%; +9.432%]

scenario:sethttpmeta-all-disabled

• 🟥 execution_time [+2.754µs; +2.866µs] or [+23.547%; +24.499%]

scenario:sethttpmeta-obfuscation-no-query

• 🟥 execution_time [+3.366µs; +3.998µs] or [+7.994%; +9.495%]

scenario:sethttpmeta-useragentvariant_exists_2

• 🟥 execution_time [+3.275µs; +3.600µs] or [+7.810%; +8.585%]

scenario:span-add-metrics

• 🟥 execution_time [+40.208ms; +41.838ms] or [+43.925%; +45.706%]
• 🟩 max_rss_usage [-6.593MB; -6.503MB] or [-16.294%; -16.072%]

scenario:span-add-tags

• 🟥 execution_time [+43.350ms; +45.008ms] or [+28.822%; +29.924%]

scenario:span-start

• 🟥 execution_time [+1.692ms; +1.923ms] or [+9.504%; +10.804%]

scenario:span-start-traceid128

• 🟥 execution_time [+1.787ms; +2.020ms] or [+9.818%; +11.099%]