QnAMaker 봇에 원격 분석 추가Add telemetry to your QnAMaker bot

적용 대상: SDK v4APPLIES TO: SDK v4

Bot Framework SDK 버전 4.2에 원격 분석 로깅이 추가되었습니다.Telemetry logging was added to version 4.2 of the Bot Framework SDK. 이제 봇 애플리케이션에서 Application Insights 같은 서비스로 이벤트 데이터를 보낼 수 있습니다.This enables bot applications to send event data to telemetry services such as Application Insights. 원격 분석은 가장 많이 사용되는 기능을 보여주고, 원치 않는 동작을 감지하고, 가용성, 성능 및 사용량 정보를 제공함으로써 봇에 대한 인사이트를 제공합니다.Telemetry offers insights into your bot by showing which features are used the most, detects unwanted behavior and offers visibility into availability, performance, and usage.

새로운 두 가지 구성 요소인 TelemetryLoggerMiddlewareQnAMaker 클래스가 QnA Maker 사용 봇에서 원격 분석 로깅을 사용하도록 설정하는 Bot Framework SDK에 추가되었습니다.Two new components were added to the Bot Framework SDK that enable telemetry logging in QnA Maker enabled bots: TelemetryLoggerMiddleware and the QnAMaker class. TelemetryLoggerMiddleware는 메시지를 수신, 전송, 업데이트 또는 삭제할 때마다 기록하는 미들웨어 구성 요소이며, 'QnAMaker' 클래스는 원격 분석 기능을 확장하는 사용자 지정 로깅을 제공합니다.TelemetryLoggerMiddleware is a middleware component that logs every time messages are received, sent, updated, or deleted, and the 'QnAMaker' class provides custom logging that extends telemetry capabilities.

이 문서에서 알아볼 내용은 다음과 같습니다.In this article you will learn about:

  • 봇에서 원격 분석을 연결하는 데 필요한 코드The code required to wire up telemetry in your bot

  • 표준 이벤트 속성을 사용하는 기본 제공 QnA 로깅과 보고서를 사용하도록 설정하는 데 필요한 코드The code required to enable the out-of-the-box QnA logging and reports that use the standard event properties.

  • 광범위한 보고 요구 사항을 적용하도록 SDK의 기본 이벤트 속성 수정 또는 확장Modifying or extending the SDK's default event properties to enable a wide range of reporting needs.

사전 요구 사항Prerequisites

참고

이 문서에서는 원격 분석을 통합하는 데 필요한 단계를 단계별로 수행하여 QnA Maker 샘플 코드를 빌드합니다.This article will build on the QnA Maker sample code by stepping you through the steps required to incorporate telemetry.

QnA Maker 봇에서 원격 분석 연결Wiring up telemetry in your QnA Maker bot

