Monitor deployed applications

OSF provides tools that you can use for monitoring deployed applications by querying the deployment controllers running on the storefront server.

A controller instance is a Node.js application that manages the availability of a new deployment. The controller receives the deployment from the administration server, installs it, and then spawns application instances from it. The controller then switches incoming HTTP traffic to the new instances and takes the previous deployment offline. Each deployment is assigned a unique ID that can be used to identify it for monitoring.

The controller produces logs related to the process of accepting, installing, starting, and switching deployments. These logs are particularly helpful in cases where the application does not install successfully. For example, if the deployment status indicates that a deployment is not active on a controller, the logs for the controller will contain information that can help you determine why.

A cluster is a group of preview and live controllers. A cluster has one or more controllers configured for the preview context and one or more controllers configured for the live context.

When a deployment is uploaded, the administration server pushes it to the preview controllers in the cluster. When each preview controller receives the new application, it makes the previous preview application inactive. The controller deletes the inactive application's files, sets up the new application, starts it, and then makes it active by beginning to route traffic to it. Similarly, when a preview application is published, it is pushed from the preview context to the live context controllers, which inactivate the previous live application and activate the newly published application.

View deployment status

You can use the deploy-status command to return status information about a deployed application. The command supports a variety of options for querying about the status of deployments. These include options that return:

The status of the preview and live deployments for a specified application.
The status of a deployment specified by ID.
The status of the deployments in a cluster.

Different information is returned for each of these queries. The responses are described below.

Query by application

To see the status of the preview and live deployments for an application, specify the name of the application in the command like this:

yarn occ deploy-status <app-name>

If you do not supply the application name, it defaults to the value of the appName setting in the workspace's .occ/config.js file. You can change this setting using the configure command or edit the setting in the file directly.

The deploy-status command returns information about the preview and live deployments that have been received by the administration server and their status on their respective controllers. For example:

yarn occ deploy-status my-app

[cli] info: Getting status for application my-app 
[cli] info: Deployment 300322 found in preview.
[cli] info: - Deployment: 300322 - 
[cli] info:   application id: my-app 
[cli] info:   creation date:  2020-06-10T03:50:27.087Z 
[cli] info:   tags:           username:fsmith
[cli] info: Deployment 300322 is fully installed in preview. 
[cli] info: Deployment 300322 found in live. 
[cli] info: - Deployment: 300322 - 
[cli] info:   application id: my-app 
[cli] info:   creation date:  2020-06-10T03:50:27.087Z 
[cli] info:   tags:           username:fsmith
[cli] info: Deployment 300322 is fully installed in live.

The response includes the deployment ID for each deployment. In this example, the same deployment (ID = 300322) is present in both the preview and live contexts, but that may not always be the case.

If the response indicates that a deployment is fully installed in the preview or live context, this means it is currently running on that context’s controllers. However, if you see a message like the following, the deployment was received by the administration server but has failed to install and run successfully:

[cli] info: Deployment 300322 found in preview.
. . .
[cli] info: Deployment 300322 is not fully installed in preview.

See Redeploy an application for information for information about what to do if this occurs.

Query by deployment ID

To see the status of a single deployment specified by deployment ID, use the –-deployment option:

yarn occ deploy-status --deployment <deployID>

The deployment can be one currently running in the preview or live context, or any earlier deployment for which Commerce still has a record. If there is a record of the specified deployment on the administration server, information like the following is returned:

[cli] info: Getting status for deployment 300322 
[cli] info: - Deployment: 300322 - 
[cli] info:   application id: my-app 
[cli] info:   creation date:  2020-06-10T03:50:27.087Z 
[cli] info:   tags:           username:fsmith

If the specified deployment is the current preview or live deployment, information like the following is also returned:

[cli] info: Deployment 300322 found in preview. 
[cli] info: Deployment 300322 is fully installed in preview. 
[cli] info: Deployment 300322 found in live. 
[cli] info: Deployment 300322 is fully installed in live.

Query by cluster

You can query deployment status by cluster to return information about the deployments running on the controllers in the cluster, and about earlier deployments that are now inactive. The information returned reflects only deployments that have been successfully installed, not deployments that were received by the administration server but were not installed successfully.

To return the status of the deployments in a cluster, use the –-cluster option:

yarn occ deploy-status --cluster <clusterID>

If <clusterID> is omitted, its value defaults to storefront. This is the only value currently supported.

The response is returned in JSON format, as in the following example:

