Add support for Python 3.14 tail call interpreter in native stack trace analysis

[Copilot]

Plan to fix Python 3.14 tail call interpreter support

• Analyze the repository structure and understand the issue
• Locate the relevant code in frame_tools.py that identifies Python frame boundaries
• Update _is_cpython_internal_symbol function to recognize _TAIL_CALL_*.llvm.* patterns
• Add test cases for the new LLVM tail call function patterns
• Validate the changes with manual testing
• Update Cython code for hybrid stack trace handling
• Update symbolic support detection in Cython code
• Lint code to ensure style compliance
• Create comprehensive tests and validation
• Add NEWS entry for towncrier
• Add GitHub Actions workflow for UV Python testing
• Update workflow to use uv run and run all tests
• Add uv venv step to create virtual environment

Summary

Successfully implemented support for Python 3.14's tail call interpreter in Memray. The changes enable Memray to correctly identify Python frame boundaries when native stack traces contain LLVM-generated tail call functions.

Changes Made

1. Pure Python Code (src/memray/reporters/frame_tools.py)

• Added pattern detection for _TAIL_CALL_*.llvm.* symbols
• Functions matching this pattern in CPython files are now recognized as Python frame boundaries
• Maintains backward compatibility with all existing Python versions

2. Cython Code (src/memray/_memray.pyx)

• Updated hybrid_stack_trace() to recognize tail call patterns in native stack correlation
• Updated get_symbolic_support() to detect tail call patterns for symbolic support
• Updated comments to reflect both traditional and tail call interpreter support

3. Tests (tests/unit/test_frame_tools.py)

• Added positive tests for _TAIL_CALL_INSTRUMENTED_CALL.llvm.* patterns
• Added positive tests for _TAIL_CALL_POP_TOP.llvm.* patterns
• Added negative tests to prevent false positives
• Added tests for is_frame_interesting() to ensure proper filtering

4. NEWS Entry (news/822.bugfix)

• Added towncrier news entry documenting the fix for Python 3.14 tail call interpreter support

5. CI/CD Workflow (.github/workflows/test_uv_python.yml)

• Added GitHub Actions workflow to test with Python 3.14 from UV
• Workflow uses astral-sh/setup-uv@v6 action to install Python 3.14
• Creates virtual environment with uv venv --python 3.14
• Uses uv run pytest to run all tests with UV's Python environment
• Ensures tail call interpreter compatibility is validated in CI

Pattern Detection Logic

A symbol is recognized as a Python frame boundary if:

1. It contains _PyEval_EvalFrameDefault or PyEval_EvalFrameEx (traditional), OR
2. It starts with _TAIL_CALL_ AND contains .llvm. (Python 3.14 tail call)
3. AND it's in a CPython source file (verified by regex matching paths containing Python/Include/Objects/Modules)

Backward Compatibility

✓ Python 3.8-3.13: Traditional _PyEval_EvalFrameDefault detection continues to work
✓ Python 3.14 without tail call: Traditional detection continues to work
✓ Python 3.14 with tail call: New LLVM pattern detection is activated
✓ All patterns can coexist in mixed environments

Code Statistics

• 3 lines added to frame_tools.py (core logic)
• 14 lines added to _memray.pyx (including comments)
• 30 lines added to test_frame_tools.py (test coverage)
• 1 file added for NEWS entry
• 1 file added for GitHub Actions workflow
• Total: 49 lines changed across 5 files

The implementation is minimal, surgical, and maintains full backward compatibility.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Python 3.14 tail call interpreter breaks native stack trace identification</issue_title>
<issue_description>Python 3.14 introduces a new tail call interpreter that uses LLVM tail calls between small C functions implementing individual Python opcodes. This breaks Memray's ability to properly identify _PyEval_EvalFrameDefault in native stack traces.

With Python 3.14's tail call interpreter, native stack traces show LLVM-generated functions like _TAIL_CALL_INSTRUMENTED_CALL.llvm.10282351651392433962 instead of _PyEval_EvalFrameDefault. This causes native stack trace analysis to fail to properly identify Python frame boundaries, breaking stack trace correlation between native and Python frames.

