botbuilder-applicationinsights
    TypeScript icon, indicating that this package has built-in type declarations

    4.16.0 • Public • Published

    Bot Builder Application Insights

    Application Insights extensions for Microsoft BotBuilder.

    Installing

    To add the latest version of this package to your bot:

    npm install --save botbuilder-applicationinsights

    Use the Daily Build

    To get access to the daily builds of this library, configure npm to use the MyGet feed before installing.

    npm config set registry https://botbuilder.myget.org/F/botbuilder-v4-js-daily/npm/

    To reset the registry in order to get the latest published version, run:

    npm config set registry https://registry.npmjs.org/

    What's Included

    This module contains interfaces to use the Application Insights services to back Bot Builder's metrics and reporting needs.

    Using this module along with the dialog.telemetryClient property will create Waterfall Dialogs that emit Application Insights events for each step of the dialog, and which can automatically be correlated with all other actions taken to fufill an incoming request.

    Use

    Import the module into your app. Make sure to import both the ApplicationInsightsTelemetryClient class and the ApplicationInsightsWebserverMiddleware function. In order to function properly, it is recommended that you import this module as early as possible in your application code -- preferably as the first import.

    const { ApplicationInsightsTelemetryClient, ApplicationInsightsWebserverMiddleware } = require('botbuilder-applicationinsights');

    Create an instance of the ApplicationInsightsTelemetryClient. This requires an Instrumentation Key which can be acquired by creating the Application Insights instance within the Azure portal. This key should be stored in the environment, or in your applications .bot file.

    The resulting appInsightsClient can be used to track events, traces, and other information to Application Insights.

    const appInsightsClient = new ApplicationInsightsTelemetryClient(process.env.instrumentationKey);

    Now, bind the ApplicationInsightsWebserverMiddleware to your webserver. The example below shows this being used with Restify, though this should also work with Express and other webserver modules that follow the Express middleware pattern.

    This middleware will ensure that Application Insights has the appropriate information to correlate activities to the original incoming message, user and session that triggered them.

    let server = restify.createServer();
    server.use(ApplicationInsightsWebserverMiddleware);

    Configure Options

    By default, the botbuilder-applicationinsights is configured to automatically track and correlate data from many parts of your application. If you would like to tune the settings of your client, use the configuration functions documented here as part of the official Application Insights client, but call them from the appInsightsClient.configuration property as seen below:

    // enable application insights to capture console.log output and send it as trace events
    appInsightsClient.configuration.setAutoCollectConsole(true, true);

    Use with Waterfall Dialogs

    As of version 4.2, Waterfall Dialogs included in botbuilder-dialogs can tracked automatically with a properly configured telemetry client. To use Application Insights to track a waterfall dialog, set the dialog.telemetryClient property:

    const myDialog = new WaterfallDialog(DIALOG_ID, array_of_steps);
    myDialog.telemetryClient = appInsightsClient;

    You may also set the telemetryClient field on DialogSet and ComponentDialog objects. Setting the property on these classes will apply it to all contained dialogs automatically.

    Once enabled, expect to see WaterfallStart, WaterfallStep, WaterfallComplete and WaterfallCancel events logged in Application Insights. These custom events will also include the dialog id, a unique instance id for each use of the dialog, and the name of the dialog step.

    Use Directly

    This telemetry client includes access to the common event types used by Application Insights. The signatures for these functions match the official Application Insights client module.

    appInsightsClient.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
    appInsightsClient.trackException({exception: new Error("handled exceptions can be logged with this method")});
    appInsightsClient.trackTrace({message: "trace message"});
    appInsightsClient.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});

    Learn More

    Learn how to build great bots.

    Install

    npm i botbuilder-applicationinsights

    DownloadsWeekly Downloads

    394

    Version

    4.16.0

    License

    MIT

    Unpacked Size

    52.6 kB

    Total Files

    27

    Last publish

    Collaborators

    • botframework
    • joshgummersall
    • sgellock
    • cwhitten