Debugging and Diagnosability

Debugging and diagnostics in the Eventing Service comprises of debugging functions, functions log, 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.

Port 9140 is the default Eventing debug port. To change the default port settings, see Modifying the Debug Port.

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.

  • If a debug session gets terminated during execution, then the mutation may be abruptly processed.

  • 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 production environments, as it affects the in-order processing of the document mutations. Additionally, the debug sessions introduce timing related issues.

Debugging a Function Using the Debug Option

  1. To enable debugging, navigate to Couchbase Web Console > Eventing page, from the top banner, click Settings and check the Enable Debugger option.

  2. From the Eventing page, click on the name of a deployed Function. The deployed Function expands to provide additional options. Click Edit JavaScript.

    debug 1
  3. 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
  4. Upon a data mutation, the debug URL in the Debugging pop-up gets populated.

    debug 3
  5. Copy and paste the URL from the Debugging pop-up to your Google Chrome browser.

    debug 4
  6. From your Google Chrome browser, you can add breakpoints and run step-step diagnosis to debug and troubleshoot the deployed Function.

  7. From the Debugging pop-up, click Stop Debugging to terminate a debug session.

Transpiler and Source Map

A transpiler accepts source code provided as input from one high-level programming language and produces an equivalent code in another high-level programming language.

Couchbase Server uses a native transpiler. This transpiler converts the handler code to a code that the JavaScript engine can understand. If this transpiler was unavailable, then the JavaScript engine would have failed to compile any native N1QL queries.

Source map, generated by our native transpiler, provides a mapping between the transpiled code and the original function handler code. Debugging is easy as the debugger detects the source map and presents the code in the original format.

Upon source map detection, a text confirmation flag gets displayed in the debug window
(highlighted below).

debug sourcemap

Modifying the Debug Port

By default, the ns_server configures the Eventing Debug on port 9140. Using the static_config file you can modify the default Eventing Debug port.

To modify the debug port:

  1. Stop Couchbase server.

  2. Navigate to the /opt/couchbase/etc/couchbase/static_config file. This is the location where Couchbase Server picks up the configuration parameters.

  3. Edit the static_config file to add the new eventing_debug_port and the new port-number information.

  4. (Optional step) To remove any old configuration file, delete the /opt/couchbase/var/lib/couchbase/config/config.dat file.

  5. Start Couchbase server.

Note: If no port numbers are not specified, default ports are used. To override some or all default ports, append the user-defined ports to the static_config file file.

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 clustersetup:ui-logs.adoc.

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

During Cluster setup, if you have chosen a custom path, then the path for Application logs is same as that of the selected Indexes Path. The @eventing folder in the selected Indexes Path stores the Application logs.

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.

Log redaction is applicable only for System logs and not for Application logs.