자습서: 로깅 및 추적 시작하기

소개

이 자습서에서는 함수 및 프로시저 처리기 코드에서 로그 및 추적 데이터를 내보내고 수집하고 쿼리하는 기본 사항을 소개합니다.

이 자습서에서는 Snowsight 웹 인터페이스를 사용하지만, SQL 실행을 지원하는 모든 Snowflake 클라이언트를 사용할 수 있습니다. Snowsight 에 대한 자세한 내용은 워크시트 시작하기 및 Snowsight에서 워크시트 관리 및 사용하기 섹션을 참조하십시오.

알아볼 내용

이 자습서에서는 다음에 대해 설명합니다.

  • 로그 및 추적 데이터를 저장할 이벤트 테이블을 만드는 방법.

    Snowflake는 테이블의 미리 정의된 구조에서 로그 및 추적 데이터를 수집합니다.

  • 사용자 정의 함수(UDF)에서 로그 메시지와 추적 데이터를 내보내는 방법.

    처리기 언어용으로 설계된 API를 사용하여 처리기 코드에서 로그 메시지와 추적 데이터를 내보낼 수 있습니다.

  • 이벤트 테이블을 쿼리하여 수집된 로그 및 추적 데이터를 보는 방법.

    SELECT 문으로 테이블을 쿼리하여 수집된 데이터를 분석할 수 있습니다.

전제 조건

  • 세션 컨텍스트가 필요하므로 동일한 SQL 명령 세션에서 모든 SQL 명령을 실행해야 합니다.

    예를 들어 Snowsight 에서 이 작업을 수행하려면 단계를 진행하면서 모든 코드를 같은 워크시트에 붙여넣으십시오. 한 섹션에서 다음 섹션으로 진행할 때 각 섹션은 이전 섹션을 기반으로 합니다.

  • ACCOUNTADMIN 역할을 사용할 수 있어야 합니다.

    이 자습서에서는 ACCOUNTADMIN 역할을 사용하여 모든 단계를 수행합니다. 하지만 일반적으로 수행 중인 작업에 대해 특별히 정의된 권한이 있는 역할을 사용하게 될 것입니다. 예를 들어 UDF를 만드는 개발자, 수집된 로그와 추적 데이터를 쿼리하는 분석가 등, 별도의 역할을 가질 수 있습니다.

    역할에 대한 자세한 내용은 활성 역할 전환하기 및 액세스 제어 고려 사항 섹션을 참조하십시오.

데이터베이스, 웨어하우스 및 액세스 설정하기

이 섹션에서는 자습서에 필요한 웨어하우스와 데이터베이스를 만들어 봅니다. 또한 이 자습서에서 몇몇 문을 실행하는 데 필요한 ACCOUNTADMIN 역할을 사용하기 시작할 것입니다.

나중에 이벤트 테이블과 사용자 정의 함수를 만들 데이터베이스를 만드는 것입니다. 데이터베이스와 웨어하우스를 포함하여 자습서에서 만든 모든 오브젝트는 더 이상 필요하지 않을 때는 삭제할 수 있습니다.

자습서에서 사용할 데이터베이스와 웨어하우스를 만들려면 다음을 수행하십시오.

  1. Snowsight 에 로그인합니다.

  2. ACCOUNTADMIN 역할로 전환합니다.

  3. Projects » Worksheets 를 엽니다.

  4. + » SQL Worksheet 를 선택합니다.

  5. 새 워크시트의 이름을 에서 Logging-tracing tutorial 로 바꿉니다.

  6. 새 워크시트에서 다음 문을 붙여넣고 실행하여 데이터베이스를 만듭니다. 새 데이터베이스는 이 자습서에서만 사용하기 위한 것입니다.

    CREATE OR REPLACE DATABASE tutorial_log_trace_db;
    Copy

  7. 다음 문을 붙여넣고 실행하여 웨어하우스를 만듭니다. 새 웨어하우스는 이 자습서에서만 사용하기 위한 것입니다.

    CREATE OR REPLACE WAREHOUSE tutorial_log_trace_wh
  WAREHOUSE_TYPE = STANDARD
  WAREHOUSE_SIZE = XSMALL;
    Copy

