[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #4587: [Doc] Add two methods (log topic & CLI) for debugging functions

[GitBox <gi...@apache.org>]

Jennifer88huang commented on a change in pull request #4587: [Doc] Add two methods (log topic & CLI) for debugging functions
URL: https://github.com/apache/pulsar/pull/4587#discussion_r297130128
 
 

 ##########
 File path: site2/docs/functions-debugging.md
 ##########
 @@ -124,3 +130,322 @@ To use localrun like above programmatically please addd the following dependency
 For complete code samples, see [here](https://github.com/jerrypeng/pulsar-functions-demos/tree/master/debugging)
 
 In the future, debugging with localrun mode for Pulsar Functions written in other languages will be supported.
+
+## Use log topic
+
+The Pulsar Functions allows you to output the log information defined in functions to a specified log topic. Consumers can be configured to consume messages from a specified log topic to check the log information.
+
+![Pulsar Functions core programming model](assets/pulsar-functions-overview.png)
+
+**Example** 
+
+```text
+import org.apache.pulsar.functions.api.Context;
+import org.apache.pulsar.functions.api.Function;
+import org.slf4j.Logger;
+
+public class LoggingFunction implements Function<String, Void> {
+    @Override
+    public void apply(String input, Context context) {
+        Logger LOG = context.getLogger();
+        String messageId = new String(context.getMessageId());
+
+        if (input.contains("danger")) {
+            LOG.warn("A warning was received in message {}", messageId);
+        } else {
+            LOG.info("Message {} received\nContent: {}", messageId, input);
+        }
+
+        return null;
+    }
+}
+```
+
+As shown in the example below, you can get the logger via `context.getLogger()` and assign the logger to the `LOG` variable of `slf4j`, so you can define your desired log information in a function using the `LOG` variable. You also need to specify the topic to which the log information is produced.
+
+**Example** 
+
+```
+$ bin/pulsar-admin functions create \
+  --log-topic persistent://public/default/logging-function-logs \
+  # Other function configs
+```
+
+## Use Functions CLI
+
+The [Pulsar Functions CLI](reference-pulsar-admin.md#functions) helps you in debugging Pulsar functions with the following subcommands:
+
+* get
+* status
+* stats
+* list
+* trigger
+
+> **Tip**
+> 
+> For complete commands of **Pulsar Functions CLI**, see [here](reference-pulsar-admin.md#functions)。
+
+### get
+
+Get information about a Pulsar function.
+
+**Usage**
+
+```text
+$ pulsar-admin functions get options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--fqfn`|The Fully Qualified Function Name (FQFN) of a function
+|`--name`|The name of a function
+|`--namespace`|The namespace of a function
+|`--tenant`|The tenant of a function
+
+> **Tip**
+> 
+> `--fqfn` consists of `--name`, `--namespace` and `--tenant`, that is, you can specify only `--fqfn` or specify `--name`, `--namespace` and `--tenant` instead.
+
+**Example** 
+
+You can specify `--fqfn` to get information about a Pulsar function.
+
+```text
+$ ./bin/pulsar-admin functions get public/default/ExclamationFunctio6
+```
+Optionally, you can specify `--name`, `--namespace` and `--tenant` to get information about a Pulsar function.
+
+```text
+$ ./bin/pulsar-admin functions get \
+    --tenant public \
+    --namespace default \
+    --name ExclamationFunctio6
+```
+
+As shown below, the `get` command shows input, output, runtime, and other information about the _ExclamationFunctio6_ function.
+
+```text
+{
+  "tenant": "public",
+  "namespace": "default",
+  "name": "ExclamationFunctio6",
+  "className": "org.example.test.ExclamationFunction",
+  "inputSpecs": {
+    "persistent://public/default/my-topic-1": {
+      "isRegexPattern": false
+    }
+  },
+  "output": "persistent://public/default/test-1",
+  "processingGuarantees": "ATLEAST_ONCE",
+  "retainOrdering": false,
+  "userConfig": {},
+  "runtime": "JAVA",
+  "autoAck": true,
+  "parallelism": 1
+}
+```
+
+### status
+
+Check the current status of a Pulsar function.
+
+**Usage**
+
+```text
+$ pulsar-admin functions status options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--fqfn`|The Fully Qualified Function Name (FQFN) of a function
+|`--instance-id`|The instance ID of a function <br>If the `--instance-id` is not specified, it will get the IDs of all instances<br>
+|`--name`|The name of a function 
+|`--namespace`|The namespace of a function
+|`--tenant`|The tenant of a function
+
+**Example** 
+
+```text
+$ ./bin/pulsar-admin functions status \
+    --tenant public \
+    --namespace default \
+    --name ExclamationFunctio6 \
+```
+
+As shown below, the `status` command shows the number of instances, the number of running instances, the instance running under the _ExclamationFunctio6_ function, the number of received messages, the number of successfully processed messages, the number of system exceptions, the average latency and so on.
+
+```text
+{
+  "numInstances" : 1,
+  "numRunning" : 1,
+  "instances" : [ {
+    "instanceId" : 0,
+    "status" : {
+      "running" : true,
+      "error" : "",
+      "numRestarts" : 0,
+      "numReceived" : 1,
+      "numSuccessfullyProcessed" : 1,
+      "numUserExceptions" : 0,
+      "latestUserExceptions" : [ ],
+      "numSystemExceptions" : 0,
+      "latestSystemExceptions" : [ ],
+      "averageLatency" : 0.8385,
+      "lastInvocationTime" : 1557734137987,
+      "workerId" : "c-standalone-fw-23ccc88ef29b-8080"
+    }
+  } ]
+}
+```
+
+### stats
+
+Get the current stats of a Pulsar function.
+
+**Usage**
+
+```text
+$ pulsar-admin functions stats options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--fqfn`|The Fully Qualified Function Name (FQFN) of a function
+|`--instance-id`|The instance ID of a function <br>If the `--instance-id` is not specified, it will get the IDs of all instances<br>
+|`--name`|The name of a function 
+|`--namespace`|The namespace of a function
+|`--tenant`|The tenant of a function
+
+**Example**
+
+```text
+$ ./bin/pulsar-admin functions stats \
+    --tenant public \
+    --namespace default \
+    --name ExclamationFunctio6 \
+```
+
+The output is as below:
+
+```text
+{
+  "receivedTotal" : 1,
+  "processedSuccessfullyTotal" : 1,
+  "systemExceptionsTotal" : 0,
+  "userExceptionsTotal" : 0,
+  "avgProcessLatency" : 0.8385,
+  "1min" : {
+    "receivedTotal" : 0,
+    "processedSuccessfullyTotal" : 0,
+    "systemExceptionsTotal" : 0,
+    "userExceptionsTotal" : 0,
+    "avgProcessLatency" : null
+  },
+  "lastInvocation" : 1557734137987,
+  "instances" : [ {
+    "instanceId" : 0,
+    "metrics" : {
+      "receivedTotal" : 1,
+      "processedSuccessfullyTotal" : 1,
+      "systemExceptionsTotal" : 0,
+      "userExceptionsTotal" : 0,
+      "avgProcessLatency" : 0.8385,
+      "1min" : {
+        "receivedTotal" : 0,
+        "processedSuccessfullyTotal" : 0,
+        "systemExceptionsTotal" : 0,
+        "userExceptionsTotal" : 0,
+        "avgProcessLatency" : null
+      },
+      "lastInvocation" : 1557734137987,
+      "userMetrics" : { }
+    }
+  } ]
+}
+```
+
+### list
+
+List all Pulsar functions running under a specific tenant and namespace.
+
+**Usage**
+
+```text
+$ pulsar-admin functions list options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--namespace`|The namespace of a function
+|`--tenant`|The tenant of a function
+
+**Example** 
+
+```text
+$ ./bin/pulsar-admin functions list \
+    --tenant public \
+    --namespace default
+```
+As shown below, the `list` command returns three functions running under the _public_ tenant and the _default_ namespace.
+
+```text
+ExclamationFunctio1
+ExclamationFunctio2
+ExclamationFunctio3
+```
+
+### trigger
+
+Trigger a specified Pulsar function with a supplied value. This command simulates the execution process of a function and verifies a function.
+
+**Usage**
+
+```text
+$ pulsar-admin functions trigger options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--fqfn`|The Fully Qualified Function Name (FQFN) of a function
+|`--name`|The name of a function
+|`--namespace`|The namespace of a function
+|`--tenant`|The tenant of a function
+|`--topic`|The topic name that a function consumes from
+|`--trigger-file`|The path to a file that contains the data to trigger a function
+|`--trigger-value`|The value to trigger a function
+
+**Example** 
+
+```text
+$ ./bin/pulsar-admin functions trigger \
+    --tenant public \
+    --namespace default \
+    --name ExclamationFunctio6 \
+    --topic persistent://public/default/my-topic-1 \
+    --trigger-value "hello pulsar functions"
+```
+
+As shown below, the `trigger` command returns the following result:
+
+```text
+This is my function!
+```
+
+> #### **Note**
+> You must specify the [entire topic name](getting-started-pulsar.md#topic-names) when using the `--topic` option. Otherwise, the following error will be raised.
 
 Review comment:
   will be --> is?

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services