Doc 4306

modules/ROOT/nav.adoc

@@ -121,8 +121,13 @@
 * xref:eventing:eventing-overview.adoc[Eventing Service: Fundamentals]
  ** xref:eventing:eventing-Terminologies.adoc[Terminology]
  ** xref:eventing:eventing-language-constructs.adoc[Language Constructs]
+  *** xref:eventing:eventing-timers.adoc[Timers]
  ** xref:eventing:eventing-adding-function.adoc[Adding a Couchbase Function]
  ** xref:eventing:eventing-examples.adoc[Examples: Using the Eventing Service]
+  *** xref:eventing:eventing-example-data-enrichment.adoc[Data Enrichment]
+  *** xref:eventing:eventing-examples-high-risk.adoc[Risk Assessment]
+  *** xref:eventing:eventing-examples-cascade-delete.adoc[Cascade Delete]
+  *** xref:eventing:eventing-examples-docexpiry.adoc[Document Expiry and Archival]
  ** xref:eventing:eventing-debugging-and-diagnosability.adoc[Debugging and Diagnosability]
  ** xref:eventing:eventing-statistics.adoc[Statistics]
  ** xref:eventing:troubleshooting-best-practices.adoc[Troubleshooting and Best Practices]

modules/eventing/pages/eventing-Terminologies.adoc

@@ -23,31 +23,40 @@ NOTE: In the Couchbase Server 6.0 BETA release, the handler code size is limited
 
 The persistent state of a Function is captured by entities listed below, while any state that appears on the execution stack is ephemeral.
 
-* The metadata bucket (which will eventually be a system collection).
+* The metadata bucket.
 * The document being observed and its Extended Attributes.
 
 == Buckets
 
-Every Function definition needs two distinct buckets: source bucket and metadata bucket.
+There are two distinct buckets: source bucket and metadata bucket.
 
-The Functions use a source bucket to listen to data changes.
-The Function handler code polls the source bucket for data mutations.
-Multiple Functions can use the same source bucket.
+*Source Bucket*
 
-Metadata bucket stores internal artifacts and checkpoint information.
-The metadata bucket provides better restartability semantics when the eventing nodes is offline.
-Ensure that your Function handler code does not write any data to this bucket.
+Couchbase Functions use a bucket to track data mutations. This bucket is termed as the source bucket. The source bucket can be either Couchbase or Ephemeral bucket type. However, memcached bucket types are not supported.
 
-The Functions can in turn trigger data mutations, to avoid a cyclic generation of events, ensure that you carefully consider options when you select the source and destination buckets.
-When you are using a series of handlers, ensure that:
+When you are creating a function, you need to specify a source bucket. The handler code polls this bucket to track data mutations.
 
-* The source bucket can be either Couchbase or Ephemeral bucket.
-However, memcached buckets are not supported.
-* Metadata bucket is used by the Eventing Service to store some critical checkpoint information.
-Avoid writing to the metadata bucket or flushing it.
-It is recommended that a separate bucket be kept destined as a metadata bucket.
-* A read operation from the source bucket is allowed but operations such as delete, set and update are not supported.
-* The destination buckets to which event handlers perform a write operation, do not have other event handlers configured to listen and track data mutations.
+NOTE: You can use a common source bucket to listen to multiple Functions running different code.
+
+When a source bucket is deleted, all deployed functions associated with this source +
+bucket, are undeployed.
+
+
+After processing the handler code, documents can be stored in a different bucket. For understanding purposes, this bucket can be termed as a destination bucket.
+
+At times, the handler code can trigger data mutations. To avoid cyclic generation of data changes, refer to xref:troubleshooting-best-practices.adoc#cyclicredun[Bucket Allocation Considerations].
+
+*Metadata Bucket*
+
+Metadata bucket stores artifacts such as timers, DCP streams, worker allocations along with internal checkpoint information.
+
+When you are creating a Function, ensure that a separate bucket is destined as a +
+metadata bucket. You can use a common metadata bucket across multiple Functions.
+
+NOTE: At any point, refrain from deleting the metadata bucket. Also, ensure that the Function handler code does not perform a write operation on the metadata bucket.
+
+If a metadata bucket gets accidentally deleted, then all deployed functions are +
+undeployed and associated indexes get dropped.
 
 == Workers
 
