프로파일링 및 추적¶

파이썬 인터프리터는 프로파일링 및 실행 추적 기능을 연결하기 위한 일부 낮은 수준의 지원을 제공합니다. 이 기능들은 프로파일링, 디버깅, 커버리지 분석 도구에 사용됩니다.

이 C 인터페이스를 통해 프로파일링 또는 추적 코드가 파이썬 수준의 호출 가능 객체를 거치는 오버헤드를 피하고 대신 직접 C 함수를 호출할 수 있습니다. 이 기능의 핵심 속성은 변경되지 않았으며, 인터페이스는 스레드별로 추적 함수를 설치할 수 있게 하고 이전 버전에서 파이썬 레벨 추적 함수에 보고되었던 것과 동일한 기본 이벤트들을 추적 함수에 보고합니다.

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)¶

PyEval_SetProfile() 및 PyEval_SetTrace() 를 사용하여 등록된 추적 함수의 유형입니다. 첫 번째 매개변수는 등록 함수에 obj 로 전달되는 객체이며, frame 은 해당 이벤트와 관련된 프레임 객체이고, what 은 PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN, 또는 PyTrace_OPCODE 중 하나의 상수이며, arg 는 what 의 값에 따라 달라집니다.

what 의 값	arg 의 의미
`PyTrace_CALL`	항상 `Py_None` 입니다.
`PyTrace_EXCEPTION`	`sys.exc_info()` 에 의해 반환되는 예외 정보입니다.
`PyTrace_LINE`	항상 `Py_None` 입니다.
`PyTrace_RETURN`	호출자에게 반환되는 값이며, 예외로 인해 발생한 경우 `NULL` 입니다.
`PyTrace_C_CALL`	호출되는 함수 객체입니다.
`PyTrace_C_EXCEPTION`	호출되는 함수 객체입니다.
`PyTrace_C_RETURN`	호출되는 함수 객체입니다.
`PyTrace_OPCODE`	항상 `Py_None` 입니다.

int PyTrace_CALL¶: 함수나 메서드에 대한 새로운 호출이 보고되거나 제너레이터에 새 항목이 진입할 때 Py_tracefunc 함수의 what 매개변수 값입니다. 제너레이터 함수를 위한 이터레이터 생성은 해당 프레임에서 파이썬 바이트 코드로의 제어 전송이 없으므로 보고되지 않음에 유의하십시오.

int PyTrace_EXCEPTION¶: 예외가 발생했을 때 Py_tracefunc 함수의 what 매개변수 값입니다. 콜백 함수는 실행 중인 프레임 내에서 바이트 코드가 처리되고 예외가 설정된 후, 해당 what 에 대한 이 값으로 호출됩니다. 이로 인해 예외 전파로 파이썬 스택이 되감길 때(unwind), 예외가 전파되면서 각 프레임으로 반환될 때 콜백이 호출됩니다. 이러한 이벤트는 추적 함수만 수신하며 프로파일러에서는 필요하지 않습니다.

int PyTrace_LINE¶: 라인 번호 이벤트가 보고될 때 Py_tracefunc 함수(프로파일링 함수 제외)에 what 매개변수로 전달되는 값입니다. 해당 프레임의 f_trace_lines 를 0 으로 설정하여 비활성화할 수 있습니다.

int PyTrace_RETURN¶: 호출이 반환되려 할 때 Py_tracefunc 함수의 what 매개변수 값입니다.

int PyTrace_C_CALL¶: C 함수가 호출되려 할 때 Py_tracefunc 함수의 what 매개변수 값입니다.

int PyTrace_C_EXCEPTION¶: C 함수에서 예외가 발생했을 때 Py_tracefunc 함수의 what 매개변수 값입니다.

int PyTrace_C_RETURN¶: C 함수가 반환되었을 때 Py_tracefunc 함수의 what 매개변수 값입니다.

int PyTrace_OPCODE¶: 새로운 옵코드가 실행되려 할 때 Py_tracefunc 함수(프로파일링 함수 제외)의 what 매개변수 값입니다. 이 이벤트는 기본적으로 발생하지 않으며, 해당 프레임에서 f_trace_opcodes 를 1 로 설정하여 명시적으로 요청해야 합니다.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)¶

프로파일러 함수를 func 로 설정합니다. obj 매개변수는 함수의 첫 번째 매개변수로 전달되며, 임의의 파이썬 객체 또는 NULL 일 수 있습니다. 프로파일 함수가 상태를 유지해야 하는 경우, 각 스레드에 대해 다른 obj 값을 사용하면 편리하고 스레드 안전하게 이를 저장할 수 있는 공간을 제공합니다. 프로파일 함수는 PyTrace_LINE, PyTrace_OPCODE, 그리고 PyTrace_EXCEPTION 을 제외한 모든 모니터링 이벤트에 대해 호출됩니다.

