Telemetry

Overview

The term telemetry refers to the collection of certain usage data to help improve the quality of a piece of software. Dendron uses telemetry primarily for collecting usage data.

This page describes the overall telemetry approach for Dendron, what kind of data is collected and how to opt-out of data collection.

Why does Dendron collect metrics?

Telemetry helps us better understand how many users are using our products and how often they are using our products. Unlike many telemetry services, our telemetry implementation is intentionally limited in scope.

We use telemetry to answer the following questions:

  • how many people are actively using Dendron?
  • how performant is Dendron over time and how do new changes impact performance?
  • what features are most useful for users?
  • what exceptions and errors are users encountering?

What is not collected

Dendron will never collect data inside your notes. We believe that your personal knowledge is for your eyes alone.

What is collected

The below is a collection of common fields that are collected

FieldAttributesDescription
appstringCurrently installed version of the product (e.g. 1.0.0-rc0)
ideVersionstringCurrently installed version of the IDE (e.g. 1.0.0-rc0)
userAgentstringThe specific IDE in question(e.g. VSCodium)
archstringClient's operating system architecture (e.g. amd64).
osstringClient's operating system (e.g. darwin).
nodeVersionstringClient's node version (e.g. v12.12.0).
anonymousIdstringRandom, non-identifiable signature nanoID (e.g. JC6NXxDa0lDFD1Mu7U2Ga)
timestampstringWhen the request was made
appVersionstringVersion of currently installed Dendron plugin
cliVersionstringVersion of currently installed dendron-cli

When is data collected?

Data is collected in scenarios that are described below.

Startup

When Dendron initializes, we collect data about on initialization time. This helps us measure the performance impact of changes that run before startup as well as improvements to our indexing performance over time.

FieldAttributesDescription
durationnumberNumber of seconds for startup
numNotesnumberNumber of notes across all vaults (rounded to the nearest 10 notes)
numVaultsnumberNumber of vaults in workspace
noCachingbooleanCheck whether caching is disabled
workspaceTypestringThe type of Dendron workspace.
codeWorkspacePresentbooleanWhether a dendron.code-workspace file was present

Configuration

When Dendron initializes, we collect data about how Dendron is configured. This helps us figure out the number of users who are actively using a legacy (deprecated or scheduled to be deprecated) configuration to better understand the impact of configuration changes.

FieldAttributesDescription
keystringKey of the configuration that has not been migrated yet.

Migration

In addition to the above field, we track the result of configuration migrations. This helps us make sure deprecating old configurations and introducing new configurations work seamlessly.

FieldAttributesDescription
versionstringMigration version (e.g. "0.63.0")
changeNamestringMigration name (e.g. "v63-command-migration")
status"ok""error"
dendronConfigstringSnapshot of dendron.yml after migration
wsConfigstringSnapshot of dendron.code-workspace after migration

Tutorial Progression

When Dendron starts for the first time, it launches users into a tutorial workflow. We track how far along the tutorial you get using the Tutorial_{num}_Show event. This helps us figure out how effective our intro documentation is.

User Survey

We ask users if they want to answer survey questions that would help use improve Dendron. These surveys are prompted when the user first initializes the tutorial, or has been inactive for a month after actively using Dendron on their first week, or has never initialized a workspace after install.

We use the results to customize the onboarding experience and help users get started. We track if the user accepted the prompt, and what answer they gave for the survey. For each survey question, the following fields are collected.

FieldAttributesDescription
resultsstring[]List of selected survey answers
otherotherUser submitted answer when they selected other

Installation/Upgrade/Uninstall

When Dendron is first installed or upgraded, we collect information about both previous and current versions. This helps us plan deprecation policies.

FieldAttributesDescription
previousVersionstringPrevious version of Dendron
durationnumberNumber of seconds for startup

Lookup

When lookup is performed, Dendron collects profiling information for different phases of lookup. This helps us measure the performance impact of optimizations and features we add to lookup.

Events

  • Lookup Show: when lookup is presented
  • Lookup Update: when lookup items are updated
  • Lookup Accept: when a result from lookup is accepted
