---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://perforator.tech/docs/en/reference/language-support/python/stack-unwinding.md
---
> **Documentation Index:** Fetch the complete configuration index at https://perforator.tech/docs/en/llms.txt

# Python Stack Unwinding

Having a current `*PyThreadState` pointer a top executing frame is retrieved using the `current_frame` field and the frame chain is traversed using the `previous` field.

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 524.941301882267 318.87890625" width="1049.882603764534" height="637.7578125"><!--svg-source:excalidraw--><metadata/><defs></defs><rect x="0" y="0" width="524.941301882267" height="318.87890625" fill="#ffffff"/><g stroke-linecap="round" transform="translate(43.44140625 57.7265625) rotate(0 122.1171875 31.701171875)"><path d="M15.85 0 C63.19 0, 110.53 0, 228.38 0 M15.85 0 C89.31 0, 162.77 0, 228.38 0 M228.38 0 C238.95 0, 244.23 5.28, 244.23 15.85 M228.38 0 C238.95 0, 244.23 5.28, 244.23 15.85 M244.23 15.85 C244.23 28.53, 244.23 41.21, 244.23 47.55 M244.23 15.85 C244.23 23.38, 244.23 30.91, 244.23 47.55 M244.23 47.55 C244.23 58.12, 238.95 63.4, 228.38 63.4 M244.23 47.55 C244.23 58.12, 238.95 63.4, 228.38 63.4 M228.38 63.4 C173.75 63.4, 119.12 63.4, 15.85 63.4 M228.38 63.4 C153.33 63.4, 78.28 63.4, 15.85 63.4 M15.85 63.4 C5.28 63.4, 0 58.12, 0 47.55 M15.85 63.4 C5.28 63.4, 0 58.12, 0 47.55 M0 47.55 C0 38.47, 0 29.38, 0 15.85 M0 47.55 C0 38.52, 0 29.48, 0 15.85 M0 15.85 C0 5.28, 5.28 0, 15.85 0 M0 15.85 C0 5.28, 5.28 0, 15.85 0" stroke="#1e1e1e" stroke-width="2" fill="none"/></g><g transform="translate(92.78515625 18.35546875) rotate(0 76.41993835568428 12.5)"><text x="0" y="17.619999999999997" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">PyThreadState</text></g><g stroke-linecap="round" transform="translate(84.60546875 61.7890625) rotate(0 66.21875 27.58203125)"><path d="M13.79 0 C50.04 0, 86.29 0, 118.65 0 M118.65 0 C127.84 0, 132.44 4.6, 132.44 13.79 M132.44 13.79 C132.44 23.28, 132.44 32.77, 132.44 41.37 M132.44 41.37 C132.44 50.57, 127.84 55.16, 118.65 55.16 M118.65 55.16 C97.02 55.16, 75.4 55.16, 13.79 55.16 M13.79 55.16 C4.6 55.16, 0 50.57, 0 41.37 M0 41.37 C0 35.05, 0 28.73, 0 13.79 M0 13.79 C0 4.6, 4.6 0, 13.79 0" stroke="#1e1e1e" stroke-width="2.5" fill="none" stroke-dasharray="8 10"/></g><g transform="translate(94.78125 78.6328125) rotate(0 57.02396151423454 10)"><text x="0" y="14.096" font-family="Virgil, Segoe UI Emoji" font-size="16px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">current_frame</text></g><g stroke-linecap="round" transform="translate(10 203.4609375) rotate(0 44.251953125 28.306640625)"><path d="M14.15 0 C29.08 0, 44 0, 74.35 0 M14.15 0 C30.32 0, 46.48 0, 74.35 0 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M88.5 14.15 C88.5 23.61, 88.5 33.07, 88.5 42.46 M88.5 14.15 C88.5 23.24, 88.5 32.33, 88.5 42.46 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M74.35 56.61 C54.33 56.61, 34.3 56.61, 14.15 56.61 M74.35 56.61 C61.56 56.61, 48.77 56.61, 14.15 56.61 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M0 42.46 C0 34.4, 0 26.33, 0 14.15 M0 42.46 C0 31.74, 0 21.01, 0 14.15 M0 14.15 C0 4.72, 4.72 0, 14.15 0 M0 14.15 C0 4.72, 4.72 0, 14.15 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(37.99196645617485 219.267578125) rotate(0 16.25998666882515 12.5)"><text x="16.25998666882515" y="17.619999999999997" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#1e1e1e" text-anchor="middle" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">foo</text></g><g stroke-linecap="round" transform="translate(130.736328125 201.412109375) rotate(0 44.251953125 28.306640625)"><path d="M14.15 0 C28.37 0, 42.59 0, 74.35 0 M14.15 0 C27.71 0, 41.28 0, 74.35 0 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M88.5 14.15 C88.5 25.48, 88.5 36.8, 88.5 42.46 M88.5 14.15 C88.5 20.49, 88.5 26.83, 88.5 42.46 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M74.35 56.61 C53.8 56.61, 33.24 56.61, 14.15 56.61 M74.35 56.61 C54.98 56.61, 35.6 56.61, 14.15 56.61 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M0 42.46 C0 32.66, 0 22.86, 0 14.15 M0 42.46 C0 33.84, 0 25.23, 0 14.15 M0 14.15 C0 4.72, 4.72 0, 14.15 0 M0 14.15 C0 4.72, 4.72 0, 14.15 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(158.39828994870186 217.21875) rotate(0 16.58999130129814 12.5)"><text x="16.58999130129814" y="17.619999999999997" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#1e1e1e" text-anchor="middle" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">bar</text></g><g stroke-linecap="round" transform="translate(250.193359375 198.974609375) rotate(0 44.251953125 28.306640625)"><path d="M14.15 0 C30.65 0, 47.15 0, 74.35 0 M14.15 0 C35.11 0, 56.06 0, 74.35 0 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M74.35 0 C83.79 0, 88.5 4.72, 88.5 14.15 M88.5 14.15 C88.5 24.54, 88.5 34.93, 88.5 42.46 M88.5 14.15 C88.5 22.15, 88.5 30.14, 88.5 42.46 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M88.5 42.46 C88.5 51.9, 83.79 56.61, 74.35 56.61 M74.35 56.61 C55.68 56.61, 37.01 56.61, 14.15 56.61 M74.35 56.61 C59.28 56.61, 44.22 56.61, 14.15 56.61 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M14.15 56.61 C4.72 56.61, 0 51.9, 0 42.46 M0 42.46 C0 32, 0 21.53, 0 14.15 M0 42.46 C0 33.52, 0 24.57, 0 14.15 M0 14.15 C0 4.72, 4.72 0, 14.15 0 M0 14.15 C0 4.72, 4.72 0, 14.15 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(274.3353255391121 214.78125) rotate(0 20.10998696088791 12.5)"><text x="20.10998696088791" y="17.619999999999997" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#1e1e1e" text-anchor="middle" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">main</text></g><g stroke-linecap="round"><g transform="translate(108.14453125 119.765625) rotate(0 -41.185546875 40.9609375)"><path d="M0 0 C-13.73 13.65, -68.64 68.27, -82.37 81.92 M0 0 C-13.73 13.65, -68.64 68.27, -82.37 81.92" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(108.14453125 119.765625) rotate(0 -41.185546875 40.9609375)"><path d="M-71.74 59.29 C-75.88 68.1, -80.02 76.91, -82.37 81.92 M-71.74 59.29 C-74.34 64.81, -76.93 70.33, -82.37 81.92" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(108.14453125 119.765625) rotate(0 -41.185546875 40.9609375)"><path d="M-59.68 71.42 C-68.52 75.51, -77.35 79.6, -82.37 81.92 M-59.68 71.42 C-65.22 73.98, -70.75 76.54, -82.37 81.92" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g stroke-linecap="round"><g transform="translate(103.23046875 230.796875) rotate(0 13.08984375 0)"><path d="M0 0 C4.36 0, 21.82 0, 26.18 0 M0 0 C4.36 0, 21.82 0, 26.18 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(103.23046875 230.796875) rotate(0 13.08984375 0)"><path d="M13.88 4.48 C16.48 3.53, 19.07 2.59, 26.18 0 M13.88 4.48 C18.54 2.78, 23.21 1.08, 26.18 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(103.23046875 230.796875) rotate(0 13.08984375 0)"><path d="M13.88 -4.48 C16.48 -3.53, 19.07 -2.59, 26.18 0 M13.88 -4.48 C18.54 -2.78, 23.21 -1.08, 26.18 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g stroke-linecap="round"><g transform="translate(220.2578125 228.8515625) rotate(0 14.720703125 0)"><path d="M0 0 C4.91 0, 24.53 0, 29.44 0 M0 0 C4.91 0, 24.53 0, 29.44 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(220.2578125 228.8515625) rotate(0 14.720703125 0)"><path d="M15.61 5.03 C19.81 3.51, 24.01 1.98, 29.44 0 M15.61 5.03 C21.02 3.07, 26.43 1.1, 29.44 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(220.2578125 228.8515625) rotate(0 14.720703125 0)"><path d="M15.61 -5.03 C19.81 -3.51, 24.01 -1.98, 29.44 0 M15.61 -5.03 C21.02 -3.07, 26.43 -1.1, 29.44 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g stroke-linecap="round" transform="translate(416.4609375 49.79296875) rotate(0 37.818359375 129.54296875)"><path d="M18.91 0 C29.11 0, 39.31 0, 56.73 0 M18.91 0 C27.66 0, 36.41 0, 56.73 0 M56.73 0 C69.33 0, 75.64 6.3, 75.64 18.91 M56.73 0 C69.33 0, 75.64 6.3, 75.64 18.91 M75.64 18.91 C75.64 94.35, 75.64 169.8, 75.64 240.18 M75.64 18.91 C75.64 71.33, 75.64 123.75, 75.64 240.18 M75.64 240.18 C75.64 252.78, 69.33 259.09, 56.73 259.09 M75.64 240.18 C75.64 252.78, 69.33 259.09, 56.73 259.09 M56.73 259.09 C47.05 259.09, 37.37 259.09, 18.91 259.09 M56.73 259.09 C48.55 259.09, 40.37 259.09, 18.91 259.09 M18.91 259.09 C6.3 259.09, 0 252.78, 0 240.18 M18.91 259.09 C6.3 259.09, 0 252.78, 0 240.18 M0 240.18 C0 180.78, 0 121.39, 0 18.91 M0 240.18 C0 169.52, 0 98.86, 0 18.91 M0 18.91 C0 6.3, 6.3 0, 18.91 0 M0 18.91 C0 6.3, 6.3 0, 18.91 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g><g transform="translate(385.44140625 10) rotate(0 64.7499478161335 12.5)"><text x="0" y="17.619999999999997" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">Python stack</text></g><g transform="translate(436.203125 57.8125) rotate(0 16.087992817163467 10)"><text x="0" y="14.096" font-family="Virgil, Segoe UI Emoji" font-size="16px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">main</text></g><g stroke-linecap="round"><g transform="translate(416.15234375 85.1171875) rotate(0 38.224609375 0)"><path d="M0 0 C12.74 0, 63.71 0, 76.45 0 M0 0 C12.74 0, 63.71 0, 76.45 0" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g transform="translate(438.6875 92.04296875) rotate(0 13.27199399471283 10)"><text x="0" y="14.096" font-family="Virgil, Segoe UI Emoji" font-size="16px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">bar</text></g><g stroke-linecap="round"><g transform="translate(416.56640625 117.6953125) rotate(0 37.03125 0.08984375)"><path d="M0 0 C12.34 0.03, 61.72 0.15, 74.06 0.18 M0 0 C12.34 0.03, 61.72 0.15, 74.06 0.18" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g transform="translate(438.83203125 125.76171875) rotate(0 13.007992014288902 10)"><text x="0" y="14.096" font-family="Virgil, Segoe UI Emoji" font-size="16px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">foo</text></g><g stroke-linecap="round"><g transform="translate(416.546875 149.51171875) rotate(0 37.619140625 0.05078125)"><path d="M0 0 C12.54 0.02, 62.7 0.08, 75.24 0.1 M0 0 C12.54 0.02, 62.7 0.08, 75.24 0.1" stroke="#1e1e1e" stroke-width="1" fill="none"/></g></g><mask/><g transform="translate(86.2265625 168.10546875) rotate(0 93.0959243774414 10)"><text x="0" y="14.096" font-family="Virgil, Segoe UI Emoji" font-size="16px" fill="#1e1e1e" text-anchor="start" style="white-space: pre;" direction="ltr" dominant-baseline="alphabetic">PyInterpreterFrame list</text></g></svg>

The process of passing symbols from the eBPF context to the user space is not trivial. Copying symbol names on each frame processing is avoided as it is not efficient.

[Python Symbolization](https://perforator.tech/docs/en/reference/language-support/python/symbolization.md) section describes how python symbols are handled in the eBPF program.
