Manage Eventing Functions and Settings

    +
    You can manage Eventing functions through the Couchbase Cloud UI.

    The Eventing Lifecycle

    This is a quick introduction to managing the Eventing Service. We will create a default Eventing Handler and subsequently exercising the Eventing Handler’s functionality and operations across its typical lifecycle.

    Eventing Lifecycle

    In order to show the basic life cycle of an Eventing Function, we need a source bucket and a metadata bucket. For the source bucket we will use the beer-sample sample document set. You must have a metadata bucket, typically called metadata, to be used solely by Eventing. Refer to Prerequisites

    Accessing the Eventing Service in the Couchbase Cloud UI

    If a cluster is running the Eventing Service, Eventing Functions can be created or accessed under the cluster’s Tools > Eventing Service tab.

    1. Go to the Clusters tab.

      The 'Clusters' view.
    2. Find and click on your cluster.

      This opens the cluster’s Overview tab:

      The cluster’s 'Overview' tab.
    3. Go to the Tools > Eventing tab.

      The cluster’s 'Tools > Eventing' tab.
    4. The Eventing Summery Tab is now displayed

      The Functions summary.

    Prerequisites

    The Eventing systems has a prerequisites that there is at least two (2) isolated buckets. Here, for testing purposes we need two buckets, the first a source of the events or mutations and the second is a scratchpad for the Eventing Service (this can be shared across Functions).

    For the first bucket or source of the Eventing mutations we will use the sample dataset beer-sample to load this Click the cluster’s Tools > Import tab.

    Goto Import

    The Import tab will be displayed, scroll down to the section called Beer Sample

    Import tab

    Click Import to load the beer-sample dataset.

    Load Beer Sample

    The second required bucket is an Eventing Service scratch pad area that can be shared between multiple Eventing Functions. We will just name this bucket metadata

    Go to the Buckets tab.

    Goto Buckets

    Click Add Bucket to create the metadata bucket. Fill in the Bucket Name field with the name metadata, create it with a minimum size of 100MB.

    Bucket Config

    Click Save to create the metadata bucket.

    Now Go back to the Tools > Eventing tab.

    Goto Eventing

    Functions Summary

    If there are any Functions saved on the cluster, they are displayed in the Functions summary in the cluster’s Tools > Eventing tab.

    The Functions summary.

    The Functions summary lists all Eventing Functions regardless of the functions status. This list displays the following information:

    Function Name

    The name of the Function.

    Status

    The status of the Function.

    The status can be either in a stable state of Deployed, Undeployed, and Paused or in a transitory state of Deploying, Undeploying and Pausing.

    Add New Function

    1. From the cluster’s Tools > Eventing tab, click Add Function.

      This opens the Add New Function fly-out menu. In this walk through we will configure our Function to use the prerequisites created above

      • The beer-sample bucket as an event source.

      • The metadata bucket as a common scratchpad for all Eventing Functions.

      The 'New Function' fly-out menu.
    2. Configure the details in the Add New Function fly-out menu.

      • In the Name field, enter a unique name for the Eventing Function you are creating. The Function name can only start with characters in range A-Z, a-z, 0-9 and can only contain characters in range A-Z, a-z, 0-9, underscore, and hyphen.

      • Click the Source Bucket drop-down menu and select a bucket currently defined on the cluster. For more information on creating buckets, refer to Manage Buckets.

      • Click the Metadata Bucket drop-down menu and select the Eventing metadata bucket currently defined on the cluster. Refer to the Couchbase Server documentation for more information about creating and using a metadata bucket for the Eventing Service.

      • In the Description field, you may enter a description of the Function you are creating.

      • N1QL Consistency: The default consistency level of N1QL statements in the handler. The options in the drop-down menu are None (the default) and Request.

      • Workers: The number of worker threads per node to be allocated to the Function to process events. The default is 3 (the minimum is 1 maximum is 64).

      • Script Timeout: The number of seconds that should elapse before the script times out and is terminated. The default is 60.

    3. Add any needed Bucket bindings or URL bindings.

      A binding is a construct that allows separating environment specific variables (example: bucket names, external endpoint URLs, credentials) from the handler source code. It provides a level of indirection between environment specific artifacts to symbolic names, to help moving a handler definition from development to production environments without changing code. Binding names must be valid JavaScript identifiers and must not conflict any built-in types.

      An Eventing Function can have no binding, one binding, or several bindings.

      • Bucket Bindings

        Bucket bindings allow JavaScript handlers to access Couchbase KV buckets. The buckets are then accessible by the bound name as a JavaScript map in the global space of the handler.

        You can add bucket bindings via the 'bucket-alias' choice then entering a tuple of: alias-name, bucket-name, and an access level. Where the alias-name that you can use to refer to the bucket from your handler code; the bucket-name is the actual name of the bucket in the cluster; and the access level is either read only or read and write.

      • URL Bindings

        These bindings are utilized by the cURL language construct to access external resources. The binding specifies the endpoint, the protocol (http/https), and credentials if necessary. Cookie support can be enabled via the binding if desired when accessing trusted remote nodes. When a URL binding limits access through to be the URL specified or descendants of it. The target of a URL binding should not be a node that belongs to the Couchbase cluster.

        You can add URL bindings via the 'URL-alias' choice then entering the following: alias-name, URL, allow cookies setting, and security settings of validate SSL certificate and an auth type of (no auth, basic, bearer, and digest).

    4. Example of a completed Add New Function fly-out menu.

      The 'New Function' fly-out menu.
    5. Bindings

      A binding is a construct that allows separating environment specific variables (example: bucket names, external endpoint URLs, credentials) from the handler source code.

      At the bottom of the Settings fly-out you click Add for each needed binding and then configure them appropriately.

      the following example bindings are not used in this example.

      Example Bucket Bindings

      Bucket bindings allow JavaScript handlers to access Couchbase KV buckets. The buckets are then accessible by the bound name as a JavaScript map in the global space of the handler.

      Bucket Bindings

      Example cURL Binding

      These bindings are utilized by the cURL language construct to access external resources. The binding specifies the endpoint, the protocol (http/https), and credentials if necessary.

      Bucket Bindings
    6. Click Save to save the current settings and proceed to the Code Editor fly-out menu.

    7. Add your JavaScript code to the Code Editor fly-out menu.

      The 'Code Editor' fly-out menu.

      The Code Editor fly-out menu contains valid placeholder code that just logs mutations. You may leave the code unchanged if it fits your needs.

    8. Once you’re satisfied with the Function’s JavaScript code, you can click Save to save the Function in an undeployed state.

    Deploy a Function

    When you create or import an Eventing Function, it is initially saved in an undeployed state. The Functions summary shows all functions on the cluster, along with their respective deployment status.

    This operation activates an Eventing Function (or handler). Several validations are performed, and only valid handlers can be deployed. The JavaScript source code of an activated handler cannot be edited. Unless a handler is in deployed state, it will not receive or process any events (or mutations). Deployment creates necessary metadata, spawns worker processes, calculates initial partitions, and initiates check pointing of processed stream data.

    At this time, Couchbase Cloud automatically sets the Function’s Feed Boundary to Everything upon deployment. The Feed Boundary determines whether documents previously in existence need to be included in the Function’s activities. When the Feed Boundary is set to Everything, the Function is invoked on all mutations available in the cluster. This is opposed to setting the Feed Boundary to From Now, where the Function is only invoked on future instances of data mutation post Function deployment).

    Select Deploy from the Function’s pop-up menu

    To deploy an existing Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Deploy to deploy the Function.

    Function, pop-up menu.

    Click Confirm to deploy Confirm Deploy Function fly-out menu.

    Confirm Deploy

    The Function will now enter the Deploying state and in several seconds will transition to the Deployed state and start processing events (or mutations).

    The Functions summary now lists the function as deployed.

    Deployed Function

    The deployed Eventing Function is now processing mutations.

    Running Function

    Undeploy a Function

    This operation deactivates an Eventing Function (or handler). The JavaScript source code of a deactivated handler can be edited.

    Select Undeploy from the Function’s pop-up menu

    To undeploy an existing Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Undeploy to undeploy the Function.

    The Undeploy option will not appear until the Function is deployed.
    Function, pop-up menu.

    Click Confirm to undeploy Confirm Undeploy Function fly-out menu.

    Undeploy, confirm.

    The Function will now enter the Undeploying state and in several seconds will transition to the Undeployed state and cease processing events (or mutations).

    Pause a Function

    This operation pauses and checkpoints an Eventing Function (or handler). The JavaScript source code of a deactivated handler can be edited. The checkpoint saves the point in the processing stream such that when the Function is later resumed no mutations will be missed. Handlers in Paused state can be either Resumed or Undeployed.

    Select Pause from the Function’s pop-up menu

    To pause an existing Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Pause to pause the Function.

    The Pause option will not appear until the Function is deployed.
    Function, pop-up menu.

    Click Confirm to deploy Confirm Pause Function fly-out menu.

    Confirm Pause

    The Function will now enter the Pausing state and in several seconds will transition to the Paused state and cease processing events (or mutations).

    Resume a Function

    This operation is similar to Deploy but reactivates an Eventing Function (or handler) and continues processing of a Function that was previously Paused. Several validations are performed, and only valid handlers can be resumed. The JavaScript source code of an activated handler cannot be edited. Unlike Deploy this operation will start from a previously saved checkpoint from the pause operation to ensure that no mutations are missed. On a resume the backlog of mutations that occurred when the Function was in the paused state will now be processed. In addition the backlog of timers that came due while the Function was paused will now also fire as soon as possible (ensuring that no timers are lost). Depending on the system activity and how long the Function was paused, clearing the backlog of mutations may take some time before Handler moves on to current mutations and timers.

    Select Resume from the Function’s pop-up menu

    To resume an existing Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Resume to resume the Function.

    Function, pop-up menu.

    Click Confirm to deploy Confirm Resume Function fly-out menu.

    The Function will now enter the Deploying state (there is no Resuming state) and in several seconds will transition to the Deployed state and start processing events (or mutations).

    Confirm Resume

    Deployment Statistics

    Eventing Statistics, for each deployed Function, can be viewed in the Couchbase Cloud UI, the available deployment statistics are:

    • Success - displays the number of processed Functions.

    • Backlog - displays the number of mutations to be processed by a Function.

    • Timeout - displays the number of Functions which have encountered a timeout condition.

    • Failure - displays the number of failures while processing the Function handler code.

    To display the statistics for a deployed Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Deployment Statistics.

    The Deployment Statistics option will not appear until the Function is deployed.
    Deployed Function

    The resulting Deployment Statistics fly-out will show the current deployment statistics for the Function.

    Deployed Function

    Function Logs

    Each deployed Function has its own application log. Application logs allow you to identify and capture various business logic related activities and errors via user-defined messages specific to each Function.

    The information that goes to these log files is solely dependent on the logic of the Function via log(…​) statements put inside the individual Function handler’s JavaScript code. As such, there is no logging level for application logs.

    Application logs are primarily used for the development and debugging of business logic.

    To display the application for a deployed Function, start by finding the specific Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Logs.

    The Logs option will not appear until the Function is deployed.
    Deployed Function

    The resulting Logs fly-out will show the current application log for the Function.

    Deployed Function

    Edit Settings

    To modify a specific Function’s settings, start by finding the Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Edit Settings.

    Edit Settings

    Only a subset of the Function’s settings are available for modification after the Function is created.

    • Name: Cannot be modified

    • Source Bucket: Cannot be modified

    • Metadata Bucket: Cannot be modified

    • Description: Can be modified at any time

    • N1QL Consistency: Can only be modified when the Function is undeployed or paused

    • Workers: Can only be modified when the Function is undeployed or paused

    • Script Timeout: Can only be modified when the Function is undeployed or paused

    To modify any of the above settings that require the Function to be in an undeployed or paused state, you will first need to undeploy or pause the Function by invoking the appropriate action from that pop-up menu at the right of the Function’s row.

    Save Settings

    Once you’re satisfied with the modifications you’ve made to the Function’s settings, make sure to click Save to commit the changes.

    Edit JavaScript

    To modify a specific Function’s JavaScript code, start by finding the Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Edit JavaScript.

    Edit JavaScript

    You may now use fly-out editor to modify and change your business logic.

    Save JavaScript

    Once you’re satisfied with the modifications you’ve made to the Function’s JavaScript code, make sure to click Save to commit the changes.

    Delete Function

    To delete a specific Function’s settings, start by finding the Function in the Functions summary list, and then invoking the pop-up menu at the right of the Function’s row select the menu item labeled Delete.

    Before you can delete a specific Function, you must first ensure that it is undeployed. Only Functions that are in an undeployed state can be deleted.

    Delete

    Click Confirm to delete Confirm Delete Function fly-out menu.

    Confirm Delete