Skip to main content

Instance Details

This topic describes using the Replicated Vendor Portal to quickly understand the recent events and performance of application instances installed in your customers' environments.

About the Instance Details Page

The Vendor Portal provides insights about the health, status, and performance of the active application instances associated with each customer license on the Instance details page. You can use the insights on the Instance details page to more quickly troubleshoot issues with your customers' active instances, helping to reduce support burden.

For example, you can use the Instance details page to track the following events for each instance:

  • Recent performance degradation or downtime
  • Length of instance downtime
  • Recent changes to the cluster or infrastructure
  • Changes in the number of nodes, such as nodes lost or added
  • Changes in the cluster's Kubernetes version
  • Changes in the application version that the instance is running

To access the Instance details page, go to Customers and click the Customer reporting button for the customer that you want to view:

Customer reporting button on the Customers page

From the Reporting page for the selected customer, click the View details button for the desired application instance.

The following shows an example of the Instance details page:

Instance details full page

View a larger version of this image

As shown in the image above, the Instance details page includes the following sections:

  • Current State: Information about the state of the instance, such as the current application version. See Current State below.
  • Instance Insights: Key performance indicators (KPIs) related to health, performance, and adoption. See Insights below.
  • Instance Information: Information about the cluster where the instance is installed, such as the version of Kubernetes running on the cluster. See Instance Information below.
  • Custom Metrics: The values for any custom metrics that are configured for the application, from the most recent check-in. For more information about configuring custom metrics, see Configuring Custom Metrics.
  • Instance Uptime: Details about instance uptime over time. See Instance Uptime below.
  • Instance Activity: Event data stream. See Instance Activity below.

Current State

The Current State section displays the following event data about the status and version of the instance:

  • App status: The status of the application. Possible statuses are Ready, Updating, Degraded, Unavailable, and Missing. For more information about enabling application status insights and how to interpret the different statuses, see Enabling and Understanding Application Status.

    Additionally, for applications that include the Replicated SDK, you can hover over the App status field to view the statuses of the indiviudal resources deployed by the application, as shown in the example below:

    resource status pop up

    View a larger version of this image

  • App version: The version label of the currently running release. You define the version label in the release properties when you promote the release. For more information about defining release properties, see Properties in About Channels and Releases.

    If there is no version label for the release, then the Vendor Portal displays the release sequence in the App version field. You can find the sequence number associated with a release by running the replicated release ls command. See release ls in the Replicated CLI documentation.

  • Version age: The absolute and relative ages of the instance:

    • Absolute age: now - current_release.promoted_date

      The number of days since the currently running application version was promoted to the channel. For example, if the instance is currently running version 1.0.0, and version 1.0.0 was promoted to the channel 30 days ago, then the absolute age is 30.

    • Relative age (Days Behind Latest): channel.latest_release.promoted_date - current_release.promoted_date

      The number of days between when the currently running application version was promoted to the channel and when the latest available version on the channel was promoted.

      For example, the instance is currently running version 1.0.0, which was promoted to the Stable channel. The latest version available on the Stable channel is 1.5.0. If 1.0.0 was promoted 30 days ago and 1.5.0 was promoted 10 days ago, then the relative age of the application instance is 20 days.

  • Versions behind: The number of versions between the currently running version and the latest version available on the channel where the instance is assigned.

    For example, the instance is currently running version 1.0.0, which was promoted to the Stable channel. If the later versions 1.1.0, 1.2.0, 1.3.0, 1.4.0, and 1.5.0 were also promoted to the Stable channel, then the instance is five versions behind.

  • Last check-in: The timestamp when the instance most recently sent data to the Vendor Portal.

Instance Insights

The Insights section includes the following metrics computed by the Vendor Portal:

Uptime

The Vendor Portal computes the total uptime for the instance as the fraction of time that the instance spends with a Ready, Updating, or Degraded status. The Vendor Portal also provides more granular details about uptime in the Instance Uptime graph. See Instance Uptime below.

