Skip to main content

About Instance and Event Data

This topic provides an overview of the customer and instance insights that you can view in the Replicated Vendor Portal. It includes information about how the Vendor Portal accesses data as well as requirements and limitations.

How the Vendor Portal Collects Instance Data​

This section describes how the Vendor Portal collects instance data from online and air gap environments.

Online Instances​

For instances running in online (internet-connected) environments, either Replicated KOTS or the Replicated SDK periodically sends a small amount of data to the Vendor Portal, depending on which is installed in the cluster alongside the application. If both KOTS and the SDK are installed in the cluster (such as when a Helm chart that includes the SDK is installed by KOTS), then both send instance data.

The data sent to the Vendor Portal includes properties such as the current version and status of the instance. For a full overview of what data might be included, see the Replicated Data Transmission Policy.

The following diagram shows the flow of different types of data from customer environments to the Vendor Portal:

Telemetry sent from instances to vendor platform

View a larger version of this image

As shown in the diagram above, application instance data, application status data, and details about the KOTS and the SDK instances running in the cluster are all sent to the Vendor Portal through the Replicated app service:

  • When both KOTS and the SDK are installed in the cluster, they both send application instance data, including information about the cluster where the instance is running.
  • KOTS and the SDK both send information about themselves, including the version of KOTS or the SDK running in the cluster.
  • Any custom metrics configured by the software vendor are sent to the Vendor Portal through the Replicated SDK API. For more information, see Configuring Custom Metrics.
  • Application status data, such as if the instance is ready or degraded, is sent by KOTS. If KOTS is not installed in the cluster, then the SDK sends the application status data. For more information, see Enabling and Understanding Application Status.

Air Gap Instances​

For air gap instances, Replicated KOTS and the Replicated SDK collect and store instance telemetry in a Kubernetes Secret in the customer environment. The Replicated SDK also stores any custom metrics within its Secret.

The telemetry and custom metrics stored in the Secret are collected when a support bundle is generated in the environment. When the support bundle is uploaded to the Vendor Portal, the telemetry and custom metrics are associated with the correct customer and instance ID, and the Vendor Portal updates the instance insights and event data accordingly.

For more information, see Collecting Telemetry for Air Gap Instances.

Frequency of Data Sent to the Vendor Portal​

This section describes how frequently data is sent to the Vendor Portal for online and air gap instances.

From the Replicated SDK (Online Instances Only)​

When installed alongside the application in an online environment, the SDK automatically sends instance data to the Vendor Portal when any of the following occur:

  • The SDK sends data every four hours.

  • The instance checks for updates. An update check occurs when the instance makes a request to the /api/v1/app/updates SDK API endpoint. See app in Replicated SDK API (Alpha).

  • The instance completes a Helm update to a new application version. After the update completes, the SDK sends data when it restarts.

  • The status of an instance changes. For example, an instance can change from a Ready to Degraded status. For more information, see Enabling and Understanding Application Status.

From KOTS (Online Instances Only)​

When installed alongisde the application in an online environment, KOTS automatically sends instance data to the Vendor Portal when any of the following occur:

  • The instance checks for updates. By default, KOTS checks for updates every four hours. Additionally, an update check can occur when a user clicks the Check for updates button in the Replicated Admin Console.

    note

    KOTS users can modify or disable automatic update checks from the Admin Console. For more information, see Configuring Automatic Updates.

  • The status of an instance changes. For example, an instance can change from a Ready to Degraded status. For more information, see Enabling and Understanding Application Status.

  • (KOTS v1.92 and later only) The instance deploys a new application version.

From Air Gap Instances​

For air gap instances, the frequency of data sent to the Vendor Portal depends on how frequently support bundles are collected in the customer environment and uploaded to the Vendor Portal.

For more information, see Collecting Telemetry for Air Gap Instances.

How the Vendor Portal Generates Events and Insights​

When the Vendor Portal receives instance data, it evaluates each data field to determine if there was a change in its value. For each field that changes in value, the Vendor Portal creates an event to record the change. For example, a change from Ready to Degraded in the application status generates an event.

In addition to creating events for changes in data sent by the instance, the Vendor Portal also generates events for changes in values of computed metrics. The Vendor Portal updates the values of computed metrics each time it receives instance data. For example, the Vendor Portal computes a Versions behind metric that tracks the number of versions behind the latest available version for the instance. When the instance checks for updates and a new update is available, the value of this metric changes and the Vendor Portal generates an event.

The Vendor Portal uses events to display insights for each active instance in a Instance details dashboard. For more information about using the Vendor Portal Instance details page to monitor active instances of your application, see Instance Details.

Requirements​

The following requirements apply to collecting instance telemetry:

  • Replicated KOTS or the Replicated SDK must be installed in the cluster where the application instance is running.

  • For KOTS installations and for Helm CLI installations that use helm template then kubectl apply, additional configuration is required to get application status data. For more information, see Enabling and Understanding Application Status.

  • To view resource status details for an instance on the Instance details page, the Replicated SDK must be installed in the cluster alongside the application. For more information, see View Resource Status Insights in Enabling and Understanding Application Status.

  • There are additional requirements for collecting telemetry from air gap instances. For more information, see Collecting Telemetry for Air Gap Instances.

Limitations​

The Vendor Portal has the following limitations for reporting instance data and generating events:

  • Active instances: Instance data is available for active instances. An instance is considered inactive when its most recent check-in was more than 24 hours ago. An instance can become inactive if it is decommissioned, stops checking for updates, or otherwise stops reporting.

    The Vendor Portal continues to display data for an inactive instance from its most-recently seen state. This means that data for an inactive instance might continue to show a Ready status after the instance becomes inactive. Replicated recommends that you use the timestamp in the Last Check-in field to understand if an instance might have become inactive, causing its data to be out-of-date.

  • Air gap instances: There are additional limitations for air gap telemetry. For more information, see Collecting Telemetry for Air Gap Instances.

  • Instance data freshness: The rate at which data is updated in the Vendor Portal varies depending on how often the Vendor Portal receives instance data.

  • Event timestamps: The timestamp of events displayed on the Instances details page is the timestamp when the Replicated Vendor API received the data from the instance. The timestamp of events does not necessarily reflect the timestamp of when the event occurred.

  • Caching for kURL cluster data: For clusters created with Replicated kURL (embedded clusters), KOTS stores the counts of total nodes and ready nodes in a cache for five minutes. If KOTS sends instance data to the Vendor Portal within the five minute window, then the reported data for total nodes and ready nodes reflects the data in the cache. This means that events displayed on the Instances details page for the total nodes and ready nodes can show values that differ from the current values of these fields.