이 섹션에서는 자습서의 예제를 실행하는 데 필요한 부분을 준비합니다. 다음 섹션에서는 로그 및 추적 데이터를 저장하기 위한 이벤트 테이블을 만듭니다.

이벤트 테이블 만들기

이 섹션에서는 이벤트 테이블을 만듭니다. 처리기 코드가 로그 메시지와 추적 데이터를 내보낼 때 Snowflake는 내보낸 데이터를 이벤트 테이블 행에 저장합니다. 이벤트 테이블을 쿼리하여 데이터를 분석할 수 있습니다.

로그 및 추적 데이터를 수집하려면 이벤트 테이블을 만들어야 합니다. 이벤트 테이블은 항상 Snowflake에서 정의한 미리 정의된 구조 를 사용합니다.

중요

이 섹션을 완료하려면 새 이벤트 테이블이 계정의 활성 이벤트 테이블이 되도록 계정을 변경할 때 필요한 ACCOUNTADMIN 역할을 사용할 수 있어야 합니다.

이벤트 테이블을 만들고 계정의 활성 이벤트 테이블로 만들려면 다음을 수행하십시오.

  1. 다음 문을 붙여넣고 실행하여 이벤트 테이블을 만듭니다.

    CREATE OR REPLACE EVENT TABLE tutorial_event_table;
    Copy

    이 테이블은 Snowflake가 로그와 추적 데이터를 저장하는 곳입니다.

  2. 만든 이벤트 테이블이 계정의 활성 테이블이 되도록 다음 문을 붙여넣고 실행하여 계정을 변경합니다.

    ALTER ACCOUNT SET EVENT_TABLE = tutorial_log_trace_db.public.tutorial_event_table;
    Copy

    이 문은 새 이벤트 테이블을 Snowflake가 현재 계정의 처리기에서 로그 메시지와 추적 데이터를 저장하는 데 사용해야 하는 테이블로 설정합니다. 한 계정에 하나의 활성 이벤트 테이블만 있을 수 있습니다.

이 섹션에서는 이벤트 테이블을 만들어 보았습니다. 다음 섹션에서는 Snowflake가 테이블에 저장하는 로그 메시지 내보내기를 시작해 보겠습니다.

로그 메시지 내보내기

이 섹션에서는 로그 메시지를 내보내는 Python 처리기 코드를 사용하여 사용자 정의 함수(UDF)를 만들어 봅니다. 코드에서 로그 메시지를 내보내면 Snowflake가 메시지 데이터를 수집하여 앞서 만든 이벤트 테이블에 저장합니다.

Snowflake는 지원되는 각 처리기 언어의 메시지를 로깅하는 API를 지원합니다. Python으로 작성하는 처리기의 경우 Python의 표준 라이브러리에서 logging 모듈을 사용할 수 있습니다.

로그 메시지를 내보내는 UDF를 만들려면 다음을 수행하십시오.

  1. 다음 문을 붙여넣고 실행하여 로그 수준을 INFO 로 설정합니다.

    ALTER SESSION SET LOG_LEVEL = INFO;
    Copy

    이를 통해 UDF가 실행될 때 Snowflake가 캡처해야 하는 로그 메시지의 심각도가 지정됩니다. 이 경우의 수준에서는 정보 메시지(INFO)부터 가장 심각한 메시지(FATAL)까지의 모든 메시지가 허용됩니다.

  2. 다음 문을 붙여넣고 실행하여 사용자 정의 함수를 만듭니다.

    CREATE OR REPLACE FUNCTION log_trace_data()
RETURNS VARCHAR
LANGUAGE PYTHON
RUNTIME_VERSION = 3.8
HANDLER = 'run'
AS $$
import logging
logger = logging.getLogger("tutorial_logger")