먼저 QnA Maker 샘플 앱으로 시작하고, QnA 서비스를 사용하여 원격 분석을 봇에 통합하는 데 필요한 코드를 추가합니다.We will start with the QnA Maker sample app and add the code required to integrate telemetry into a bot using the QnA service. 그러면 Application Insights에서 요청 추적을 시작할 수 있습니다.This will enable Application Insights to begin tracking requests.

  1. Visual Studio에서 QnA Maker 샘플 앱을 엽니다.Open the QnA Maker sample app in Visual Studio

  2. Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet 패키지 추가Add the Microsoft.Bot.Builder.Integration.ApplicationInsights.Core NuGet package. NuGet 사용에 대한 자세한 내용은 Visual Studio에서 패키지 설치 및 관리를 참조하세요.For more information on using NuGet, see Install and manage packages in Visual Studio:

  3. 다음 명령문을 Startup.cs에 포함합니다.Include the following statements in Startup.cs:

    using Microsoft.ApplicationInsights.Extensibility;
    using Microsoft.Bot.Builder.ApplicationInsights;
    using Microsoft.Bot.Builder.Integration.ApplicationInsights.Core;
    

    참고

    QnA Maker 샘플 코드를 업데이트하여 수행하는 경우 Microsoft.Bot.Builder.Integration.AspNet.Core에 대한 using 문이 이미 QnA Maker 샘플에 있습니다.If you're following along by updating the QnA Maker sample code you will notice that the using statement for Microsoft.Bot.Builder.Integration.AspNet.Core already exists in the QnA Maker sample.

  4. 다음 코드를 Startup.csConfigureServices() 메서드에 추가합니다.Add the following code to the ConfigureServices() method in Startup.cs. 그러면 DI(종속성 주입)를 통해 봇에서 원격 분석 서비스를 사용할 수 있습니다.This makes telemetry services available to your bot via dependency injection (DI):

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        // Create the Bot Framework Adapter with error handling enabled.
        services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
    
        // Add Application Insights services into service collection
        services.AddApplicationInsightsTelemetry();
    
        // Add the standard telemetry client
        services.AddSingleton<IBotTelemetryClient, BotTelemetryClient>();
    
        // Create the telemetry middleware to track conversation events
        services.AddSingleton<TelemetryLoggerMiddleware>();
    
        // Add the telemetry initializer middleware
        services.AddSingleton<IMiddleware, TelemetryInitializerMiddleware>();
    
        // Add telemetry initializer that will set the correlation context for all telemetry items
        services.AddSingleton<ITelemetryInitializer, OperationCorrelationTelemetryInitializer>();
    
        // Add telemetry initializer that sets the user ID and session ID (in addition to other bot-specific properties, such as activity ID)
        services.AddSingleton<ITelemetryInitializer, TelemetryBotIdInitializer>();
        ...
    }
    

    참고

    QnA Maker 샘플 코드를 업데이트하여 수행하는 경우 services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();가 이미 있습니다.If you are following along by updating the QnA Maker sample code you will notice that services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>(); already exists.

  5. ConfigureServices() 메서드에 추가된 미들웨어 코드를 사용하도록 어댑터에 지시합니다.Instruct the adapter to use the middleware code that was added to the ConfigureServices() method. AdapterWithErrorHandler.cs를 열고, IMiddleware middleware를 생성자 매개 변수 목록에 추가합니다.Open AdapterWithErrorHandler.cs and add IMiddleware middleware to the constructors parameter list. Use(middleware); 문을 생성자의 마지막 줄로 추가합니다.Add the Use(middleware); statement as the last line in the contructor:

    public AdapterWithErrorHandler(ICredentialProvider credentialProvider, ILogger<BotFrameworkHttpAdapter> logger, IMiddleware middleware, ConversationState conversationState = null)
            : base(credentialProvider)
    {
        ...
    
        Use(middleware);
    }
    
  6. Application Insights 계측 키를 appsettings.json 파일에 추가합니다.Add the Application Insights instrumentation key in your appsettings.json file. appsettings.json 파일에는 봇에서 실행 중에 사용하는 외부 서비스에 대한 메타데이터가 포함되어 있습니다.The appsettings.json file contains metadata about external services the Bot uses while running. 예를 들어 CosmosDB, Application Insights 및 QnA Maker 서비스 연결 및 메타데이터는 여기에 저장됩니다.For example, CosmosDB, Application Insights and the QnA Maker service connection and metadata is stored there. 다음 형식으로 appsettings.json 파일에 추가해야 합니다.The addition to your appsettings.json file must be in this format:

    {
        "MicrosoftAppId": "",
        "MicrosoftAppPassword": "",
        "QnAKnowledgebaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "QnAEndpointHostName": "https://xxxxxxxx.azurewebsites.net/qnamaker",
        "ApplicationInsights": {
            "InstrumentationKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    }
    

    참고

    • Application Insights 계측 키 를 얻는 방법에 대한 자세한 내용은 Application Insights 키 문서를 참조하세요.Details on getting the Application Insights instrumentation key can be found in the article Application Insights keys.
    • QnA maker 계정이이미 있어야 합니다. 필요한 경우 키 관리 문서에서 QnA 기술 자료 Id, 끝점 키 및 호스트 이름 값을 가져오는 방법에 대 한 정보를 찾을 수 있습니다.You should already have a QnA maker account, if needed you can find information on getting the QnA Knowledgebase Id, Endpoint Key and HostName values in the key management article.

Application Insights를 사용하여 원격 분석을 사용하도록 설정하는 예비 작업이 완료되었습니다.At this point the preliminary work to enable telemetry using Application Insights is done. Bot 에뮬레이터를 사용 하 여 로컬에서 봇을 실행 한 다음 Application Insights로 이동 하 여 응답 시간, 전체 앱 상태 및 일반적인 실행 정보와 같은 기록 되는 내용을 확인할 수 있습니다.You can run your bot locally using the bot Emulator and then go into Application Insights to see what is being logged such as response time, overall app health, and general running information.

활동 이벤트 및 개인 정보 로깅 사용/사용 안 함에 대한 자세한 내용은 봇에 원격 분석 추가를 참조하세요.For information on Enabling / disabling activity event and personal information logging see Add telemetry to your bot

다음으로, QnA Maker 서비스에 원격 분석 기능을 추가하기 위해 포함되어야 하는 항목에 대해 살펴보겠습니다.Next we will see what needs to be included to add telemetry functionality to the QnA Maker service.

QnA Maker 서비스에서 사용량 데이터를 캡처하도록 원격 분석 사용Enabling telemetry to capture usage data from the QnA Maker service

QnA Maker 서비스는 기본 제공 원격 분석 로깅을 사용할 수 있으므로 QnA Maker에서 원격 분석 데이터를 가져오기 위해 수행해야 하는 작업이 거의 없습니다.The QnA Maker service has built-in telemetry logging available so there is very little you need to do to start getting telemetry data from QnA Maker. 먼저 원격 분석 기능을 QnA Maker 코드에 통합하여 기본 제공 원격 분석 로깅을 사용하도록 설정하는 방법을 확인한 다음, 다양한 보고 요구 사항을 충족시키기 위해 기존 이벤트 데이터에 대한 속성을 대체하거나 추가하는 방법을 알아봅니다.First we will see how to incorporate telemetry into the QnA Maker code to enable the built-in telemetry logging, then we will learn how to replace or add additional properties to the existing event data to satisfy a wide range of reporting needs.

기본 QnA 로깅 사용Enabling default QnA logging

  1. IBotTelemetryClient 형식의 private readonly 필드를 QnABot.csQnABot 클래스에 만듭니다.Create a private readonly field of type IBotTelemetryClient in your QnABot class in QnABot.cs:

    public class QnABot : ActivityHandler
        {
            private readonly IBotTelemetryClient _telemetryClient;
            ...
    }
    
  2. IBotTelemetryClient 매개 변수를 QnABot.csQnABot 클래스 생성자에 추가하고, 이전 단계에서 만든 private 필드에 해당 값을 할당합니다.Add an IBotTelemetryClient parameter to your QnABot class constructor in QnABot.cs and assign its value to the private field created in the previous step:

    public QnABot(IConfiguration configuration, ILogger<QnABot> logger, IHttpClientFactory httpClientFactory, IBotTelemetryClient telemetryClient)
    {
        ...
        _telemetryClient = telemetryClient;
    }
    
  3. QnABot.cs에서 새 QnAMaker 개체를 인스턴스화하는 경우 telemetryClient 매개 변수가 필요합니다.The telemetryClient parameter is required when instantiating the new QnAMaker object in QnABot.cs:

    var qnaMaker = new QnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    

    항목에서 사용 하는 속성 이름이 _configuration AppSettings.js파일에 사용한 속성 이름과 일치 하는지 확인 하 고 해당 속성의 값은 QnA Maker 포털의 내 기술 자료 페이지에서 코드 보기 단추를 선택 하 여 가져옵니다.Make sure that the property names that you use in the _configuration entries match the property names you used in the AppSettings.json file and the values for those properties are obtained by selecting the View Code button on the My knowledge bases page in the QnA Maker portal:

    AppSettings

QnA Maker 기본 항목에서 기록된 원격 분석 데이터 보기Viewing Telemetry data logged from the QnA Maker default entries

다음 단계를 수행 하 여 봇 에뮬레이터에서 봇을 실행 한 후 Application Insights에서 QnA Maker bot 사용 결과를 볼 수 있습니다.You can view the results of your QnA Maker bot usage in Application Insights after running your bot in the bot Emulator by taking the following steps :

  1. Azure Portal로 이동Go to the Azure portal

  2. 모니터 > 애플리케이션 을 차례로 클릭하여 Application Insights로 이동합니다.Navigate to your Application Insights by clicking on Monitor > Applications.

  3. Application Insights에 있으면 아래와 같이 탐색 모음에서 로그(분석) 를 클릭합니다.Once in your Application Insights, click on Logs (Analytics) on the navigation bar as shown below:

    Log Analytics

  4. 다음 Kusto 쿼리를 입력한 다음, 실행 을 선택합니다.Enter the following Kusto query and then select Run

    customEvents
    | where name == 'QnaMessage'
    | extend answer = tostring(customDimensions.answer)
    | summarize count() by answer
    
  5. 브라우저에서 이 페이지를 열어 둡니다. 그러면 새 사용자 지정 속성을 추가한 후에 해당 페이지로 돌아갑니다.Leave this page open in your browser, we will come back to it after adding a new custom property.

Azure Monitor에서 로그 쿼리를 작성하는 데 사용되지만 SQL 쿼리 언어에 익숙한 Kusto 쿼리 언어를 처음 사용하는 경우 SQL-Azure Monitor 로그 쿼리 참고 자료 시트가 유용할 수 있습니다.If you are new to the Kusto query language that is used to write log queries in Azure Monitor, but are familiar with SQL query language, you may find the SQL to Azure Monitor log query cheat sheet useful.

기본 이벤트 속성 수정 또는 확장Modifying or extending the default event properties

QnAMaker 클래스에 정의되지 않은 속성이 필요한 경우 이를 처리하는 두 가지 방법이 있으며, 둘 다 QnAMaker 클래스에서 파생되는 고유한 클래스를 만들어야 합니다.If you need properties that are not defined in the QnAMaker class there are two ways of handling this, both require creating your own class derived from the QnAMaker class. 첫 번째 방법은 속성을 기존 QnAMessage 이벤트에 추가하는 아래의 속성 추가 섹션에 설명되어 있습니다.The first is explained in the section below titled Adding properties in which you add properties to the existing QnAMessage event. 두 번째 방법을 사용하면 사용자 지정 속성을 사용하여 새 이벤트 추가에서 설명한 대로 속성을 추가할 수 있는 새 이벤트를 만들 수 있습니다.The second method allows you to create new events to which you can add properties as described in Adding new events with custom properties.

참고

QnAMessage 이벤트는 Bot Framework SDK의 일부이며, Application Insights에 로깅되는 기본 제공 이벤트 속성을 모두 제공합니다.The QnAMessage event is part of the Bot Framework SDK and provides all of the out-of-the-box event properties that are logged to Application Insights.

속성 추가Adding properties

다음은 QnAMaker 클래스에서 파생되는 방법을 보여 줍니다.The following demonstrates how you can derive from the QnAMaker class. 이 예에서는 QnAMessage 이벤트에 "MyImportantProperty" 속성을 추가하는 방법을 보여줍니다.The example shows adding the property "MyImportantProperty" to the QnAMessage event. QnA GetAnswers 호출을 수행할 때마다 QnAMessage 이벤트가 기록됩니다.The QnAMessage event is logged every time a QnA GetAnswers call is performed.

사용자 지정 속성을 추가하는 방법에 대해 알아본 후에는 새 사용자 지정 이벤트를 만들고 속성을 이에 연결하는 방법을 알아본 다음, Bot Framework Emulator를 사용하여 봇을 로컬로 실행하고, Kusto 쿼리 언어를 사용하여 Application Insights에 기록되는 내용을 확인합니다.After learning how to add custom properties we will learn how to create a new custom event and associate properties with it, then we will run the bot locally using the Bot Framework Emulator and see what is being logged in Application Insights using the Kusto query language.

  1. MyQnAMaker라는 새 클래스를 QnAMaker 클래스에서 상속되는 Microsoft.BotBuilderSamples 네임스페이스에 만들고 MyQnAMaker.cs으로 저장합니다.Create a new class named MyQnAMaker in the Microsoft.BotBuilderSamples namespace that inherits from the QnAMaker class and save it as MyQnAMaker.cs. QnAMaker 클래스에서 상속하려면 Microsoft.Bot.Builder.AI.QnA using 문을 추가해야 합니다.In order to inherit from the QnAMaker class you will need to add the Microsoft.Bot.Builder.AI.QnA using statement. 코드는 다음과 같이 표시됩니다.Your code should appear as follows:

    using Microsoft.Bot.Builder.AI.QnA;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
    
        }
    }
    
  2. 클래스 생성자를 MyQnAMaker에 추가합니다.Add a class constructor to MyQnAMaker. System.Net.HttpMicrosoft.Bot.Builder 생성자 매개 변수에 대해 두 개의 추가 using 문이 필요합니다.Note that you will need two additional using statements for the constructors parameters System.Net.Http and Microsoft.Bot.Builder:

    ...
    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    
    namespace Microsoft.BotBuilderSamples
    {
        public class MyQnAMaker : QnAMaker
        {
            public MyQnAMaker(
                QnAMakerEndpoint endpoint,
                QnAMakerOptions options = null,
                HttpClient httpClient = null,
                IBotTelemetryClient telemetryClient = null,
                bool logPersonalInformation = false)
                : base(endpoint, options, httpClient, telemetryClient, logPersonalInformation)
            {
    
            }
        }
    }
    
  3. 새 속성을 생성자 뒤의 QnAMessage 이벤트에 추가하고, System.Collections.Generic, System.ThreadingSystem.Threading.Tasks 문을 포함합니다.Add the new property to the QnAMessage event after the constructor and include the statements System.Collections.Generic, System.Threading, and System.Threading.Tasks:

    using Microsoft.Bot.Builder.AI.QnA;
    using System.Net.Http;
    using Microsoft.Bot.Builder;
    using System.Collections.Generic;
    using System.Threading;
    using System.Threading.Tasks;
    
    namespace Microsoft.BotBuilderSamples
    {
            public class MyQnAMaker : QnAMaker
            {
            ...
    
            protected override async Task OnQnaResultsAsync(
                                QueryResult[] queryResults,
                                Microsoft.Bot.Builder.ITurnContext turnContext,
                                Dictionary<string, string> telemetryProperties = null,
                                Dictionary<string, double> telemetryMetrics = null,
                                CancellationToken cancellationToken = default(CancellationToken))
            {
                var eventData = await FillQnAEventAsync(
                                        queryResults,
                                        turnContext,
                                        telemetryProperties,
                                        telemetryMetrics,
                                        cancellationToken)
                                    .ConfigureAwait(false);
    
                // Add new property
                eventData.Properties.Add("MyImportantProperty", "myImportantValue");
    
                // Log QnAMessage event
                TelemetryClient.TrackEvent(
                                QnATelemetryConstants.QnaMsgEvent,
                                eventData.Properties,
                                eventData.Metrics
                                );
            }
    
        }
    }
    
  4. 새 클래스를 사용하도록 봇을 수정합니다. QnAMaker 개체를 만드는 대신 MyQnAMaker 개체를 QnABot.cs에 만듭니다.Modify your bot to use the new class, instead of creating a QnAMaker object you will create a MyQnAMaker object in QnABot.cs:

    var qnaMaker = new MyQnAMaker(new QnAMakerEndpoint
                {
                    KnowledgeBaseId = _configuration["QnAKnowledgebaseId"],
                    EndpointKey = _configuration["QnAEndpointKey"],
                    Host = _configuration["QnAEndpointHostName"]
                },
                null,
                httpClient,
                _telemetryClient);
    
