Troubleshoot your app

11 min

OCP apps log messages using the App SDK logger to assist in development and debugging. Log access differs by role.

Optimizely Support – Views all logs for all OCP apps.

App developers – View logs from their app in OCP accounts they have access to, such as a sandbox account. This includes logs from lifecycle hooks, functions, and jobs, but not global functions. Run ocp app logs in the OCP CLI to access your logs.

OCP customers – View logs for apps installed to their account. They access these logs in the Troubleshooting tab of the app in the OCP App Directory.

📘 Note Logs are intended for debugging and troubleshooting purposes. To provide customer-facing messages in the OCP Activity Log, use Activity Log notifications.

Log levels

Log messages with one of the following log levels:

info – The default log level for full release and beta pre-release app versions.

debug – The default log level for -dev tagged app versions.

warn

error

To check the current log level for an app installation, run the following command in the OCP CLI:

ocp app get-log-level APP_VERSION --trackerId=TRACKER_ID

To change the log level for an app installation, run the following:

ocp app set-log-level APP_VERSION NEW_LOG_LEVEL --trackerId=TRACKER_ID

📘 Note The change lasts two hours. OCP then resets the log level to the default.

Use logger instead of console to capture messages at the correct log level. However, the app runtime also captures console calls as a safety measure for uncontrolled dependency usage, writing messages with the following log levels:

debug – debug

info – info

log – info

warn – warn

error – error

The logger uses the same mechanism that console.log does to inspect objects passed in as arguments.

Import App SDK logger

The App SDK exposes the logging feature through the logger instance. Import it as follows:

import {logger} from '@zaiusinc/app-sdk';

The logger instance follows the ILogger interface in the App SDK.

/**
 * OCP Logger interface
 */
export interface ILogger {
  /**
   * Write something to the logs at the Debug level
   * @param args One or more values to log.
   *   Objects are formatted using `util.inspect`, other values are converted to a string.
   *   Multiple values are concatenated with a space between
   */
  debug(...args: any[]): void;

  /**
   * Write something to the logs at the Info level
   * @param args One or more values to log.
   *   Objects are formatted using `util.inspect`, other values are converted to a string.
   *   Multiple values are concatenated with a space between
   */
  info(...args: any[]): void;

  /**
   * Write something to the logs at the Warning level
   * @param args One or more values to log.
   *   Objects are formatted using `util.inspect`, other values are converted to a string.
   *   Multiple values are concatenated with a space between
   */
  warn(...args: any[]): void;

  /**
   * Write something to the logs at the Error level
   * @param args One or more values to log.
   *   Objects are formatted using `util.inspect`, other values are converted to a string.
   *   Multiple values are concatenated with a space between
   */
  error(...args: any[]): void;
}

Capture stack traces

To capture a stack trace, supply the error as a separate argument.

// This will include the stack trace of `e` if it is an error
logger.error('Something went wrong:', e);

// This will NOT include the stack trace
logger.error(`Something went wrong: ${e}`);

Access logs in the OCP CLI

Use the OCP CLI to access logs from your app in OCP accounts you have access to, such as a sandbox account.

To access your app logs, run the following:

ocp app logs --appId=APP_ID --trackerId=TRACKER_ID

By default, the command returns logs from the last 24 hours. Specify a different time range using the --from and --to options. Use the -a or --availability option to query logs from regions other than the default US region.

To query logs produced by a job execution, run the following:

ocp app logs --jobId=JOB_ID

📘 Note Use the ocp job list command to get the job ID.

To fetch build logs produced by the ocp app prepare command, run the following:

ocp app logs --buildId=BUILD_ID

📘 Note Use the ocp app prepare command to get the build ID.

To view all available logging options for ocp app logs, use the -h flag:

$ ocp app logs -h
Active environment: production
@optimizely/ocp-cli  1.0.3  (Apache-2.0)
Usage: ocp app logs [--tail] [--appId=<appId>] [--buildId=<buildId>] [--appVersion=<appVersion>] [--trackerId=<trackerId>] [--jobId=<jobId>] [--level=<level>] [--from=<from>] [--to=<to>]
               [--search=<search>] [--availability=<availability>]

Flags:
  --tail   Tails the logs

Options:
  --appId              The App ID (e.g. my_app). Either App ID or Build ID must be specified.
  --buildId            The ID of the build. Either App ID or Build ID must be specified. Build IDs are printed by 'ocp app prepare' command.
  --appVersion         The app version (e.g. 1.0.0)
  --trackerId          The Tracker ID of the ODP account (required for developers)
  --jobId              Show logs for given execution of a job. Use 'ocp jobs list' command to get the job ID
  --level              Filter app logs by log level. Valid values: INFO, DEBUG, WARN, ERROR
  --from               A start time as an ISO string, an epoch timestamp, or relative string (i.e. "5m" for 5 minutes.) Default: 24h
  --to                 A end time as an ISO string, an epoch timestamp, or relative string (i.e. "5m" for 5 minutes)
  --search             String to search for in log messages.  Can be specified multiple times.
  --availability, -a   The availability zone that will be targeted (default: us)

Activity Log notifications

For customer-facing messages about significant events such as data imports, sync operations, or errors, use Activity Log notifications instead of app logs. See Activity Log notifications for implementation details.

Common issues

The following issues are common during development:

Build failures – Run ocp app logs --buildId=BUILD_ID to view build logs and identify the cause. Common causes include missing dependencies and TypeScript compilation errors.

Function timeouts – Functions have a maximum execution time. Break large operations into smaller tasks or use jobs for long-running work.

Job failures – Use ocp app logs --jobId=JOB_ID to view logs for a specific job execution. Ensure the perform method completes in under 60 seconds.

Settings form issues – Test your form locally with ocp dev to verify rendering and validation before publishing. See Local testing.