sys.setprofile() 함수를 참고하십시오.

호출자는 반드시 attached thread state 를 보유해야 합니다.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)¶

PyEval_SetProfile() 과 유사하지만, 현재 스레드에만 설정하는 대신 현재 인터프리터에 속한 모든 실행 중인 스레드에 프로파일 함수를 설정합니다.

호출자는 반드시 attached thread state 를 보유해야 합니다.

PyEval_SetProfile() 와 마찬가지로, 이 함수는 모든 스레드에 프로파일 함수를 설정하는 동안 발생하는 예외를 무시합니다.

Added in version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)¶

추적 함수를 func 로 설정합니다. 이는 PyEval_SetProfile() 과 유사하지만, 추적 함수가 라인 번호 및 옵코드별 이벤트를 수신하는 대신 C 함수 객체 호출 관련 이벤트는 수신하지 않습니다. PyEval_SetTrace() 를 사용하여 등록된 모든 추적 함수는 what 매개변수의 값으로 PyTrace_C_CALL, PyTrace_C_EXCEPTION 또는 PyTrace_C_RETURN 을 수신하지 않습니다.

sys.settrace() 함수를 참고하십시오.

호출자는 반드시 attached thread state 를 보유해야 합니다.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)¶

PyEval_SetTrace() 와 유사하지만, 현재 스레드에만 설정하는 대신 현재 인터프리터에 속한 모든 실행 중인 스레드에 추적 함수를 설정합니다.

호출자는 반드시 attached thread state 를 보유해야 합니다.

PyEval_SetTrace() 와 마찬가지로, 이 함수는 모든 스레드에 추적 함수를 설정하는 동안 발생하는 예외를 무시합니다.

Added in version 3.12.

참조 추적¶

Added in version 3.13.

typedef int (*PyRefTracer)(PyObject*, int event, void *data)¶

PyRefTracer_SetTracer() 를 사용하여 등록된 추적 함수의 유형입니다. 첫 번째 매개변수는 방금 생성되었거나(event 가 PyRefTracer_CREATE 로 설정된 경우) 또는 곧 파기될(머티션이 event 가 PyRefTracer_DESTROY 로 설정된 경우) 파이썬 객체입니다. data 인자는 PyRefTracer_SetTracer() 호출 시 제공된 불투명 포인터입니다.

현재 함수를 대체하는 새로운 추적 함수가 등록되는 경우, 객체가 NULL 로 설정되고 event 가 PyRefTracer_TRACKER_REMOVED 로 설정된 상태에서 추적 함수 호출이 발생합니다. 이는 새 기능이 등록되기 직전에 발생합니다.

Added in version 3.13.

int PyRefTracer_CREATE¶: 파이썬 객체가 생성되었을 때 PyRefTracer 함수의 event 매개변수 값입니다.

int PyRefTracer_DESTROY¶: 파이썬 객체가 파기되었을 때 PyRefTracer 함수의 event 매개변수 값입니다.

int PyRefTracer_TRACKER_REMOVED¶: 현재 추적자가 새 것으로 교체되기 직전일 때 PyRefTracer 함수의 event 매개변수 값입니다.

Added in version 3.14.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)¶

참조 추적 함수를 등록합니다. 이 함수는 새로운 파이썬 객체가 생성되거나 객체가 파기될 예정일 때 호출됩니다. data 가 제공되는 경우, 이는 추적 함수가 호출될 때 제공될 불투명 포인터여야 합니다. 성공 시 0 을 반환하고, 오류 시 예외를 설정하고 -1 을 반환합니다.

추적 함수 내부에서 파이썬 객체를 생성해서는 안 됩니다. 그렇지 않으면 호출이 재진입(re-entrant)될 수 있습니다. 또한 추적자는 기존 예외를 지우거나 새 예외를 설정해서도 안 됩니다. 추적 함수가 호출될 때마다 thread state 가 활성화됩니다.

There must be an attached thread state when calling this function.

다른 추적 함수가 이미 등록된 경우, 새 함수가 등록되기 직전에 이전 함수가 event 가 PyRefTracer_TRACKER_REMOVED 로 설정된 상태로 호출됩니다.

Added in version 3.13.

PyRefTracer PyRefTracer_GetTracer(void **data)¶

등록된 참조 추적 함수와 PyRefTracer_SetTracer() 가 호출될 때 등록된 불투명 데이터 포인터 값을 가져옵니다. 등록된 추적자가 없는 경우 이 함수는 NULL을 반환하고 data 포인터를 NULL로 설정합니다.

There must be an attached thread state when calling this function.

Added in version 3.13.