Debug Pulsar Functions

Function startup information and captured stderr output is written to logs/functions/<tenant>/<namespace>/<function>/<function>-<instance>.log

This is useful for debugging why a function fails to start.

A Pulsar Function is a function with inputs and outputs, you can test a Pulsar Function in a similar way as you test any function.

For example, if you have the following Pulsar Function:

You can write a simple unit test to test Pulsar Function.

tip

Pulsar uses testng for testing.

  2. @Test
  3. public void testJavaNativeExclamationFunction() {
  4.    JavaNativeExclamationFunction exclamation = new JavaNativeExclamationFunction();
  5.    String output = exclamation.apply("foo");
  6.    Assert.assertEquals(output, "foo!");
  7. }

The following Pulsar Function implements the org.apache.pulsar.functions.api.Function interface.

  2. import org.apache.pulsar.functions.api.Context;
  3. import org.apache.pulsar.functions.api.Function;
  5. public class ExclamationFunction implements Function<String, String> {
  6.    @Override
  7.    public String process(String input, Context context) {
  8.        return String.format("%s!", input);
  9.    }
  10. }

In this situation, you can write a unit test for this function as well. Remember to mock the Context parameter. The following is an example.

tip

Pulsar uses testng for testing.

  2. @Test
  3. public void testExclamationFunction() {
  4.    ExclamationFunction exclamation = new ExclamationFunction();
  5.    String output = exclamation.process("foo", mock(Context.class));
  6.    Assert.assertEquals(output, "foo!");
  7. }

When you run a Pulsar Function in localrun mode, it launches an instance of the Function on your local machine as a thread.

In this mode, a Pulsar Function consumes and produces actual data to a Pulsar cluster, and mirrors how the function actually runs in a Pulsar cluster.

note

Currently, debugging with localrun mode is only supported by Pulsar Functions written in Java. You need Pulsar version 2.4.0 or later to do the following. Even though localrun is available in versions earlier than Pulsar 2.4.0, you cannot debug with localrun mode programmatically or run Functions as threads.

You can launch your function in the following manner.

  2. FunctionConfig functionConfig = new FunctionConfig();
  3. functionConfig.setName(functionName);
  4. functionConfig.setInputs(Collections.singleton(sourceTopic));
  5. functionConfig.setClassName(ExclamationFunction.class.getName());
  6. functionConfig.setRuntime(FunctionConfig.Runtime.JAVA);
  7. functionConfig.setOutput(sinkTopic);
  9. LocalRunner localRunner = LocalRunner.builder().functionConfig(functionConfig).build();
  10. localRunner.start(true);

So you can debug functions using an IDE easily. Set breakpoints and manually step through a function to debug with real data.

