Proposal: telemetry API for Data Center and Server

Disclaimer: this is just a rough proposal

Problem

Vendors want to have an understanding of usage of their apps on self-hosted installations (DC/Server).
Also, vendors would like to receive installation and uninstallation lifecycle events triggered by user (Jira admin) action. This might also help in fighting the trial licence abuse, if sufficient information will be provided.
Many vendors implement DIY reporting with custom opt-in/out logic and policies.
It would benefit the trust of customers if all telemetry data would be gathered via unified solution with ability to review and opt-out it in one place.

Proposed Solution

0. Installation and license metadata

In order to understand which customer is performing the action and associate the usage data with the specific license, such fields are essential:
  • Server ID
  • App license SEN (if applicable or present)
  • Jira license SEN (if allowed by Atlassian)

1. Lifecycle events

This can be implemented (without any additional logic implementation from vendor) within UPM/Marketplace infrastructure.

Event types:

  • Manual disable and enable
  • Install and uninstall
  • (extension of previous) enable/install error, with stack trace if possible. If “silent” implicit reporting is not allowed by Atlassian, it might be implemented as “send crash report” explicit action.

2. Usage metrics

Java API interface with methods to extract metrics from the database. Each app would have a sensible timeframe to collect metrics, if it fails, the request would be interrupred due to time out.

For the most cases, I believe it might be sufficient to have one method that would return Map<String, Long> to represent entity count metrics.

It can be either implemented within new upm-api/licensing-api libraries, or via a separate facet library similar to atlassian-app-cloud-migration-listener for best compatibility.

3. Transportation of telemetry data

Most likely, the telemetry data would be collected on some kind of schedule with sensible default (like once a week on Saturday/Sunday), which might be configurable through telemetry settings interface (4).
Lifecycle events might be accumulated between telemetry reporting scheduled time and sent along with metrics, or be sent on a separate schedule.

Telementry events and metrics would be also enriched with installation metadata described in (0).

In general I see data pipeline as:
[hosted installation] => [Atlassian servers] => [vendor]

The specifics of how vendors might receive the data are laid out in (5).

4. End-user transparency

Jira admins would have a separate page in Admin section to review and configure which apps are sending telemetry data (and what kind of data) with option of complete or partial opt-out.
DC approval process would eventually be updated to allow telemetry only through this API after some transitional period.

5. Vendor API

Generally, there are two choices, either vendors will pull the data via API, or receive the events via secure webhooks to the endpoint that would be specified in marketplace vendor profile.

1 Like

@lexek-92,

We had some community members report a bit of confusion about your post. RFCs are expected to be official from Atlassians. As such, I edited your title just slightly to “Proposal”, which I think the community will understand just fine. Despite the small edit, I appreciate the input and the use of the “problem/solution” format. We’ll make sure the appropriate Atlassians give this some thought.

1 Like

@ibuchanan sorry for confusion :sweat_smile:

It might be worth exploring the possibility of establishing RFC-like process for suggestions from community as well :wink: