TripPin 8부 - 진단 추가

아티클
05/17/2024

참고 항목

이 콘텐츠는 현재 Visual Studio에서 진단 위해 레거시 구현의 콘텐츠를 참조합니다. Visual Studio Code의 새 파워 쿼리 SDK를 포함하도록 콘텐츠가 곧 업데이트될 예정입니다.

이 다중 파트 자습서에서는 파워 쿼리에 대한 새 데이터 원본 확장의 생성에 대해 설명합니다. 이 자습서는 순차적으로 수행됩니다. 각 단원은 이전 단원에서 만든 커넥터를 기반으로 하여 커넥터에 새 기능을 증분 방식으로 추가합니다.

이 단원에서는 다음을 수행합니다.

Diagnostics.Trace 함수에 대해 알아보기
진단 도우미 함수를 사용하여 커넥터 디버그에 도움이 되는 추적 정보 추가

진단 사용

파워 쿼리 사용자는 옵션 | 아래에서 검사 상자를 선택하여 추적 로깅을 사용하도록 설정할 수 있습니다. 진단.

파워 쿼리에서 추적을 사용하도록 설정합니다.

사용하도록 설정하면 후속 쿼리로 인해 M 엔진이 고정 사용자 디렉터리에 있는 로그 파일에 추적 정보를 내보냅니다.

파워 쿼리 SDK 내에서 M 쿼리를 실행하는 경우 프로젝트 수준에서 추적을 사용하도록 설정됩니다. 프로젝트 속성 페이지에는 추적과 관련된 세 가지 설정이 있습니다.

로그 지우기 - 로그가 설정 true되면 쿼리를 실행할 때 로그가 다시 설정/지워집니다. 이 집합 true을 으로 유지하는 것이 좋습니다.
엔진 추적 표시 - 이 설정은 M 엔진에서 기본 제공 추적의 출력을 제어합니다. 이러한 추적은 파워 쿼리 팀의 구성원에게만 유용하므로 일반적으로 이 집합을 유지하려고 합니다 false.
사용자 추적 표시 - 이 설정은 커넥터의 추적 정보 출력을 제어합니다. 이 값을 .로 설정할 수 있습니다 true.

프로젝트 속성입니다.

사용하도록 설정하면 로그 탭 아래의 M 쿼리 출력 창에 로그 항목이 표시되기 시작합니다.

Diagnostics.Trace

Diagnostics.Trace 함수는 M 엔진의 추적 로그에 메시지를 쓰는 데 사용됩니다.

Diagnostics.Trace = (traceLevel as number, message as text, value as any, optional delayed as nullable logical as any) => ...

Important

M은 지연 평가가 있는 기능 언어입니다. 사용할 Diagnostics.Trace때 함수는 함수의 일부인 식이 실제로 평가되는 경우에만 호출됩니다. 이 예제는 이 자습서의 뒷부분에서 찾을 수 있습니다.

매개 변수는 traceLevel 다음 값 중 하나일 수 있습니다(내림차순).

TraceLevel.Critical
TraceLevel.Error
TraceLevel.Warning
TraceLevel.Information
TraceLevel.Verbose

추적을 사용하도록 설정하면 사용자는 보려는 메시지의 최대 수준을 선택할 수 있습니다. 이 수준 이하의 모든 추적 메시지는 로그에 출력됩니다. 예를 들어 사용자가 "경고" 수준을 선택하면 , TraceLevel.ErrorTraceLevel.Critical 의 TraceLevel.Warning추적 메시지가 로그에 표시됩니다.

message 매개 변수는 추적 파일에 출력될 실제 텍스트입니다. 텍스트에 명시적으로 포함하지 않는 한 텍스트에는 매개 변수가 포함되지 value 않습니다.

value 매개 변수는 함수가 반환하는 값입니다. 매개 변수가 delayed 설정된 truevalue 경우 평가 중인 실제 값을 반환하는 0 매개 변수 함수가 됩니다. delayed 로 설정 falsevalue 되면 실제 값이 됩니다. 이 작동 방식의 예는 아래에서 확인할 수 있습니다.

진단 사용. TripPin 커넥터에서 추적

Diagnostics.Trace 및 매개 변수의 delayed 영향을 사용하는 실용적인 예제를 보려면 TripPin 커넥터의 GetSchemaForEntity 함수를 업데이트하여 예외를 래핑합니다error.