def run():
  logger.info("Logging from Python function.")
  return "SUCCESS"
$$;
    Copy

    코드에서 강조 표시된 줄은 다음을 수행합니다.

    • 처리기 코드에서 사용할 수 있도록 Python logging 모듈을 가져옵니다.

    • 코드가 메시지를 로깅하는 데 사용할 인터페이스를 노출하는 로거를 만듭니다.

    • INFO 수준에서 메시지를 로깅합니다.

  3. 다음 문을 붙여넣고 실행하여 방금 만든 함수를 실행합니다.

    SELECT log_trace_data();
    Copy

    그러면 다음 출력이 생성됩니다. 또한 함수가 실행되면서 Snowflake가 이벤트 테이블에 수집한 로그 메시지를 내보냈습니다.

    --------------------
| LOG_TRACE_DATA() |
--------------------
| SUCCESS          |
--------------------

이 섹션에서는 UDF에서 로그 메시지를 내보내 보았습니다. 다음 섹션에서는 이벤트 테이블을 쿼리하여 메시지와 관련된 데이터를 검색해 보겠습니다.

로그 메시지의 쿼리

이 섹션에서는 이전 섹션에서 실행한 UDF에서 내보낸 로그 메시지 데이터에 대한 이벤트 테이블을 쿼리해 보겠습니다.

참고

처리기 코드에서 내보낸 로그 또는 추적 데이터가 이벤트 테이블에 기록되는 데 몇 초가 걸릴 수 있습니다. 결과가 즉시 표시되지 않으면 몇 초 후에 다시 시도하십시오.

Snowflake는 미리 정의된 이벤트 테이블 열 을 사용하여 다음 종류의 로그 및 추적 데이터를 수집하고 저장합니다.

  • 로그 메시지 및 추적 이벤트 데이터와 같이, 처리기 코드에서 내보내는 데이터.

    RECORD_TYPE, RECORD, RECORD_ATTRIBUTES 등의 열에서 이러한 데이터를 찾을 수 있습니다.

  • 타임스탬프, 데이터를 내보낸 처리기 메서드의 이름 등과 같이, 로그 또는 추적 데이터를 내보낸 컨텍스트에 대한 데이터.

    RESOURCE_ATTRIBUTES, TIMESTAMP, SCOPE와 같은 열에서 이 데이터를 찾을 수 있습니다.

로그 메시지 데이터에 대한 이벤트 테이블을 쿼리하려면 다음을 수행하십시오.

  1. 다음 문을 붙여넣고 실행하여 이벤트 테이블을 쿼리합니다.

    SELECT
  TIMESTAMP AS time,
  RESOURCE_ATTRIBUTES['snow.executable.name'] as executable,
  RECORD['severity_text'] AS severity,
  VALUE AS message
FROM
  tutorial_log_trace_db.public.tutorial_event_table
WHERE
  RECORD_TYPE = 'LOG'
  AND SCOPE['name'] = 'tutorial_logger';
    Copy

    일부 열에는 키-값 페어로 표현된 정형 데이터가 포함됩니다. 이 쿼리에서는 RECORD['severity_text'] 와 같은 대괄호 표기법 을 사용하여 열 내의 특성 키를 지정합니다.

    또한 대괄호 표기법(SCOPE['name'])을 사용하여 처리기 코드에서 만든 Python 로거 tutorial_logger 로 로그 항목을 내보내는 열 값만 선택하도록 지정합니다.

  2. 출력을 확인합니다.

    -----------------------------------------------------------------------------------------------------------