MyImportantProperty 속성에서 기록된 원격 분석 데이터 보기Viewing telemetry data logged from the new property MyImportantProperty

에뮬레이터에서 봇을 실행 한 후 다음을 수행 하 여 Application Insights 결과를 볼 수 있습니다.After running your bot in the Emulator you can view the results in Application Insights by doing the following:

  1. 로그(분석) 보기가 활성 상태인 브라우저로 다시 전환합니다.Switch back to your browser that has the Logs (Analytics) view active.

  2. 다음 Kusto 쿼리를 입력한 다음, 실행 을 선택합니다.Enter the following Kusto query and then select Run. 그러면 새 속성이 실행된 횟수가 제공됩니다.This will give a count of the number of times the new property was executed:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    | summarize count() by MyImportantProperty
    
  3. 횟수 대신 세부 정보를 표시하려면 마지막 줄을 제거하고 쿼리를 다시 실행합니다.To show details instead of the count remove the last line and re-run the query:

    customEvents
    | where name == 'QnaMessage'
    | extend MyImportantProperty = tostring(customDimensions.MyImportantProperty)
    

사용자 지정 속성을 사용하여 새 이벤트 추가Adding new events with custom properties

데이터를 QnaMessage 이외의 다른 이벤트에 기록해야 하는 경우 고유한 속성을 사용하여 고유한 사용자 지정 이벤트를 만들 수 있습니다.If you need to log data to a different event than QnaMessage, you can create your own custom event with its own properties. 이렇게 하려면 다음과 같이 MyQnAMaker 클래스의 끝에 코드를 추가합니다.To do this, we will add code to the end of the MyQnAMaker class as follows:

