6928 documentation of mp reactive messaging stream operators 3-6

6928 documentation of mp reactive messaging stream operators 3-6

#6928

modules/ROOT/pages/liberty-kafka-connector-channel-properties.adoc

@@ -0,0 +1,137 @@
+// Copyright (c) 2024 IBM Corporation and others.
+// Licensed under Creative Commons Attribution-NoDerivatives
+// 4.0 International (CC BY-ND 4.0)
+//    https://creativecommons.org/licenses/by-nd/4.0/
+//
+// Contributors:
+// IBM Corporation
+//
+:page-layout: general-reference
+:page-type: general
+:page-description: The Liberty-kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
+:page-categories: MicroProfile Reactive Messaging
+:seo-title: Liberty-kafka connector options and channel properties
+:seo-description: The Liberty-kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
+
+
+
+[#connectoroptionschannelprop]
+= Liberty-kafka connector options and channel properties
+
+The `Liberty-kafka` connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
+
+You can use all these options as attributes on either the connector or a channel that uses the `Liberty-kafka` connector. If you specify the option on both the channel and the connector, the channel takes precedence.
+
+.Properties supported by the `liberty-kafka` connector for incoming channels
+[cols="a,a,a",width="100%"]
+|===
+|Property Name |Default |Description
+
+|topic
+|The name of the channel.
+|The Kafka topic that the channel is to either send or receive messages from.
+
+|unacked.limit
+|Defaults to the value of `max.poll.records` if set, or to 500.
+|The number outstanding unacknowledged messages. 
+ {empty} +
+ If this limit is reached, the connector stops retrieving records from Kafka until some messages are acknowledged.
+
+|fast.ack
+|- MicroProfile Reactive Messaging 1.0 - `False`
+ {empty} +
+ - MicroProfile Reactive Messaging 3.0 - `true`
+|Defines the acknowledge behavior of the `liberty-kafka` connector within the MicroProfile Reactive Messaging framework for `incoming` channels in relation to activities with the Kafka topic.
+ {empty} +
+If the value of `fast.ack` is `false`, the acknowledgment is not reported as complete until the partition offset is committed to the Kafka broker. If an error occurs during this process, then the acknowledgment is reported as failed.
+ {empty} +
+If the value of `fast.ack` is `true`, and the acknowledgment is reported as complete when the Kafka Connector receives the acknowledgment signal.
+
+|context.service
+|If the `concurrent-x.y` feature is enabled. the default context service is used.
+ {empty} +
+ If the concurrent feature is not enabled, the built in Liberty context service is used with a set list of context types to capture and apply around asynchronous tasks.
+|Enabling the concurrent feature is needed for the `context.service` option to be effective for the `liberty-kafka` connector. 
+ {empty} +
+This setting specifies the Context Service that is used for Asynchronous tasks.
+
+|
+|Uses the Kafka Client default
+|All other properties are passed directly as config parameters to the KafkaConsumer API. A list of required and optional properties can be found in the http://kafka.apache.org/documentation.html#consumerconfigs[Kafka documentation].
+
+|===
+
+
+.Properties supported by the `liberty-kafka` connector for outgoing channels
+[cols="a,a,a",width="100%"]
+|===
+|Property Name |Default |Description
+
+|topic
+|The name of the channel.
+|The Kafka topic that the channel is to either send or receive messages from.
+
+
+|context.service
+|If the `concurrent-x.y` feature is enabled. the default context service is used.
+ {empty} +
+ If the concurrent feature is not enabled, the built in Liberty context service is used with a set list of context types to capture and apply around asynchronous tasks.
+|Enabling the concurrent feature is needed for the `context.service` option to be effective for the `liberty-kafka` connector. 
+ {empty} +
+This setting specifies the Context Service that is used for Asynchronous tasks.
+
+|
+|Uses the Kafka Client default
+|All other properties are passed directly as config parameters to the KafkaProducer API. A list of required and optional properties can be found in the http://kafka.apache.org/documentation.html#producerconfigs[Kafka documentation].
+
+|===
+
+
+== fast.ack
+Properties like `fast.ack` allow for control over message acknowledgment processes, improving the efficiency of message processing. 
+
+In the following example, in the `microprofile-config.properties` file of the application, the `fast.ack` setting is defaulted to `false` for the connector, affecting all channels in the application. However, for a distinct incoming channel called `foo`, this setting is overridden to `true`. This alteration favors a quicker acknowledgment approach, which enhances the handling performance for messages that arrive on this channel.
+
+----
+mp.messaging.connector.liberty-kafka.fast.ack=false
+
+mp.messaging.incoming.foo.connector=liberty-kafka
+mp.messaging.incoming.foo.fast.ack=true
+----
+
+== context.service
+The `context.service` attribute specifies the Context Service for asynchronous operations, critical for performance tuning. 
+
+Context Services that are defined within the application itself cannot be used with the `liberty-kafka` connector. 
+
+In the following example, the `server.xml` file defines three different context services, each with a unique identifier (`rst`, `uvw`, and `xyz`).
+
+server.xml
+----
+<contextService id=“rst”/>
+<contextService id=“uvw”/>
+<contextService id=“xyz”/>
+----
+
+The `microprofile-config.properties` file is part of the application's configuration and specifies how MicroProfile features should be used within the application.
+
+microprofile-config.properties
+----
+mp.messaging.connector.liberty-kafka.context.service=rst
+
+mp.messaging.incoming.def.connector=liberty-kafka
+mp.messaging.incoming.foo.connector=liberty-kafka
+mp.messaging.incoming.foo.context.service=uvw
+mp.messaging.outgoing.bar.connector=liberty-kafka
+mp.messaging.outgoing.bar.context.service=xyz
+----
+
+The property `mp.messaging.connector.liberty-kafka.context.service=rst` indicates that the Kafka connector that is used for handling messaging between services uses the `rst`` context service by default for its operations.
+
+The application has three channels (`def`, `foo`, and `bar`), which are logical endpoints for incoming and outgoing messages. The configuration for these channels specifies which Kafka connector to use (`liberty-kafka`) and for two of the channels (`foo` and `bar`), overrides the default context service with their own (`uvw` and `xyz`, respectively).
+
+The `def` channel does not specify its own `context.service`, so it inherits the default one (`rst`) defined at the connector level.
+
+By defining separate context services, the application can isolate certain operations or configurations, which can be useful in complex applications or during integration with external systems.
+
+These configurations demonstrate the flexibility and control that you have over message processing in Open Liberty applications.