High uptime indicates that the application is reliable and able to handle the demands of the customer environment. Low uptime might indicate that the application is prone to errors or failures. By measuring the total uptime, you can better understand the performance of your application.

The following table lists the application statuses that are associated with an Up or Down state in the total uptime calculation:

Uptime StateApplication Statuses
UpReady, Updating, or Degraded
DownMissing or Unavailable
note

The Vendor Portal includes time spent in a Degraded status in the total uptime for an instance because an app may still be capable of serving traffic when some subset of desired replicas are available. Further, it is possible that a Degraded state is expected during upgrade.

Time to Install

The Vendor Portal computes both License time to install and Instance time to install metrics to represent how quickly the customer was able to deploy the application to a Ready state in their environment.

Replicated recommends that you use Time to Install as an indicator of the quality of the packaging, configuration, and documentation of your application.

If the installation process for your application is challenging, poorly documented, lacks appropriate preflight checks, or relies heavily on manual steps, then it can take days or weeks to deploy the application in customer environments. A longer Time to Install generally represents a significantly increased support burden and a degraded customer installation experience.

The following describes the License time to install and Instance time to install metrics:

  • License time to install: The time between when you create the customer license in the Vendor Portal, and when the application instance reaches a Ready status in the customer environment.

    License time to install represents the time that it takes for a customer to successfully deploy your application after you intend to distribute the application to the customer. Replicated uses the timestamp of when you create the customer license in the Vendor Portal to represent your intent to distribute the application because creating the license file is generally the final step before you share the installation materials with the customer.

    License time to install includes several activities that are involved in deploying the application, including the customer receiving the necessary materials and documentation, downloading the assets, provisioning the required hardware, networking, external systems, completing the preflight checks, and finally installing, configuring, and deploying the application.

  • Instance time to install: The time between when the Vendor Portal records the first event for the application instance in the customer environment, and when the instance reaches a Ready status.

    Instance time to install is the length of time that it takes for the application to reach a Ready state after the customer starts a deployment attempt in their environment. Replicated considers a deployment attempt started when the Vendor Portal first records an event for the instance.

    For more information about how the Vendor Portal generates events, see About Events in Event Data.

    note

    Instance time to install does not include any deployment attempts that a customer might have made that did not generate an event. For example, time spent by the customer discarding the server used in a failed attempt before attempting to deploy the instance again on a new server.

Instance Information

The Instance Information section displays the following details about the cluster infrastructure where the application is installed as well as vendor-defined metadata about the instance:

  • The Kubernetes distribution for the cluster. For example, GKE or EKS.
  • The version of Kubernetes running in the cluster.
  • The version of KOTS or the Replicated SDK installed in the cluster.
  • For First Seen, the timestamp of the first event that the Vendor Portal generated for the instance. For more information about how the Vendor Portal generates events, see About Events in Event Data.
  • If detected, the cloud provider and region where the cluster is running. For example, GCP: us-central1.
  • An optional vendor-defined name for the instance.
  • Optional vendor-defined instance tags in the form of key-value pairs. Each instance can have a maximum of 10 tags.

In addition to the details listed above, the Instance Information section also displays the following for embedded clusters provisioned by Replicated kURL:

  • Node operating systems
  • Node operating systems versions
  • Total number of cluster nodes
  • Number of cluster nodes in a Ready state
  • ID of the Kubernetes installer specification

Instance Uptime

The Instance Uptime graph shows the percentage of a given time period that the instance was in an Up, Degraded, or Down state.

To determine if the instance is Up, Degraded, or Down, the Vendor Portal uses the application status. Possible application statuses are Ready, Updating, Degraded, Unavailable, and Missing. The following table lists the application statuses that are associated with each state in the Instance Uptime graph:

Uptime StateApplication Statuses
UpReady or Updating
DegradedDegraded
DownMissing or Unavailable

