You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by si...@apache.org on 2019/06/26 09:55:42 UTC
[pulsar] branch master updated: [Doc] Add two methods (log topic &
CLI) for debugging functions (#4587)
This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new a1a3f3a [Doc] Add two methods (log topic & CLI) for debugging functions (#4587)
a1a3f3a is described below
commit a1a3f3aff5f99f5aea2b1b6fd75ddd150506cfe3
Author: Anonymitaet <50...@users.noreply.github.com>
AuthorDate: Wed Jun 26 17:55:35 2019 +0800
[Doc] Add two methods (log topic & CLI) for debugging functions (#4587)
---
site2/docs/functions-debugging.md | 327 +++++++++++++++++++++++++++++++++++++-
1 file changed, 326 insertions(+), 1 deletion(-)
diff --git a/site2/docs/functions-debugging.md b/site2/docs/functions-debugging.md
index 675513c..a317ccd 100644
--- a/site2/docs/functions-debugging.md
+++ b/site2/docs/functions-debugging.md
@@ -4,6 +4,12 @@ title: How to debug Pulsar Functions
sidebar_label: Debugging
---
+You can use the following methods to debug Pulsar Functions:
+
+* [Use unit test](functions-debugging.md#use-unit-test)
+* [Debug with localrun mode](functions-debugging.md#debug-with-localrun-mode)
+* [Use log topic](functions-debugging.md#use-log-topic)
+* [Use Functions CLI](functions-debugging.md#use-functions-cli)
## Use unit test
@@ -121,6 +127,325 @@ 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)
+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
+
+Pulsar Functions allow 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.
+
+
+
+**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 above, 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 Pulsar Function
+|`--name`|The name of a Pulsar Function
+|`--namespace`|The namespace of a Pulsar Function
+|`--tenant`|The tenant of a Pulsar 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 Pulsar Function
+|`--instance-id`|The instance ID of a Pulsar Function <br>If the `--instance-id` is not specified, it will get the IDs of all instances<br>
+|`--name`|The name of a Pulsar Function
+|`--namespace`|The namespace of a Pulsar Function
+|`--tenant`|The tenant of a Pulsar 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 Pulsar Function
+|`--instance-id`|The instance ID of a Pulsar Function <br>If the `--instance-id` is not specified, it will get the IDs of all instances<br>
+|`--name`|The name of a Pulsar Function
+|`--namespace`|The namespace of a Pulsar Function
+|`--tenant`|The tenant of a Pulsar 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 Pulsar Function
+|`--tenant`|The tenant of a Pulsar 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 Plusar Function and verifies it.
+
+**Usage**
+
+```text
+$ pulsar-admin functions trigger options
+```
+
+**Options**
+
+|Flag|Description
+|---|---
+|`--fqfn`|The Fully Qualified Function Name (FQFN) of a Pulsar Function
+|`--name`|The name of a Pulsar Function
+|`--namespace`|The namespace of a Pulsar Function
+|`--tenant`|The tenant of a Pulsar Function
+|`--topic`|The topic name that a Pulsar Function consumes from
+|`--trigger-file`|The path to a file that contains the data to trigger a Pulsar Function
+|`--trigger-value`|The value to trigger a Pulsar 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 is raised.
+>
+>```text
+>Function in trigger function has unidentified topic
+>
+>Reason: Function in trigger function has unidentified topic
+>```