GetSchemaForEntity = (entity as text) as type =>
    try
        SchemaTable{[Entity=entity]}[Type]
    otherwise
        let
            message = Text.Format("Couldn't find entity: '#{0}'", {entity})
        in
            Diagnostics.Trace(TraceLevel.Error, message, () => error message, true);

잘못된 엔터티 이름을 함수에 전달하여 평가 중에(테스트 목적으로!) 오류를 적용할 GetEntity 수 있습니다. 여기서 함수의 withData 줄을 변경하고 TripPinNavTable .[Name] "DoesNotExist"

TripPinNavTable = (url as text) as table =>
    let
        // Use our schema table as the source of top level items in the navigation tree
        entities = Table.SelectColumns(SchemaTable, {"Entity"}),
        rename = Table.RenameColumns(entities, {{"Entity", "Name"}}),
        // Add Data as a calculated column
        withData = Table.AddColumn(rename, "Data", each GetEntity(url, "DoesNotExist"), type table),
        // Add ItemKind and ItemName as fixed text values
        withItemKind = Table.AddColumn(withData, "ItemKind", each "Table", type text),
        withItemName = Table.AddColumn(withItemKind, "ItemName", each "Table", type text),
        // Indicate that the node should not be expandable
        withIsLeaf = Table.AddColumn(withItemName, "IsLeaf", each true, type logical),
        // Generate the nav table
        navTable = Table.ToNavigationTable(withIsLeaf, {"Name"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        navTable;

프로젝트에 대해 추적을 사용하도록 설정하고 테스트 쿼리를 실행합니다. 탭에 Errors 발생한 오류의 텍스트가 표시됩니다.

오류 메시지입니다.

또한 탭에 Log 동일한 메시지가 표시됩니다. 매개 변수 및 value 매개 변수에 message 서로 다른 값을 사용하는 경우 서로 다릅니다.

오류 로그입니다.

Action 또한 로그 메시지의 필드에는 확장명(이 경우Engine/Extension/TripPin)의 이름(데이터 원본 종류)이 포함됩니다. 이렇게 하면 관련된 쿼리 및/또는 시스템(매시업 엔진) 추적이 사용하도록 설정된 경우 확장과 관련된 메시지를 더 쉽게 찾을 수 있습니다.

평가 지연

매개 변수가 delayed 작동하는 방식의 예로 몇 가지 수정을 수행하고 쿼리를 다시 실행합니다.

먼저 값을 falsedelayed로 설정하지만 매개 변수는 value 그대로 둡니다.

Diagnostics.Trace(TraceLevel.Error, message, () => error message, false);

쿼리를 실행하면 발생한 실제 오류가 아니라 "함수 형식의 값을 형식 형식으로 변환할 수 없습니다"라는 오류가 표시됩니다. 이는 호출이 이제 값 자체가 아닌 값을 반환하기 function 때문입니다.

다음으로 매개 변수에서 함수를 제거합니다 value .

Diagnostics.Trace(TraceLevel.Error, message, error message, false);

쿼리를 실행하면 올바른 오류가 표시되지만 로그 탭을 검사 경우 메시지가 없습니다. 이는 error 호출 Diagnostics.Trace중에 발생/평가되기 때문에 메시지가 실제로 출력되지 않습니다.

매개 변수의 delayed 영향을 이해했으므로 계속하기 전에 커넥터를 다시 작업 상태로 다시 설정해야 합니다.

Diagnostics.pqm의 진단 도우미 함수

이 프로젝트에 포함된 Diagnostics.pqm 파일에는 추적을 더 쉽게 만드는 많은 도우미 함수가 포함되어 있습니다. 이전 자습서에서와 같이 이 파일을 프로젝트에 포함할 수 있습니다(빌드 동작을 컴파일로 설정하기 위해 기억함). 그런 다음 커넥터 파일에 로드할 수 있습니다. 이제 커넥터 파일의 아래쪽이 아래 코드 조각과 같이 표시됩니다. 이 모듈에서 제공하는 다양한 함수를 자유롭게 탐색할 수 있지만 이 샘플에서는 함수와 Diagnostics.LogFailure 함수만 사용합니다Diagnostics.LogValue.

// Diagnostics module contains multiple functions. We can take the ones we need.
Diagnostics = Extension.LoadFunction("Diagnostics.pqm");
Diagnostics.LogValue = Diagnostics[LogValue];
Diagnostics.LogFailure = Diagnostics[LogFailure];

Diagnostics.LogValue

함수 Diagnostics.LogValue 는 매우 유사 Diagnostics.Trace하며 평가 중인 값의 출력에 사용할 수 있습니다.

Diagnostics.LogValue = (prefix as text, value as any) as any => ...

prefix 매개 변수 앞에 로그 메시지가 추가됩니다. 이를 사용하여 메시지를 출력하는 호출을 파악합니다. 매개 변수는 value 함수가 반환하는 값이며 M 값의 텍스트 표현으로 추적에 기록됩니다. 예를 들어 A 및 B 열이 있는 table 것과 같으면 value 로그에 해당하는 #table 표현이 포함됩니다.#table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

참고 항목

M 값을 텍스트로 직렬화하는 작업은 비용이 많이 들 수 있습니다. 추적에 출력하는 값의 잠재적 크기를 알고 있어야 합니다.

참고 항목

대부분의 파워 쿼리 환경은 추적 메시지를 최대 길이로 자립니다.

예를 들어 함수에 TripPin.Feed 전달된 인수와 schema 인수를 url 추적하도록 함수를 업데이트합니다.

TripPin.Feed = (url as text, optional schema as type) as table =>
    let
        _url = Diagnostics.LogValue("Accessing url", url),
        _schema = Diagnostics.LogValue("Schema type", schema),
        //result = GetAllPagesByNextLink(url, schema)
        result = GetAllPagesByNextLink(_url, _schema)
    in
        result;

호출에서 새 _url 값과 _schema 값을 사용해야 합니다 GetAllPagesByNextLink. 원래 함수 매개 변수를 사용한 경우 호출은 Diagnostics.LogValue 실제로 평가되지 않으며 추적에 기록된 메시지가 없습니다. 기능 프로그래밍은 재미있다!

쿼리를 실행할 때 이제 로그에 새 메시지가 표시됩니다.

액세스 URL:

URL 메시지에 액세스합니다.

스키마 유형:

스키마 유형 메시지입니다.

형식 값에 대해 간단한 Text.FromValue 작업을 수행할 때 얻을 수 있는 것이 아니라 매개 변수type의 schema 직렬화된 버전이 표시됩니다("type"으로 표시됨).

Diagnostics.LogFailure

함수는 Diagnostics.LogFailure 함수 호출을 래핑하는 데 사용할 수 있으며 함수 호출이 실패하는 경우에만 추적에 씁니다(즉, 반환 error).

Diagnostics.LogFailure = (text as text, function as function) as any => ...

내부적으로 Diagnostics.LogFailure 호출에 연산자를 try function 추가합니다. 호출이 실패 text 하면 원래 error값을 반환하기 전에 해당 값이 추적에 기록됩니다. 호출이 function 성공하면 추적에 아무 것도 쓰지 않고 결과가 반환됩니다. M 오류에는 전체 스택 추적이 포함되지 않으므로(일반적으로 오류 메시지만 표시됨) 오류가 발생한 위치를 정확히 파악하려는 경우에 유용할 수 있습니다.

(불량) 예제로 함수 줄을 TripPinNavTable 수정 withData 하여 오류를 다시 한 번 적용합니다.

withData = Table.AddColumn(rename, "Data", each Diagnostics.LogFailure("Error in GetEntity", () => GetEntity(url, "DoesNotExist")), type table),

추적에서 사용자 및 원래 오류 정보가 포함된 text결과 오류 메시지를 찾을 수 있습니다.

LogFailure 메시지입니다.

다음 자습서를 진행하기 전에 함수를 작업 상태로 다시 설정해야 합니다.

결론

이 간략한(중요!) 단원에서는 진단 도우미 함수를 사용하여 파워 쿼리 추적 파일에 로그하는 방법을 보여 주었습니다. 제대로 사용되는 경우 이러한 함수는 커넥터 내에서 문제를 디버깅하는 데 유용합니다.

참고 항목

커넥터 개발자는 진단 로깅의 일부로 중요한 PII(개인 식별 정보)를 기록하지 않도록 해야 합니다. 또한 성능에 부정적인 영향을 미칠 수 있으므로 너무 많은 추적 정보를 출력하지 않도록 주의해야 합니다.

다음 단계

TripPin 9부 - 테스트커넥트ion

다음을 통해 공유

TripPin 8부 - 진단 추가

진단 사용

Diagnostics.Trace

진단 사용. TripPin 커넥터에서 추적

평가 지연

Diagnostics.pqm의 진단 도우미 함수

Diagnostics.LogValue

Diagnostics.LogFailure

결론

다음 단계

피드백

추가 리소스