The following shows an example of an Instance Uptime graph:

Uptime Graph on the Instance details page

You can hover over the bars in the Instance Uptime graph to view more detail about the percent of time that the instance was in each state during the given time period.

Uptime Graph with event markers on the Instance details page

You can hover over the event markers in the Instance Uptime graph to view more detail about the events that occurred during that given interval on the graph. If more than two events occurred in that period, the event marker displays the number of events that occurred during that period. If you click the event marker or the event in the tooltip, the Instance Activity section highlights the event or the first event in the group.

Instance Activity

The Instance Activity section displays recent events for the instance. The data stream is updated each time an instance check-in occurs. For more information about what triggers an instance check-in, see How the Vendor Portal Collects Instance Data in About Instance and Event Data.

The timestamp of events displayed in the Instance Activity stream is the timestamp when the Replicated Vendor API received data from the instance. The timestamp of events does not necessarily reflect the timestamp of when the event occurred.

The following shows an example of the Instance Activity data stream:

Instance Activity section of Instance details page

You can filter the Instance Activity stream by the following categories:

The following tables describe the events that can be displayed in the Instance Activity stream for each of the categories above:

App install/upgrade

LabelDescription
App ChannelThe ID of the channel the application instance is assigned.
App VersionThe version label of the release that the instance is currently running. The version label is the version that you assigned to the release when promoting it to a channel.

App status

LabelDescription
App Status

A string that represents the status of the application. Possible values: Ready, Updating, Degraded, Unavailable, Missing. For applications that include the Replicated SDK, hover over the application status to view the statuses of the indiviudal resources deployed by the application.

For more information, see Enabling and Understanding Application Status.

Cluster status

LabelDescription
Cluster Type

Indicates if the cluster was provisioned by kURL.

Possible values:

  • kURL: The cluster is provisioned by kURL.
  • Existing: The cluster is not provisioned by kURL.

For more information about kURL clusters, see Creating a Kubernetes Installer.

Kubernetes VersionThe version of Kubernetes running in the cluster.
Kubernetes Distribution

The Kubernetes distribution of the cluster.

Possible values:

  • EKS
  • GKE
  • K3S
  • RKE2
kURL Nodes Total

Total number of nodes in the cluster.

Note: Applies only to kURL clusters.

kURL Nodes Ready

Number of nodes in the cluster that are in a healthy state and ready to run Pods.

Note: Applies only to kURL clusters.

New kURL Installer

The ID of the Kubernetes installer specification that kURL used to provision the cluster. Indicates that a new Installer specification was added. An installer specification is a manifest file that has apiVersion: cluster.kurl.sh/v1beta1 and kind: Installer.

For more information about installer specifications for kURL, see Creating a Kubernetes Installer.

Note: Applies only to kURL clusters.

Custom metrics

You can filter the activity feed by any custom metrics that are configured for the application. The labels for the custom metrics vary depending on the custom key value pairs included in the data set that is sent to the Vendor Portal. For example, the key value pair "num_projects": 5 is displayed as Num Projects: 5 in the activity feed.

For more information about configuring custom metrics, see Configuring Custom Metrics.

Infrastructure status

LabelDescription
Cloud Provider

The cloud provider where the instance is running. Cloud provider is determined by the IP address that makes the request.

Possible values:

  • AWS
  • GCP
  • DigitalOcean
Cloud Region

The cloud provider region where the instance is running. For example, us-central1-b

KOTS version

LabelDescription
KOTS VersionThe version of KOTS that the instance is running. KOTS version is displayed as a Semantic Versioning compliant string.

Replicated SDK version

LabelDescription
Replicated SDK VersionThe version of the Replicated SDK that the instance is running. SDK version is displayed as a Semantic Versioning compliant string.

Upstream update

LabelDescription
Versions Behind

The number of versions between the version that the instance is currently running and the latest version available on the channel.

Computed by the Vendor Portal each time it receives instance data.