@@ -57,11 +66,14 @@ The worker units are used mostly during Function execution.
 [#section_mzd_l1p_m2b]
 == Bindings
 
-Bindings are constructs that allow the separating of environment-specific variables from the handler source code such as bucket-names, external endpoint URLs, and credentials.
-Bindings allow Functions to be developed without source-code changes while working on different workflows.
-Using bindings, you can port source code from different environments such as Test-to-Test, Test-to-Production, or Production-to-Production environments without making code changes.
+A binding allows separating of environment specific variables from the handler code.
+
+You can add bindings as a name-value pair, where name is the actual name of the bucket in the cluster, and value is the alias that you can use to refer to the bucket from your +
+handler code.
 
-During Function definition when you are creating a bindings name-value pair, for a source bucket, ensure that only read operation is performed in the Function handler code.
+NOTE: Bindings are mandatory when your handler code performs any bucket related operations.
+
+Bindings ensure easy porting of source code across different environments. You can export-import Functions from test-to-test, test-to-production, or production-to-production environments, without making code changes.
 
 == Function Settings
 
@@ -91,7 +103,7 @@ To edit a deployed Function, you must first un-deploy the Function.
 == Feed Boundary
 
 Feed Boundary is a time milestone used during a Function configuration.
-Using the Feed Boundary option, you can either invoke a Function on all the data present in the cluster or choose to invoke a Function during future instances of data mutation, post Function deployment.
+Using the Feed Boundary option, you can either invoke a Function on all data mutations available in the cluster or choose to invoke a Function during future instances of data mutation, post Function deployment.
 
 == Undeploy
 
@@ -107,9 +119,3 @@ Newly created handlers start in an undeployed state.
 
 When a Function gets deleted, the source code implementing the Function, all processing checkpoints, and other artifacts in the metadata provider are purged.
 Before deleting, make sure you have undeployed the Function.
-
-== Timers
-
-Timers provide execution of code at a preconfigured clock time or after a specified number of seconds.
-Using timers, you can write a simple JavaScript Function handler code to delay or trigger the execution of a Function at specific wall-clock time events.
-Timers allow archiving of expired documents at a preconfigured clock time.

modules/eventing/pages/eventing-adding-function.adoc

@@ -16,7 +16,7 @@ To add a new Function, proceed as follows:
 | Source Bucket
 | The name of a bucket currently defined on the cluster.
 
-For more information on Source Bucket, refer to xref:clustersetup:create-bucket.adoc[Create a Bucket].
+For more information on creating buckets, refer to xref:clustersetup:create-bucket.adoc[Create a Bucket].
 
 | Metadata Bucket
 | The name of a bucket currently defined on the cluster.
@@ -61,7 +61,7 @@ Additional controls are now displayed: The controls are:
 . Click *Deploy*.
 This displays the *Confirm Deploy Function* dialog.
 The Feed Boundary determines whether documents previously in existence needs to be included in the Function's activities: the options are *Everything* and *From now*.
-The *Everything* option invokes a Function on all the data present in the cluster.
+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.
 This deploys the Function and returns you to the main Eventing screen.

modules/eventing/pages/eventing-api.adoc

@@ -3,6 +3,8 @@
 [abstract]
 The Functions REST API, available by default at port 8096, provides the methods available to work with Couchbase Functions.
 
+NOTE: The Functions REST API is a Beta feature intended for development purposes only, do not use them in production; no Enterprise Support is provided for Beta features.
+
 .Functions API
 [cols="2,3,6"]
 |===

modules/eventing/pages/eventing-debugging-and-diagnosability.adoc

@@ -1,16 +1,19 @@
 = Debugging and Diagnosability
 
 [abstract]
-Debugging and diagnostics in the Eventing Service comprises of  debugging functions, logging functions, and log redaction.
+Debugging and diagnostics in the Eventing Service comprises of debugging functions, functions log, and log redaction.
+
 
 [#debugging-functions]
-== *Debugging Functions*
+== 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*
+Port *9140* is the default Eventing debug port. To change the default port settings, see xref:eventing-debugging-and-diagnosability.adoc#modifydebugport[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.
@@ -19,14 +22,16 @@ This technique ensures that processing of the other data mutations in the cluste
 * 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 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.
+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*
 
-. From the *Couchbase Web Console* > *Eventing* page, click on the name of a deployed Function.
+=== Debugging a Function Using the Debug Option
+
+. To enable debugging, navigate to *Couchbase Web Console* > *Eventing* page, from the top banner, click *Settings* and check the *Enable Debugger* option.
+. From the *Eventing* page, click on the name of a deployed Function.
 The deployed Function expands to provide additional options.
 Click *Edit JavaScript*.
 +
@@ -44,23 +49,51 @@ image::debug_2.png[,300]
 +
 image::debug_3.png[,300]
 
-. Copy the URL from the Debugging pop-up and paste it into your Google Chrome browser.
+. Copy and paste the URL from the Debugging pop-up to your Google Chrome browser.
 +
 image::debug_4.png[,600]
 
 . 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.
+. 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).
+
+
+image::debug_sourcemap.png[,600]
+
+[#modifydebugport]
+=== *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:
+
+	. Stop Couchbase server.
+	. Navigate to the */opt/couchbase/etc/couchbase/static_config* file. This is the location where Couchbase Server picks up the configuration parameters.
+	. Edit the *static_config file* to add the new eventing_debug_port and the new port-number information.
+	. (Optional step) To remove any old configuration file, delete the */opt/couchbase/var/lib/couchbase/config/config.dat* file.
+	. 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]
---
-*Logging Functions*
+== Logging Functions
 
 The Eventing Service creates two different types of logs:
 
 * System Logs
 * Application Logs
 
-*System 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.
@@ -69,14 +102,14 @@ 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 xref:clustersetup:ui-logs.adoc[Using Logs].
 
-*Application 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.
+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.
 
@@ -123,7 +156,7 @@ A corresponding Application log file, *enrich_ip_nums.log*, gets created in the
 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]
 == Log Redaction