| TIME                | EXECUTABLE                           | SEVERITY | MESSAGE                         |
-----------------------------------------------------------------------------------------------------------
| 2023-04-19 22:00:49 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "INFO"   | "Logging from Python function." |
-----------------------------------------------------------------------------------------------------------

    출력에는 이벤트 테이블의 미리 정의된 열 이 각각 수집된 데이터의 일부를 포함하는 방법이 표시됩니다. EXECUTABLE 및 SEVERITY 값의 경우 대괄호 표기법을 사용하여 원하는 값을 가진 특성을 지정했습니다.

    출력 열

    설명

    TIME

    (TIMESTAMP 열에서) 항목이 생성된 시간입니다.

    EXECUTABLE

    (RESOURCE_ATTRIBUTES 열의 snow.executable.name 특성에서 가져온) UDF 이름 및 매개 변수입니다.

    SEVERITY

    (RECORD 열의 severity_text 특성에서 가져온) 로그 항목 심각도입니다.

    MESSAGE

    (VALUE 열의) 로그 메시지입니다.

이 섹션에서는 SELECT 문을 사용하여 로그 데이터를 쿼리해 보았습니다. 다음 섹션에서는 추적 데이터를 내보내도록 UDF를 업데이트해 보겠습니다.

추적 데이터 내보내기

이 섹션에서는 추적 데이터도 내보내도록 UDF 처리기 코드를 업데이트해 보겠습니다. 코드에서 추적 데이터를 내보내면 Snowflake가 데이터를 수집하여 앞서 만든 이벤트 테이블에 저장합니다.

추적 데이터에는 범위로 그룹화된 이벤트 데이터와 키-값 페어로 캡처된 데이터를 포함하여 구조적 특성이 있어 로그 데이터가 일반적으로 허용하는 것보다 더 자세한 코드 활동 상황을 조합할 수 있습니다.

Snowflake는 지원되는 각 처리기 언어에서 추적 데이터를 내보내는 API를 지원합니다. Python으로 작성하는 처리기의 경우 Snowflake telemetry 패키지를 사용할 수 있습니다.

추적 데이터를 내보내도록 UDF를 업데이트하려면 다음을 수행하십시오.

  1. 다음 문을 붙여넣고 실행하여 캡처해야 하는 추적 데이터를 지정합니다.

    ALTER SESSION SET TRACE_LEVEL = ON_EVENT;
    Copy

    그러면 추적 수준이 ON_EVENT 로 설정됩니다. 이를 통해 자신의 코드에서 명시적으로 내보낸 추적 데이터만 캡처하도록 지정합니다.

  2. 다음 문을 붙여넣고 실행하여 추적 데이터를 내보내는 UDF를 만듭니다.

    CREATE OR REPLACE FUNCTION log_trace_data()
RETURNS VARCHAR
LANGUAGE PYTHON
PACKAGES = ('snowflake-telemetry-python')
RUNTIME_VERSION = 3.8
HANDLER = 'run'
AS $$
import logging
logger = logging.getLogger("tutorial_logger")
from snowflake import telemetry

def run():
  telemetry.set_span_attribute("example.proc.run", "begin")
  telemetry.add_event("event_with_attributes", {"example.key1": "value1", "example.key2": "value2"})
  logger.info("Logging from Python function.")
  return "SUCCESS"
$$;
    Copy

    이 코드를 실행하면 앞서 만든 함수가 추적 데이터를 내보내는 코드를 추가하는 함수로 바뀌게 됩니다. 강조 표시된 줄은 다음을 수행합니다.

    • telemetry 패키지를 포함하는 snowflake-telemetry-python 을 UDF의 실행 환경에 추가합니다.

    • 함수를 호출할 수 있도록 telemetry 패키지를 가져옵니다.

    • 코드 실행 시 특성과 특성 값을 Snowflake가 만드는 범위로 설정합니다.

      범위는 여러 이벤트를 추가할 수 있는 프로시저 또는 UDF의 실행 단위를 나타냅니다.

    • 범위의 일부로 기록할 이벤트(자체 특성 포함)를 추가합니다.

  3. 다음 문을 붙여넣고 실행하여 방금 만든 함수를 실행합니다.

    SELECT log_trace_data();
    Copy

    그러면 다음 출력이 생성됩니다. 또한 함수가 실행되면서 Snowflake가 이벤트 테이블에 수집한 추적 데이터를 내보냈습니다.

    --------------------
