콘텐츠로 이동

Python Annotation API

1
import hapti

코드 내 특정 구간이나 시점에 명칭을 부여하여 트레이스상에 시각화하기 위한 API입니다.

함수 시그니처 비고
annotate (message: str) -> ContextManager[None] 컨텍스트 매니저. 진입 시점에 Range를 열고 종료 시점에 닫으며, 블록 내 예외 발생 시에도 안전하게 닫힘
range_push (message: str) -> int 호출 스레드의 Range 스택에 새로운 Range를 엶. 현재 Range의 중첩 깊이(0부터 시작)를 반환
range_pop () -> int 가장 최근에 푸시된 Range를 닫음. 닫힌 Range의 깊이를 반환하며, 스택이 비어 있는 경우 -1 반환
range_start (message: str) -> int 스택 구조와 무관한 독립된 Range를 엶. 프로세스 전역에서 유효한 핸들(Handle, int)을 반환
range_stop (id: int) -> None range_start()로 생성한 Range를 핸들 기반으로 닫음. 유효하지 않은 핸들은 안전하게 무시됨
mark (message: str) -> None 지속 구간(Range)이 아닌 특정 단일 시점을 이벤트로 기록

프로덕션 코드 유지

주석(Annotation)은 haprof 런처 환경에서 실행된 경우에만 트레이스에 기록됩니다. haprof 없이 일반 환경에서 실행할 경우, import 및 관련 함수 호출은 에러 없이 정상 수행되되 아무런 데이터도 기록하지 않습니다. 따라서 프로덕션 코드 내에 주석 코드를 제거하지 않고 그대로 유지해도 안전합니다.


예제

annotate

블록 하나를 range로 감쌉니다.

예제
1
2
3
4
import hapti

with hapti.annotate("decode"):
    out = model.step()

range_push

블록에 맞지 않는 range를 엽니다. 반드시 같은 스레드에서 range_pop으로 닫습니다.

예제
1
2
3
4
5
6
7
import hapti

depth = hapti.range_push("decode")   # 바깥에 열린 range가 없으면 0
try:
    out = model.step()
finally:
    hapti.range_pop()

range_pop

가장 최근에 연 range를 닫습니다. 반환값으로 push/pop 균형을 확인할 수 있습니다.

예제
1
2
3
4
5
6
7
import hapti

hapti.range_push("outer")
hapti.range_push("inner")
assert hapti.range_pop() == 1        # inner
assert hapti.range_pop() == 0        # outer
assert hapti.range_pop() == -1       # 닫을 것이 없음

range_start

스택과 독립적인 range를 엽니다. 구간이 겹치거나 함수·스레드 경계를 넘어도 됩니다.

예제
1
2
3
4
5
import hapti

handle = hapti.range_start("request-42")
...                                  # 다른 range와 겹쳐도 됩니다
hapti.range_stop(handle)

range_stop

range_start가 돌려준 handle로 range를 닫습니다.

예제
1
2
3
4
5
6
import hapti

a = hapti.range_start("request-1")
b = hapti.range_start("request-2")
hapti.range_stop(a)                  # 연 순서와 무관하게 닫을 수 있습니다
hapti.range_stop(b)

mark

지속 시간이 없는 시점을 기록합니다.

예제
1
2
3
import hapti

hapti.mark("first token")