The following example illustrates how to programmatically launch a function in localrun mode.

  2. public class ExclamationFunction implements Function<String, String> {
  4.    @Override
  5.    public String process(String s, Context context) throws Exception {
  6.        return s + "!";
  7.    }
  9. public static void main(String[] args) throws Exception {
  10.     FunctionConfig functionConfig = new FunctionConfig();
  11.     functionConfig.setName("exclamation");
  12.     functionConfig.setInputs(Collections.singleton("input"));
  13.     functionConfig.setClassName(ExclamationFunction.class.getName());
  14.     functionConfig.setRuntime(FunctionConfig.Runtime.JAVA);
  15.     functionConfig.setOutput("output");
  17.     LocalRunner localRunner = LocalRunner.builder().functionConfig(functionConfig).build();
  18.     localRunner.start(false);
  19. }

To use localrun mode programmatically, add the following dependency.

  1. <dependency>
  2.    <groupId>org.apache.pulsar</groupId>
  3.    <artifactId>pulsar-functions-local-runner</artifactId>
  4.    <version>${pulsar.version}</version>
  5. </dependency>

For complete code samples, see .

note

In Pulsar Functions, you can generate log information defined in functions to a specified log topic. You can configure consumers to consume messages from a specified log topic to check the log information.

Example

  2. import org.apache.pulsar.functions.api.Context;
  3. import org.apache.pulsar.functions.api.Function;
  4. import org.slf4j.Logger;
  6. public class LoggingFunction implements Function<String, Void> {
  7.     @Override
  8.     public void apply(String input, Context context) {
  9.         Logger LOG = context.getLogger();
  10.         String messageId = new String(context.getMessageId());
  12.         if (input.contains("danger")) {
  13.             LOG.warn("A warning was received in message {}", messageId);
  14.         } else {
  15.             LOG.info("Message {} received\nContent: {}", messageId, input);
  16.         }
  18.         return null;
  19.     }
  20. }

As shown in the example above, you can get the logger via context.getLogger() and assign the logger to the variable of slf4j, so you can define your desired log information in a function using the LOG variable. Meanwhile, you need to specify the topic to which the log information is produced.

Example

The message published to log topic contains several properties for better reasoning:

  • loglevel — the level of the log message.
  • fqn — fully qualified function name pushes this log message.
  • instance — the ID of the function instance pushes this log message.

With , you can debug Pulsar Functions with the following subcommands:

  • get
  • status
  • stats
  • list
  • trigger
tip

For complete commands of Pulsar Functions CLI, see 。

Get information about a Pulsar Function.

Usage

  2. $ pulsar-admin functions get options

Options

tip

--fqfn consists of --name, --namespace and --tenant, so you can specify either --fqfn or --name, --namespace and --tenant.

Example

You can specify --fqfn to get information about a Pulsar Function.

  2. $ ./bin/pulsar-admin functions get public/default/ExclamationFunctio6

Optionally, you can specify --name, --namespace and --tenant to get information about a Pulsar Function.

  2. $ ./bin/pulsar-admin functions get \
  3.     --tenant public \
  4.     --namespace default \
  5.     --name ExclamationFunctio6

As shown below, the get command shows input, output, runtime, and other information about the ExclamationFunctio6 function.

  2. {
  3.   "tenant": "public",
  4.   "namespace": "default",
  5.   "name": "ExclamationFunctio6",
  6.   "className": "org.example.test.ExclamationFunction",
  7.   "inputSpecs": {
  8.     "persistent://public/default/my-topic-1": {
  9.       "isRegexPattern": false
  10.     }
  11.   },
  12.   "output": "persistent://public/default/test-1",
  13.   "processingGuarantees": "ATLEAST_ONCE",
  14.   "retainOrdering": false,
  15.   "userConfig": {},
  16.   "runtime": "JAVA",
  17.   "autoAck": true,
  18.   "parallelism": 1
  19. }

Check the current status of a Pulsar Function.

  2. $ pulsar-admin functions status options

Options

Example

  2. $ ./bin/pulsar-admin functions status \
  3.     --tenant public \
  4.     --namespace default \
  5.     --name ExclamationFunctio6 \

As shown below, the status command shows the number of instances, running instances, the instance running under the ExclamationFunctio6 function, received messages, successfully processed messages, system exceptions, the average latency and so on.

  2. {
  3.   "numInstances" : 1,
  4.   "numRunning" : 1,
  5.   "instances" : [ {
  6.     "instanceId" : 0,
  7.     "status" : {
  8.       "error" : "",
  9.       "numRestarts" : 0,
  10.       "numReceived" : 1,
  11.       "numSuccessfullyProcessed" : 1,
  12.       "numUserExceptions" : 0,
  13.       "latestUserExceptions" : [ ],
  14.       "numSystemExceptions" : 0,
  15.       "latestSystemExceptions" : [ ],
  17.       "lastInvocationTime" : 1557734137987,
  18.       "workerId" : "c-standalone-fw-23ccc88ef29b-8080"
  19.     }
  20.   } ]
  21. }

Get the current stats of a Pulsar Function.

Usage

Options

Example

  2. $ ./bin/pulsar-admin functions stats \
  3.     --tenant public \
  4.     --namespace default \
  5.     --name ExclamationFunctio6 \

The output is shown as follows:

  2. {
  3.   "receivedTotal" : 1,
  4.   "processedSuccessfullyTotal" : 1,
  5.   "systemExceptionsTotal" : 0,
  6.   "userExceptionsTotal" : 0,
  7.   "avgProcessLatency" : 0.8385,
  8.   "1min" : {
  9.     "receivedTotal" : 0,
  10.     "processedSuccessfullyTotal" : 0,
  11.     "systemExceptionsTotal" : 0,
  12.     "userExceptionsTotal" : 0,
  13.     "avgProcessLatency" : null
  14.   },
  15.   "lastInvocation" : 1557734137987,
  16.   "instances" : [ {
  17.     "instanceId" : 0,
  18.     "metrics" : {
  19.       "receivedTotal" : 1,
  20.       "processedSuccessfullyTotal" : 1,
  21.       "systemExceptionsTotal" : 0,
  22.       "userExceptionsTotal" : 0,
  23.       "avgProcessLatency" : 0.8385,
  24.       "1min" : {
  25.         "receivedTotal" : 0,
  26.         "processedSuccessfullyTotal" : 0,
  27.         "systemExceptionsTotal" : 0,
  28.         "userExceptionsTotal" : 0,
  29.         "avgProcessLatency" : null
  30.       },
  31.       "lastInvocation" : 1557734137987,
  32.       "userMetrics" : { }
  33.     }
  34.   } ]
  35. }

List all Pulsar Functions running under a specific tenant and namespace.

Usage

  2. $ pulsar-admin functions list options

Options

Example

  2. $ ./bin/pulsar-admin functions list \
  3.     --tenant public \
  4.     --namespace default

As shown below, the list command returns three functions running under the public tenant and the default namespace.

  2. ExclamationFunctio1
  3. ExclamationFunctio2
  4. ExclamationFunctio3

Trigger a specified Pulsar Function with a supplied value. This command simulates the execution process of a Pulsar Function and verifies it.

Usage

  2. $ pulsar-admin functions trigger options

Options

Example

  2. $ ./bin/pulsar-admin functions trigger \
  3.     --tenant public \
  4.     --namespace default \
  5.     --name ExclamationFunctio6 \
  6.     --topic persistent://public/default/my-topic-1 \
  7.     --trigger-value "hello pulsar functions"
note

You must specify the entire topic name when using the --topic option. Otherwise, the following error occurs.

  2. Function in trigger function has unidentified topic