Logging

#Introduction

This page is written to give you an overview of our logging infrastructure, as well as a transparent view of our telemetry and reporting. Like many other software applications, logging in the Web Clipper is essential for debugging, surfacing issues, and highlighting usage statistics.

We group usages of the Web Clipper into sessions - the interaction between a single user and the Web Clipper within a single tab. Sessions provide an easy way to group user actions, events, and failures in a well-defined manner. Sessions start when an extension worker is constructed in response to the start of the interaction between the user and the Web Clipper in a tab. More information about the extension worker can be found in the Extension page.

Typically, an extension worker is created when the user invokes the Web Clipper. Sessions may also start when the extension initiates an interaction with the user. For example, when the Web Clipper is updated and change logs are shown to the user in the current page. Sessions end when the user signs out or navigates away from the current page.

A common example of a full session would be a user invoking the Web Clipper on a page, signing in, clipping, then finally navigating away from the current page.

#Telemetry

Due to the closed-source nature of our telemetry library, we are unable to include it in this repository, and you will find that there are references in our build script that pull in these files during our internal build process. You are able to opt out of Microsoft's telemetry by simply building this project locally, as the telemetry library lives in a separate, private repository.

Additionally, by enabling console logging on the production-version Web Clipper (i.e., the extension downloaded from browser-specific stores), you will be able to see the events and their properties being logged to our telemetry endpoint in full transparency.

Finally, while we are able to tie logging events back to the sessions they belong to, sessions are unable to be tied to a specific user and we wish to maintain the privacy of our users. Events sent to our telemetry endpoint are used strictly for debugging, generating usage statistics, and driving decisions for feature prioritization.

If you have any suggestions, questions, or concerns regarding our logging and telemetry, feel free to contact us at [email protected]

#Architecture

A visual overview of the Web Clipper's architecture is shown below. More information can be found in the Extension page.

All logging is centralized in the extension worker, meaning all calls to logging functions in the inject or UI scripts are piped back to the extension worker where the actual logging (i.e., calls to Microsoft's telemetry endpoint) takes place. Note that this is opposite to the flow of instantiation seen in the above diagram.

#Log Events

A session is composed of a sequence of log events, such as (but is not limited to) user events (e.g., clicks, selections) and API calls (e.g., POSTing the clipped page to OneNote). Each log event is a set of key-value pairs, where each key is either a context property or a custom property. We will refer to these as event objects.

##Context Properties

Context properties refer to key-value pairs that are present on every event object in a given session (if available). A simple example of this would be the key Session.Id, which allows every event to be tied back to the session it belongs to.

Some of these context properties are required. Events will not be logged until all required context properties are set. Events that are logged when not all required context properties are set are placed on a queue until all the required context properties are set, at which point they will be dequeued and logged.

##Custom Properties

Custom properties refer to event object properties that are not context properties, and are typically specific to the event or event category that is being logged. For example, the FoundDefaultNotebook property makes far more sense on the event that traverses the notebook list for a default notebook as opposed to the event that records a sign-in attempt.

#Console logging

As a developer, you might find it useful to output the logs to the console as it allows you to:

• Debug changes that you make to the Web Clipper
• View exactly what is being sent to Microsoft through telemetry

To do this, add the following key-value pair to the extension's local storage (the exact steps will vary from browser to browser):

enable_console_logging = true

To turn this feature off, either remove the key-value entry, or set the value to false.

In subsequent Web Clipper interactions, the extension will inject a console logging script. Logging calls that are executed in the extension worker will also be redirected to this inject script where console logging will be performed in the user's tab.