| LOG_TRACE_DATA() |
--------------------
| SUCCESS          |
--------------------

이 섹션에서는 UDF에서 추적 데이터를 내보내 보았습니다. 다음 섹션에서는 이벤트 테이블을 쿼리하여 추적과 관련된 데이터를 검색해 보겠습니다.

추적 메시지의 쿼리

이 섹션에서는 이전 섹션에서 실행한 UDF에서 내보낸 추적 데이터에 대한 이벤트 테이블을 쿼리해 보겠습니다.

참고

처리기 코드에서 내보낸 로그 또는 추적 데이터가 이벤트 테이블에 기록되는 데 몇 초가 걸릴 수 있습니다. 결과가 즉시 표시되지 않으면 몇 초 후에 다시 시도하십시오.

여기서 작성하는 쿼리로 함수에서 내보내는 이벤트에 대한 컨텍스트 정보를 검색하게 됩니다. 해당 컨텍스트에는 이를 내보낸 함수의 이름이 포함됩니다.

추적 데이터에 대한 이벤트 테이블을 쿼리하려면 다음을 수행하십시오.

  1. 다음 문을 붙여넣고 실행하여 추적 데이터의 이벤트 테이블을 쿼리합니다.

    SELECT
  TIMESTAMP AS time,
  RESOURCE_ATTRIBUTES['snow.executable.name'] AS handler_name,
  RECORD['name'] AS event_name,
  RECORD_ATTRIBUTES AS attributes
FROM
  tutorial_log_trace_db.public.tutorial_event_table
WHERE
  RECORD_TYPE = 'SPAN_EVENT'
  AND HANDLER_NAME LIKE 'LOG_TRACE_DATA%';
    Copy

    일부 열에는 키-값 페어로 표현된 정형 데이터가 포함됩니다. 이러한 열에 대해 코드에 나타낸 것처럼 대괄호 표기법 을 사용하여 열 내의 특성 값을 선택할 수 있습니다.

  2. 출력을 확인합니다.

    -----------------------------------------------------------------------------------------------------------------------------------------------------
| TIME                    | HANDLER_NAME                         | EVENT_NAME              | ATTRIBUTES                                             |
-----------------------------------------------------------------------------------------------------------------------------------------------------
| 2023-05-10 20:49:35.080 | "LOG_TRACE_DATA():VARCHAR(16777216)" | "event_with_attributes" | { "example.key1": "value1", "example.key2": "value2" } |
-----------------------------------------------------------------------------------------------------------------------------------------------------

    출력에는 이벤트 테이블의 미리 정의된 열 이 각각 수집된 데이터의 일부를 포함하는 방법이 표시됩니다. EXECUTABLE 및 SEVERITY 값의 경우 대괄호 표기법을 사용하여 원하는 값을 가진 특성을 지정했습니다.

    출력 열

    설명

    TIME

    (TIMESTAMP 열에서) 항목이 생성된 시간입니다.

    HANDLER_NAME

    (RESOURCE_ATTRIBUTES 열의 snow.executable.name 특성에서 가져온) UDF 이름 및 매개 변수입니다.

    EVENT_NAME

    (RECORD 열의 name 특성에서) add_event 함수로 추가된 이벤트의 이름입니다.

    ATTRIBUTES

    (RECORD_ATTRIBUTES 열에서) 이벤트에 수반하도록 추가된 특성입니다.

이 섹션에서는 작성한 UDF에서 내보낸 추적 데이터의 이벤트 테이블을 쿼리해 보았습니다. 마지막 섹션에서는 자습서를 따라 학습하는 동안 수행한 작업과 관련된 정보에 대한 링크를 확인할 수 있습니다.

자세히 알아보기

끝났습니다! 잘하셨습니다.

이 자습서에서는 처리기 코드에서 로그와 추적 데이터를 내보내고 저장한 다음 저장된 데이터를 쿼리하는 방법을 처음부터 끝까지 살펴보았습니다. 그 과정에서 다음 작업을 수행했습니다.

언어: 한국어