FieldAttributesDescription
flavorstringWhat kind of lookup ("schema" or "note")
errorbooleanDid an error happen during this phase?
sourcestringWhat initiated the lookup? ("onValueChange", "updatePickerBehavior:journal", etc )
createNewNotebooleanWas a new note created during this phase?

Commands

We collect an invocation metric when a commands is invoked. This is to measure command latency as well as detect errors in existing and new commands

FieldAttributesDescription
errorbooleanDid an error happen during this phase?
durationnumberHow long did it take to execute this command

For commands that utilze the core lookup module, we additionally collect the state of the lookup modifiers when the user accepts as well as on manual button triggers.

FieldAttributesDescription
commandstringWhat is the invoked command?
typestringWhat button was toggled?
pressedbooleanWhat is the state of the button after toggle?

CLI commands

We collect an invocation metric when a CLI command is invoked. This is to measure command latency. We also collect command arguments that do not contain user-identifying information to analyze usage frequency of a particular command argument

FieldAttributesDescription
durationnumberHow long did it take to execute this command
argsobjectWhat arguments were passed to the command (user-identifying properties omitted)

CLI command arguments

This is an exhaustive list of CLI command arguments collected on invocation.

CommandFieldAttributesDescription
devcmdstringWhat dev command was used (e.g. run_migration, build)
doctoractionstringWhat doctor action was used (e.g. fixFrontmatter, h1ToH2)
importPodpodIdstringWhat pod was used (e.g. dendron.json, markdown)
exportPodpodIdstringWhat pod was used (e.g. dendron.json, markdown)
publishPodpodIdstringWhat pod was used (e.g. dendron.json, markdown)
notecmdstringWhat note command was used (e.g. lookup, delete)
noteoutputstringWhat output format was used (e.g. json, md_gfm, md_dendron)
publishcmdstringWhat publish command was used (e.g. init, build)
seedcmdstringWhat seed command was used (e.g. init, add)
seedidstringWhat seed id was used
seedmodestringWhat seed mode was used (e.g. create_workspace, convert_workspace)
vaultcmdstringWhat vault command was used (e.g. create)
workspaceactionstringWhat workspace action was used (e.g. init, push, pull)

Contextual UI

We collect an invocation metric when a commands is invoked through Contextual UI. This helps us to measure the visibility and effectiveness of Contextual UI.

Errors

Whenever a crash happens or an unexpected error, we collect information surrounding the error to help us diagnose the problem and fix it. For more information, see Error Reporting (Private).

FieldAttributesDescription
ctxnumberWhat happened right before the error occurred?
messagestringThe error message itself
payloadstringPayload with diagnostics information such as exception call stacks, exception severity, and HTTP error codes.

Other

These are groupings of other metrics we collect. We collect them to gather performance impact and improvements across various features.

Events

  • TreeView Ready: measures when the web ui based TreeView is finished loading
FieldAttributesDescription
durationnumberHow long it takes for the tree view to be initialized

Telemetry Toggle

When telemetry is disabled or enabled, we collect information about the event to let us get an estimate of the number of untracked clients

FieldAttributesDescription
reasonenumWhy telemetry was disabled. See values here

How to opt out of data collection

If you've disabled telemetry from the Visual Studio Code Telemetry setting, no further action is needed. You can set this option in your workspace settings, or user settings.

To disable telemetry in Dendron specifically, run the Disable Telemetry command. You can also disable telemetry using the cli by using the disable_telemetry (Private) command.

Why not have opt-in telemetry?

The goal of telemetry is to make data driven decisions about features and use cases that can make the most difference to our users.

One way we could collect data is to conduct surveys but traditionally, these had very low participation and are also biased towards users that are already active in our community. Having telemetry allows us to collect feedback from our larger user base and avoids this bias.

Opt-in telemetry, at best, gives us a narrow and biased set of users. At this point, we are back to make decisions based on limited data. Opt-out telemetry that is limited in scope is the tradeoff we made in terms of preserving user privacy while still gathering meaningful data that can help improve the product.