A newer version of this documentation is available.

View Latest

Debugging and Diagnosability

Debugging and diagnostics in the Eventing Service comprises of debugging functions, logging functions, and log redaction.

Debugging Functions

Couchbase Server, for its Eventing Service framework, includes an online real-time Javascript Debugger. Debug is a special flag on a Function. The Debug option integrates seamlessly with the Google Chrome Debugger engine for running the Javascript code.

Debugging Workflow

  • During a debug session, a single mutation received by the Function is considered and sent to the Debugger. This technique ensures that processing of the other data mutations in the cluster does not get blocked.

  • The Worker in the Debugger pauses to trap the next event-instance, opens an ephemeral TCP port, and generates a Chrome dev-tools URL, with a session cookie that controls the debug worker.

  • All other events are unaffected except the trapped event-instance.

  • Using the Debug option, you can place breakpoints in the code and run the Function execution, one line at a time. The step-step execution helps while troubleshooting the deployed Function.

  • If the debugged event-instance completes execution, no further event-instance gets trapped for debugging.

  • Debugging is a convenience-feature intended to help during Function development: it is not designed for production environments. Debug mode should not be used in Product environments, as it affects the in-order processing of the document mutations. In a production environment, debug sessions introduce timing issues. If a debug session gets terminated during execution, then the mutation may be abruptly processed.

Debugging a Function Using the Debug Option

  1. From the Couchbase Web Console > Eventing page, click on the name of a deployed Function. The deployed Function expands to provide additional options. Click Edit JavaScript.

    debug 1
  2. From the Edit Function page, click Debug. A debug session gets activated. As a result, the next event-instance gets trapped and is forwarded to the Debugger.

    In the below screen, you can notice the message: "Waiting for mutation."

    debug 2
  3. Upon a data mutation, the debug URL in the Debugging pop-up gets populated.

    debug 3
  4. Copy the URL from the Debugging pop-up and paste it into your Google Chrome browser.

    debug 4
  5. From your Google Chrome browser, you can add breakpoints and run step-step diagnosis to debug and troubleshoot the deployed Function. From the Debugging pop-up, click Stop Debugging to terminate a debug session.

Logging Functions

The Eventing Service creates two different types of logs:

  • System Logs

  • Application Logs

System Logs

For the Eventing Service, Couchbase Server creates a separate system log file, termed as eventing.log. The system log file captures all the Eventing Service related system errors depending on the level and severity of the reported problem. For every node, a single system log file gets created.

The eventing.log contains redactable user data and the log is collected using the cbcollect_info tool. For log rotation, refer to Using Logs.

Application Logs

Application logs allow you to identify and capture various Function related activities and errors.

All Function-related activities such as editing the handler code, debugging, or modifying feed boundaries conditions, get recorded in the Application logs. Couchbase Server creates an individual log file for every Function in the cluster. By default, the maximum size of an Application log file is 40MB, and the number of log files before rotation is 10. Unlike system logs, the Application logs are user configurable. You can access an Application log file using the command line interface. Couchbase Server creates different application log files depending on the level and severity of the reported problem, as configured during Function definition.

The cbcollect_info tool does not collect the Application log files.
Table 1. Application Logs Path in Platform
Platform Location

Linux

/opt/couchbase/var/lib/couchbase/data/@eventing

Windows

C:\Program Files\Couchbase\Server\var\lib\couchbase\data\@eventing (Assumes default installation location)

Mac OS X

/Users/<user>/Library/Application Support/Couchbase/var/lib/couchbase/data/@eventing

To configure an Application log, use the REST endpoint settings option.

Sample URL: 192.168.1.5:8091/_p/event/api/v1/functions/<Function_name>/settings

Sample Payload:

{
  "settings":
    {
      "app_log_max_files": 10,
      "app_log_max_size": 10485760
    }
  }

The sample payload above illustrates that the system stores 10 application log files and each file records about 10 MB of data.

At some point in time, old application log files that are no longer necessary need to be deleted to make way for new log records. When an Application log file reaches the set limit, a new log file gets created. All the recorded information from the active log file gets transferred to this newly created file.

For illustration, consider enrich_ip_nums as the name of the Function. A corresponding Application log file, enrich_ip_nums.log, gets created in the Couchbase cluster. Whenever the enrich_ip_nums.log reaches 10MB in size, assuming the maximum size of an Application log file is 10MB and the number of log files before rotation is 10, the system automatically generates the enrich_ip_nums.log.1 file, during its first iteration. The file enrich_ip_nums.log transfers all the log information to this new log file. For this illustration, since the number of log files is 10, the system stores 10 such files, the currently active log file along with 9 truncated files, at any given instance.

Log Redaction

You can use logs for multiple purposes ranging from security, monitoring, and diagnostics. Suppression of sensitive data such as personally identifiable information (PII), hostnames, internal asset information, credit card details, during the logging operation is termed as log redaction. Organizations implement log redaction as part of their legal compliance and security risk mitigations.

Couchbase Server provides a capability to redact sensitive user data from getting captured in the logs. All sensitive data are scrubbed and gets removed from the log files. Post redaction, log files can be shared for troubleshooting without disregarding any regulatory compliance.

For details, see Understanding Redaction.