public class MyQnAMaker : QnAMaker
{
    ...

    // Create second event.
    var secondEventProperties = new Dictionary<string, string>();

    // Create new property for the second event.
    secondEventProperties.Add(
                        "MyImportantProperty2",
                        "myImportantValue2");

    // Log secondEventProperties event
    TelemetryClient.TrackEvent(
                    "MySecondEvent",
                    secondEventProperties);

}

Application Insights 대시보드The Application Insights dashboard

Azure에서 Application Insights 리소스를 만들 때마다 새 대시보드가 자동으로 만들어지고 리소스와 연결됩니다.Anytime you create an Application Insights resource in Azure, a new dashboard will automatically be created and associated with it. Application Insights 블레이드의 맨 위에 있는 애플리케이션 대시보드 라는 단추를 선택하면 대시보드를 볼 수 있습니다.You can see that dashboard by selecting the button at the top of your Application Insights blade, labeled Application Dashboard.

애플리케이션 대시보드 링크

또는 데이터를 보려면 Azure Portal로 이동합니다.Alternatively, to view the data, go to the Azure portal. 왼쪽에서 대시보드 를 클릭한 다음, 드롭다운에서 원하는 대시보드를 선택합니다.Click Dashboard on the left, then select the dashboard you want from the drop-down.

여기에는 봇 성능에 대한 몇 가지 기본 정보와 해당 대시보드에 고정한 추가 쿼리가 표시됩니다.There you'll see some default information about your bot performance and any additional queries that you've pinned to your dashboard.

추가 정보Additional Information