함수와 프로시저의 추적 이벤트¶

Snowpark API를 사용하여 작성한 것을 포함하여 프로시저, UDF 또는 UDTF의 처리기 코드에서 추적 이벤트를 내보낼 수 있습니다. 지원되는 처리기 언어 목록은 지원되는 언어 섹션을 참조하십시오.

참고

추적 이벤트 데이터를 수집하려면 먼저 원격 분석 데이터 수집을 활성화 해야 합니다. 코드를 측정 하면 Snowflake가 데이터를 생성하여 이벤트 테이블에 수집합니다.

추적 이벤트는 시스템 또는 애플리케이션에서 어떤 일이 발생했을 때 캡처할 수 있는 원격 분석 데이터의 한 유형입니다(예: 로그 메시지). 로그 메시지와 달리, 추적 이벤트에는 구조화된 페이로드가 있어 데이터 분석에 적합합니다. 예를 들어 추적 이벤트를 사용하여 함수 실행 중에 계산된 일부 숫자를 캡처하고 나중에 이러한 숫자를 분석할 수 있습니다.

프로시저 또는 UDF에서 추적 이벤트의 일부로 캡처해야 하는 특성(키-값 페어)을 연결할 수 있습니다. 예를 들어 추적 이벤트에서 매개 변수의 이름과 값을 캡처하려는 경우 parameters 라는 추적 이벤트를 추가하고 매개 변수의 이름과 값을 이벤트의 특성으로 설정할 수 있습니다.

프로시저 또는 함수가 성공적으로 실행되면 Snowflake가 추가된 추적 이벤트를 내보냅니다. Snowflake는 계정과 연결된 활성 이벤트 테이블에서 이러한 추적 이벤트를 사용할 수 있도록 합니다. 이벤트 테이블에 대한 설명은 이벤트 테이블 개요 섹션을 참조하십시오.

다음과 같은 방법으로 분석을 위해 추적 이벤트 데이터에 액세스 할 수 있습니다.

이벤트 테이블에서 SELECT 명령을 실행합니다.
Snowsight 에서 추적 항목을 봅니다.

추적 예제¶

다음 예제의 Python 코드는 값이 begin 인 범위에 대해 example.proc.do_tracing 특성을 설정합니다. 또한 범위 내에서 example.key1 및 example.key2 특성이 있는 event_with_attributes 이벤트를 내보냅니다.