[cli] info: Getting status for cluster storefront 
[cli] info: {
  "preview": [
    {
      "registry": "https://myhost-npmregistry.oc-test.com",
      "host": "https://myhost-previewsf2.oc-test.com/gcommerce-osfcontroller1",
      "containerId": "b593ddef66b6",
      "controllerVersion": "1.8.0",
      "status": [
        {
          "appCapacity": 0,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "STOPPED",
          "deployId": "300321"
        },
        {
          "appCapacity": 1,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "ACTIVE",
          "deployId": "300322"
        }
      ]
    },
    {
      "registry": "https://myhost-npmregistry.oc-test.com",
      "host": "https://myhost-previewsf2.oc-test.com/gcommerce-osfcontroller2",
      "containerId": "50c631159649",
      "controllerVersion": "1.8.0",
      "status": [
        {
          "appCapacity": 0,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "STOPPED",
          "deployId": "300321"
        },
        {
          "appCapacity": 1,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "ACTIVE",
          "deployId": "300322"
        }
      ]
    }
  ],
  "deployments": [
    {
      "metadata": "{\"appName\":\"my-app\",\"appDir\":\"packages/apps/my-app\",\"tags\":[\"username:fsmith\"]}",
      "repositoryId": "300322",
      "clusterId": "storefront",
      "id": "300322",
      "applicationId": "my-app",
      "creationDate": "2020-06-10T03:50:27.087Z"
    },
    {
      "metadata": "{\"appName\":\"my-app\",\"appDir\":\"packages/apps/my-app\",\"tags\":[\"username:fsmith\"]}",
      "repositoryId": "300321",
      "clusterId": "storefront",
      "id": "300321",
      "applicationId": "my-app",
      "creationDate": "2020-06-10T03:48:29.049Z"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://myhost-admin.oc-test.com/ccadmin/v1/deploymentEnvironment/storefront/status"
    }
  ],
  "live": [
    {
      "registry": "https://myhost-npmregistry.oc-test.com",
      "host": "https://myhost-livesf2.oc-test.com/gcommerce-osfcontroller1",
      "containerId": "eb262e366c7f",
      "controllerVersion": "1.8.0",
      "status": [
        {
          "appCapacity": 0,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "STOPPED",
          "deployId": "300321"
        },
        {
          "appCapacity": 1,
          "instanceFailures": 0,
          "appName": "my-app",
          "state": "ACTIVE",
          "deployId": "300322"
        }
      ]
    }
  ]
}

View deployment logs

You can use the deploy-log command to return controller logs for a deployed application. The command supports a variety of ways to specify a cluster to return logs for. These include supplying one of the following:

The name of the application deployed in the cluster.
The cluster ID.
The ID of the deployment that the cluster is associated with.

You can specify the name of the application in the command like this:

yarn occ deploy-log <app-name>

The command determines the current preview deployment for the specified application, determines what cluster that deployment was installed on, and then queries that cluster for its logs related to that deployment. This enables you to retrieve the logs even if you do not know the deployment ID.

You can specify the cluster by using the –-cluster option:

yarn occ deploy-log --cluster <clusterID>

Specifying the cluster ID overrides the application name. Note that if you include the –-cluster option but omit the cluster ID, the cluster ID defaults to storefront. This is the only value currently supported.

You can specify the deployment by using the –-deployment option:

yarn occ deploy-log --deployment <deployID>

The deployment ID is required. This option overrides the application name and the --cluster option if they are specified.

Return the system log

To see the system log for the cluster rather than the application log, use the --system option. For example:

yarn occ deploy-log -–system

[cli] info: Connecting to https://myhost-admin.oc-test.com 
[cli] info: Getting logs for application my-app 
[cli] info: logs for http://10.74.98.250:4080 
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] info: [1/5] Validating package.json...
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] info: [2/5] Resolving packages...
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] info: [3/5] Fetching packages...
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] info: [4/5] Linking dependencies...
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] warn: warning " > @oracle-cx-commerce/cli@1.8.0" has unmet peer dependency "@oracle-cx-commerce/rollup-config@*".
2020-05-19 17:30:15 - [storefront-60e98a0a1f6e-controller-104] warn: warning " > @oracle-cx-commerce/cli@1.8.0" has unmet peer dependency "builtin-modules@*".
...
2020-05-19 17:30:17 - [storefront-60e98a0a1f6e-controller-104] info: [5/5] Building fresh packages...
...

Redeploy an application

If you detect issues with an existing deployment or if a new deployment fails, you can use the redeploy command to resend the deployment to the cluster. You can use this command to retry a failed installation or to synchronize the controllers on the same deployment. The deployment is determined based on the application that was last deployed to the cluster.

You can use command options to specify the server environment and context. For example, use the –-live option to specify the live context:

yarn occ redeploy --live

By default, the deployment is pushed only to the controllers that are not already running it. To force controllers to reinstall the deployment regardless of whether they are currently running it already, use the –-live option. For example:

yarn occ redeploy --force

Tag deployments

To help you to track your deployments, the deploy command includes a –-tag option that you can use to add custom metadata to deployments to distinguish them from one another. This option enables you to label your deployments in a way that is meaningful within your organization. For example, the following command deploys an application and adds tags that specify the build number (using whatever convention your team prefers) as well as a feature in the build:

yarn deploy my-app --tag build1.2.3 --tag featureX

The following example illustrates how the tags are returned by the deploy-status command:

yarn deploy-status --deployment 2300001 

[cli] info: Getting status for deployment 2300001 
[cli] info: - Deployment: 2300001 -
[cli] info:   application id: my-app
[cli] info:   creation date:  2020-05-07T22:32:26.754Z
[cli] info:   tags:           build1.2.3, featureX, username:fsmith
[cli] info: Deployment 2300001 found in preview.
[cli] info: Deployment 2300001 found in live.

Note that the username tag is added automatically. It reflects the username on the machine where the deployment was created.