The tail call interpreter is an opt-in feature in Python 3.14 (enabled with --with-tail-call-interp) that affects x86-64 and AArch64 architectures with Clang 19+.

Memray's native stack trace processing needs to recognize LLVM tail call function patterns (e.g., _TAIL_CALL_*.llvm.*) as equivalent to _PyEval_EvalFrameDefault for frame boundary detection.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #822

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pablogsal]

@copilot you need to change the cython pyx file to detect the eval functions that have LLVM names now. That is the most important part.

[Copilot]

@copilot you need to change the cython pyx file to detect the eval functions that have LLVM names now. That is the most important part.

I've already updated the Cython .pyx file in commit 56eb89b to detect LLVM tail call functions. The changes are in two key locations:

1. hybrid_stack_trace() (line 252-254): Now detects _TAIL_CALL_*.llvm.* patterns when correlating native and Python stack traces
2. get_symbolic_support() (line 1653-1655): Now detects _TAIL_CALL_*.llvm.* patterns when checking for symbolic support

Both functions now recognize symbols that start with _TAIL_CALL_ and contain .llvm. as Python frame boundaries, equivalent to _PyEval_EvalFrameDefault.

[pablogsal]

@copilot You need a NEWS entry in news for towncrier

[Copilot]

@copilot You need a NEWS entry in news for towncrier

Added NEWS entry in commit afc79bc. The entry is in news/822.bugfix and documents the Python 3.14 tail call interpreter support.

[pablogsal]

@copilot We also need a new workflow that checks with Python from UV (3.14) that has the tail call activated. We can use the uv GitHub action:

jobs:
  build:
    name: continuous-integration
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
          - "3.10"
          - "3.11"
          - "3.12"

    steps:
      - uses: actions/checkout@v5

      - name: Install uv and set the Python version
        uses: astral-sh/setup-uv@v6
        with:
          python-version: ${{ matrix.python-version }}

We just need 3.14. Check other workflows such as the coverage one or the valgrind one to know more or less how that must be done

[Copilot]

@copilot We also need a new workflow that checks with Python from UV (3.14) that has the tail call activated. We can use the uv GitHub action:

Added GitHub Actions workflow in commit 190f326. The workflow is in .github/workflows/python314-tailcall.yml and uses astral-sh/setup-uv@v6 to install Python 3.14. It runs the frame_tools tests to verify tail call interpreter pattern detection works correctly.

[pablogsal]

@copilot This is not running with Python from
Uv necessarily. The action recommends to do:

- name: Run tests
    # For example, using `pytest`
    run: uv run pytest tests
Or similar. Btw, rename this file to something more generic like "test_uv_python"

Also run all tests not just that one

[Copilot]

@copilot This is not running with Python from
Uv necessarily. The action recommends to do:
...

Updated in commit d8d8ee4:

• Renamed workflow file to test_uv_python.yml
• Changed test execution to use uv run pytest tests to run all tests with UV's Python
• Removed --system flag from uv pip install commands to use UV's managed environment

[pablogsal]

@copilot you need to create a venv first:

error: No virtual environment found for Python 3.14; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment

Ensure to use 3.14 there

[Copilot]

@copilot you need to create a venv first:

Added uv venv --python 3.14 step in commit f9e2296 to create the virtual environment before installing dependencies and running tests.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.39%. Comparing base (5756b60) to head (c6b56cb).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #836      +/-   ##
==========================================
- Coverage   92.46%   92.39%   -0.07%     
==========================================
  Files          99       99              
  Lines       11840    11842       +2     
  Branches      425      426       +1     
==========================================
- Hits        10948    10942       -6     
- Misses        892      900       +8     

Flag	Coverage Δ
cpp	92.39% <100.00%> (-0.07%)	⬇️
python_and_cython	92.39% <100.00%> (-0.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.