CREATE OR REPLACE PROCEDURE do_tracing()
RETURNS VARIANT
LANGUAGE PYTHON
PACKAGES=('snowflake-snowpark-python', 'snowflake-telemetry-python')
RUNTIME_VERSION = 3.9
HANDLER='run'
AS $$
from snowflake import telemetry
def run(session):
  telemetry.set_span_attribute("example.proc.do_tracing", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  return "SUCCESS"
$$;

Copy

시작하기¶

처리기 코드에서 이벤트 추적을 시작하려면 대략적으로 다음 단계를 따르십시오.

이벤트 테이블을 설정합니다.

Snowflake는 이벤트 테이블을 사용하여 처리기 코드에서 내보낸 이벤트 데이터를 저장합니다. 이벤트 테이블에는 Snowflake에서 미리 정의한 열이 있습니다.
사용할 처리기 언어에 대한 이벤트 추적 API를 익히십시오.

처리기 언어 목록은 지원되는 언어 섹션을 참조하고, 해당 언어에서 추적 이벤트를 내보내는 방법에 대한 내용 을 확인합니다.
처리기에 이벤트 추적 코드를 추가합니다.
이벤트 테이블에서 이벤트 추적 데이터 검색 방법을 알아보십시오.

추적 이벤트의 수준¶

추적 수준을 설정하여 이벤트 테이블에 저장되는 추적 이벤트 데이터의 세부 정보 표시를 관리할 수 있습니다. 추적하기 전에 이 설정을 사용하여 로그 메시지 심각도를 캡처하고 있는지 확인합니다. 이벤트 데이터가 테이블에 기록되지 않는다면 추적 수준을 확인하여 Snowflake가 원하는 데이터를 캡처하고 있는지 확인합니다.

자세한 내용은 로깅, 메트릭 및 추적을 위한 수준 설정하기 섹션을 참조하십시오.

지원되는 언어¶

다음 언어로 작성된 코드의 이벤트를 추적할 수 있으며, 핸들러 코드가 Snowpark APIs 로 작성된 경우도 포함됩니다.

언어/유형	Java	Python	JavaScript	Scala	Snowflake Scripting
저장 프로시저 핸들러	✔	✔	✔	✔	✔
Streamlit 앱		✔
UDF 핸들러(스칼라 함수)	✔	✔	✔	✔
UDTF 핸들러(테이블 함수)	✔	✔	✔	✔ *

*:: Snowpark로 작성된 Scala UDTF 처리기.

처리기 코드에서 이벤트 추적¶

이벤트를 추적하려면 사용 중인 처리기 코드용으로 설계된 Snowflake 제공 라이브러리를 사용할 수 있습니다. Snowflake는 추적 이벤트를 가로채서 사용자가 만든 이벤트 테이블에 저장합니다.

다음 표에는 로깅에 지원되는 처리기 언어와 코드에서 로깅하기에 관한 콘텐츠로 연결되는 링크가 함께 나와 있습니다.

언어	원격 분석 라이브러리	설명서
Java	Snowflake `Telemetry` 클래스.	Java에서 추적 이벤트 내보내기
JavaScript	Snowflake JavaScriptAPI.	JavaScript에서 추적 이벤트 내보내기
Python	Snowflake `telemetry` 패키지.	Python에서 추적 이벤트 내보내기
Scala	Snowflake `Telemetry` 클래스.	Scala에서 추적 이벤트 내보내기
Snowflake Scripting	Snowflake SQL 함수.	Snowflake Scripting에서 추적 이벤트 내보내기

SQL 문 추적¶

기본적으로 :doc:`추적이 활성화된 </developer-guide/logging-tracing/logging-tracing-enabling>`경우, Snowflake에서는 저장 프로시저 또는 사용자 정의 함수의 처리기 내에서처럼 다른 추적 코드와 함께 실행되는 SQL 문을 추적합니다.

기본적으로 Snowflake는 다음과 같은 컨텍스트에서 SQL을 추적합니다.

저장 프로시저 내에서 실행되는 SQL
저장 프로시저를 실행하는 SQL
하나 이상의 사용자 정의 함수를 실행하는 SQL
DBT에서 실행되는 SQL
Streamlit에서 실행되는 SQL
Notebook에서 실행되는 SQL
코드 컨텍스트가 Python 또는 Go 커넥터인 경우 Snowpark Container Services에서 실행되는 SQL

다음과 같은 경우에는 지원되지 않습니다.

|native-app|의 SQL 문
워크시트 또는 작업 공간에서 SQL을 직접 실행하는 경우

추적된 SQL 문의 경우, 다음 열을 포함하여 이벤트 테이블에서 내보낸 데이터를 찾을 수 있습니다.

RESOURCE_ATTRIBUTES 열<label-event_table_resource_attributes_event_source>`에서 :code:`snow.executable.type 속성 값은 :code:`QUERY`입니다.
RECORD 열<label-event_table_record_column_span>`에서 :code:`name 속성 값은 실행이 추적된 SQL 문의 유형(예: SELECT, CALL 또는 INSERT)입니다.
:ref:`RECORD_ATTRIBUTES 열<label-event_table_record_attributes_span>`의 다음 속성에는 SQL 추적과 관련된 값이 포함됩니다.
- db.query.table.names
- db.query.view.names
- db.query.executable.names
- :code:`db.query.text`(활성화된 경우)

SQL 텍스트 자체(최대 1,024자)가 이벤트 테이블에 캡처된 추적 테이블에 포함되어야 하는지 여부를 지정할 수 있습니다. 민감한 정보를 포함할 수 있거나 유용하지 않은 경우 SQL 텍스트를 생략하는 것이 좋습니다.

추적 시 SQL 텍스트를 캡처하려면 SQL_TRACE_QUERY_TEXT 매개 변수를 :code:`”ON”`으로 설정합니다(ACCOUNTADMIN 역할을 사용하여 이 매개 변수를 설정해야 함).

추적 이벤트를 추가하는 일반 지침¶

추적 이벤트를 추가하고 범위 특성을 설정하기 위해 추적 이벤트 API를 호출할 때 다음 사항에 유의하십시오.

한 범위는 최대 128개의 추적 이벤트와 최대 128개의 범위 특성을 보유할 수 있습니다.
앞서 추가한 이벤트와 이름이 같은 추적 이벤트를 추가하면 새 이벤트 레코드가 생성됩니다.
앞서 설정한 범위 특성과 동일한 키를 가진 범위 특성을 설정하면 해당 키의 값을 덮어씁니다.

수집된 이벤트 데이터 보기¶

Snowsight 를 통해 또는 추적 데이터가 저장된 이벤트 테이블을 쿼리하여 추적 데이터를 볼 수 있습니다. 자세한 내용은 추적 데이터 보기 섹션을 참조하십시오.