A newer version of this documentation is available.

View Latest

The Eventing Lifecycle

    +
    This page shows how to add a new Eventing Function and briefly explores the Eventing Lifecycle.
    lifecycle overview notitle

    This is a quick introduction to Eventing via creating a simple Eventing Handler and subsequently exercising the Eventing Handler’s functionality and operations across its typical lifecycle. For a deeper insight refer to the more detailed Eventing Examples.

    Prerequisites: In order to show the basic life cycle of an Eventing Function, we need a source bucket and a metadata bucket. You must have a metadata bucket, typically called metadata, to be used solely by Eventing — if it is missing, create it with a minimum size of 100MB. For the source bucket we will use the beer-sample sample document set.

    If you don’t already have the sample bucket beer-sample listed in the Couchbase Web Console > Buckets page you can load this document set as follows: Access the Couchbase Web Console > Settings page Select the Sample Buckets in the upper right banner. Check beer-sample checkbox. Click Load Sample Data.

    To add a new Eventing Function:

    1. From the Couchbase Web Console > Eventing page, click ADD FUNCTION.

      An empty ADD FUNCTION dialog is shown:

      addfunc 01 empty settings

      The ADD FUNCTION dialog enables the developer to provide the following information:

      Table 1. Add a Function Dialog
      Elements Description

      Source Bucket

      The name of a bucket currently defined on the cluster.

      For more information on creating buckets, refer to Create a Bucket.

      Metadata Bucket

      The name of a bucket currently defined on the cluster. This bucket stores artifacts and checkpoint information.

      Function Name

      A name, for the Function you are creating.

      Description

      A description of the Function you are creating. This is optional.

      Settings

      The available settings are:

      • Log Level: The granularity at which messages are logged. The options (available from the arrows control at the right of the field) are Info, Error, Warning, Debug, (the default), and Trace. This logging attribute is function-specific and is not applicable for the Eventing Service in general.

      • N1QL Consistency: The default consistency level of N1QL statements in the handler either None (the Default) or Request. The default is 3 (the minimum is 1 maximum is 64).

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

      • Language compatibility: The language version of the handler for backward compatibility either 6.0.0 or 6.5.0. Primarily to allow older handlers to continue to see the runtime behavior that existed at the time they were authored

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

      Bindings

      A binding is a construct that allows separating environment specific variables (example: bucket names, external endpoint URLs, credentials) from the handler source code. Currently Eventing Functions support either Bucket Bindings (to access KV data) or URL Bindings to communicate externally via cURL. An Eventing Function can have no binding, one binding, or several bindings.

      For more information on Bindings, refer to Bindings.

    2. In the ADD FUNCTION dialog, enter the following information:

      • For the Source Bucket drop-down, select beer-sample.

      • For the Metadata Bucket drop-down, select metadata.

      • Enter my_evt_function as the name of the Function you are creating in the Function Name text-box.

      • [Optional Step] Enter text A simple Eventing Function only prints IDs, in the Description text-box.

      • For the Settings option, use the default values.

      • For the Bindings option, don’t add any bindings (we will merely be logging messages).

        addfunc 02 settings
    3. After providing all the required information in the ADD FUNCTION dialog, click Next: Add Code. The my_evt_function dialog appears.

      • The my_evt_function dialog initially contains a placeholder code block. You will accept the default for your my_evt_function code.

        addfunc 03 editor with default
      • You will need to click Save if you modified the JavaScript source.

      • To return to the Eventing screen, click the '< back to Eventing' link (below the editor) or click the Eventing tab.

    4. Click on the Function name.

      addfunc 04 newundeployed

      Additional controls are now displayed. The controls are:

      • Delete: Deletes the Eventing Function from the system.

      • Export: Exports the Eventing Function as a JSON document.

      • Deploy: Deploys the Eventing Function, making it active across the cluster.

      • Pause: Pauses the Eventing Function, making it active across the cluster (only allowed if Deployed).

      • Edit JavaScript: Allows edits to be made on the Eventing Function, in an edit dialog (only allowed when Paused or Undeployed).

    5. From the Eventing screen, click Deploy.

      • In the Confirm Deploy Function dialog, select Everything from the Feed boundary option.

        The Feed Boundary determines whether documents previously in existence need to be included in the Function’s activities: the options are Everything and From now. The Everything option invokes a Function on all mutations available in the cluster. The From now option invokes a Function during future instances of data mutation, post Function deployment.

      • Click Deploy Function.

    6. The Eventing function is deployed and starts running within a few seconds. From this point, the defined Function is executed on all existing documents and on subsequent mutations.

      input output overview 6.5

      This simple example only has a log(…​.) statement in the OnUpdate handler that will merely list items in the bucket 'beer-sample', i.e. 7,303 documents. Basically the only thing the function does is print the key or ID of each document.

    7. Once the Eventing Function is fully deployed its status will change from deploying…​ to a status of deployed.

    8. Verify that the deployment actually worked by clicking the Log link that appeared after you deployed the Eventing Function in the right hand side of the screen.

      • A dialog showing the Function Log - my_evt_function will appear with the most recent logging information (in reverse order with the most recent lines first).

        addfunc 05 logs emitted
      • Click Close.

    9. To pause and resume a function (you can then edit and update the function without missing a mutation)

      • Click Pause.

      • In the Confirm Pause Function dialog

        • Click Pause Function.

      • The Eventing function will now pause.

      • Wait for the "paused" state.

      • Click Resume.

      • In the Confirm Resume Function dialog

        • Click Resume Function.

      • The Eventing function will now resume.

    10. To remove the Eventing Function my_evt_function

      • Click Undeploy.

      • In the Confirm Undeploy Function dialog

        • Click Undeploy Function.

      • The Eventing function will now undeploy.

      • Wait for the "undeployed" state.

      • Click Delete.

      • In the Confirm Delete Function dialog

        • Click Delete Function.

    The Eventing Function lifecycle operations (deploying, undeploying, pausing, resuming, and deleting operations) and the Eventing rebalance operation are mutually exclusive. The Eventing rebalance operation fails when an Eventing Function lifecycle operation is currently in progress. Likewise, when the Eventing rebalance operation is in progress, you cannot perform an Eventing Function lifecycle operation.