MPT-20733 add trace span decorator

[svazquezco]

🤖 AI-generated PR — Please review carefully.

Summary

• Add the public trace_span observability decorator for extension-defined business operations.
• Re-export trace_span from mpt_extension_sdk.observability so extensions can import it directly.
• Support synchronous and asynchronous decorated functions.
• Support span attributes defined as static values or callables evaluated from decorated function arguments.
• Filter unsupported or None attribute values before setting OpenTelemetry span attributes.
• Add tests covering async span creation, sync span creation, callable attribute resolution, and attribute filtering.

Testing

• make check
• make test

Closes MPT-20733

• Add public trace_span observability decorator (mpt_extension_sdk.observability.decorators.trace_span) and re-export it from mpt_extension_sdk.observability; restrict module exports via all = ["trace_span"]
• Support decorating both synchronous and asynchronous callables
• Allow span attributes to be static values or callables evaluated against the decorated function's args/kwargs
• Resolve and filter attributes via helper _resolve_span_attributes; omit None and unsupported types before setting OpenTelemetry span attributes
• Add span-related type aliases: SpanAttributeValue, SpanAttributes, SpanArgs, SpanKwargs
• Add tests covering async span creation, sync span creation, callable attribute resolution, and attribute filtering
• Run tests with: make check, make test

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 4ad91d79-9a37-45cc-b5c7-cf839d5f9be6

📥 Commits

Reviewing files that changed from the base of the PR and between 826625c and cde67a9.

📒 Files selected for processing (3)

• mpt_extension_sdk/observability/__init__.py
• mpt_extension_sdk/observability/decorators.py
• tests/observability/test_tracing.py

---

📝 Walkthrough

Walkthrough

Adds a new trace_span decorator (sync/async) with attribute resolution helper, exposes it from mpt_extension_sdk.observability, and adds tests validating span creation and attribute population/omission.

Changes

Span decorator feature

Layer / File(s)	Summary
Type definitions and imports for span decorator mpt_extension_sdk/observability/decorators.py	Imports updated to include iscoroutinefunction and expanded typing support for span attribute specifications and argument passing.
Span decorator implementation mpt_extension_sdk/observability/decorators.py	trace_span decorator wraps sync and async functions with TRACER-managed child spans and applies resolved attributes before calling the wrapped function.
Attribute resolution helper mpt_extension_sdk/observability/decorators.py	_resolve_span_attributes evaluates static values or callables (with args/kwargs), swallows resolution exceptions, and filters results to bool/str/int/float for span attributes.
Module public API export mpt_extension_sdk/observability/__init__.py	Module exports trace_span via __all__ to provide direct import from mpt_extension_sdk.observability.
Decorator tests and samples tests/observability/test_tracing.py	Adds async and sync sample functions decorated with @trace_span and tests that patch decorators.TRACER to assert span names and expected attribute presence/absence.

---

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Jira Issue Key In Title	✅ Passed	✅ Found Jira issue key in the title: MPT-20733
Test Coverage Required	✅ Passed	PR includes test file changes: tests/observability/test_tracing.py contains 3 new test functions covering the trace_span decorator alongside 2 code files modified in mpt_extension_sdk/observability/.
Single Commit Required	✅ Passed	PR contains exactly 1 commit (cde67a9 'feat: add trace span decorator'), verified via git log and git rev-list command.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/observability/test_tracing.py (1)

98-129: ⚡ Quick win

Add a regression case for failing attribute callables.

Please add one test where an attribute callable raises (for example, itemgetter("missing")) and assert the wrapped function still succeeds while that attribute is omitted.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/observability/test_tracing.py` around lines 98 - 129, Add a new test
(e.g., test_trace_omits_failing_callable_attr) that patches decorators.TRACER
using span_exporter like the other tests, then invokes the traced function (use
trace_sample_async via asyncio.run or trace_sample_sync as appropriate) while
supplying/arranging for one traced attribute to be a callable that will raise
when invoked (example: operator.itemgetter("missing")). Assert the traced
function still returns/succeeds, then locate the finished span by name (same
approach as
test_trace_span_wraps_async_attrs/test_trace_span_wraps_sync_function) and
assert the failing attribute key is not present in span.attributes while other
expected attributes remain. Ensure the test imports/uses itemgetter (or
equivalent) and follows the pattern of inspecting exporter.get_finished_spans()
for the span.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mpt_extension_sdk/observability/decorators.py`:
- Around line 123-126: The loop in decorators.py currently calls
attribute_source(*args, **kwargs) directly when attribute_source is callable
(the attributes dict loop that assigns resolved_value), which can raise and
prevent the decorated function from running; update the loop to wrap each
callable invocation of attribute_source in a try/except that catches broad
exceptions (e.g., Exception), logs or records the error if needed, and continues
without adding that attribute (i.e., skip the failing key) so only the failing
attribute is dropped and tracing never blocks business execution; ensure you
reference the same attributes, attribute_source, and resolved_value symbols when
making the change.

---

Nitpick comments:
In `@tests/observability/test_tracing.py`:
- Around line 98-129: Add a new test (e.g.,
test_trace_omits_failing_callable_attr) that patches decorators.TRACER using
span_exporter like the other tests, then invokes the traced function (use
trace_sample_async via asyncio.run or trace_sample_sync as appropriate) while
supplying/arranging for one traced attribute to be a callable that will raise
when invoked (example: operator.itemgetter("missing")). Assert the traced
function still returns/succeeds, then locate the finished span by name (same
approach as
test_trace_span_wraps_async_attrs/test_trace_span_wraps_sync_function) and
assert the failing attribute key is not present in span.attributes while other
expected attributes remain. Ensure the test imports/uses itemgetter (or
equivalent) and follows the pattern of inspecting exporter.get_finished_spans()
for the span.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 89e56cc4-e84d-4198-b135-317acd7d9509

📥 Commits

Reviewing files that changed from the base of the PR and between c80cf7f and dbb2ab8.

📒 Files selected for processing (3)

• mpt_extension_sdk/observability/__init__.py
• mpt_extension_sdk/observability/decorators.py
• tests/observability/test_tracing.py

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud