ramkumar-k-9286
commented
6 months ago Hi David @dmuelle
Incorporated comments.
Regards, Ramkumar
Closed dmuelle closed 6 months ago
ramkumar-k-9286
commented
6 months ago Hi David @dmuelle
Incorporated comments.
Regards, Ramkumar
dmuelle
commented
6 months ago Hi Ram- this is looking much better. Just a few suggestions.
The intro paragraph you added does a great job of setting the context and identifying the value for users. However- it's still a bit wordy. Try to revise it to use more direct language, with more concise sentences that use fewer words in fewer clauses. Also, try to avoid using expletive clauses with no clear referent ("It is..."). For example:
In highly distributed and event-driven application architectures, it is critical to manage data transfer between system components in a nonobstructive and responsive manner. Reactive messaging patterns make it possible by enabling applications to send, receive, and process messages asynchronously.
--->
Highly distributed and event-driven application architectures need to manage data transfer between system components responsively. Reactive messaging patterns enable applications to send, receive, and process messages asynchronously.
There's also at least one typo in the paragraph.
I'd recommend moving the first sentence of the next section to be the 2nd to last sentence of the introduction, eg
The Liberty-Kafka connector enables applications to send and receive messages from an Apache Kafka broker. It uses MicroProfile Reactive Messaging standards for robust, asynchronous communication in microservices architectures. The following section describes how to intergrate MicroProfile Reactive Messaging with Apache Kafka to send messages within and between applications.
This is a sentence fragment- revise to be a complete sentence:
By configuring a MicroProfile application as shown in the example, to connect to a Kafka broker at myKafkaBroker:9092 for messaging.
Revise to remove expletive "it is" clause:
To facilitate communication among applications, it is essential to configure microservices to send and receive messages through Kafka topics.
The incoming section doesn't provide any explanation for the deserializer proeprties- were these previously in the doc? They should be defined or explained somehow.
Revise to use active voice:
Similarly, for sending messages to a Kafka topic, an outgoing channel must be configured by using the Liberty-Kafka connector.
Run acrolinx here and fix error:
By setting up channels as demonstrated, you connect message channels directly to Kafka, offering precise control over the messaging channels. This enhances your application’s scalability and robustness by efficiently managing messages, whether incoming or outgoing.
Combine the two "For more information... " sentences, use a bulleted list if needed.
The bulleted list in the intro explains how you would want to use a shared library but it should tell you why, so the user can make an informed decision about which method to use.
Alternatively, you can integrate Kafka client libraries as a shared resource within the Open Liberty server.
I think we need to rethink this page.
This page is still using "properties" and "attributes" interchangeably but they are two different things.
the incoming/outgoing tables on the page contain the exact same properties except for unack/fastack.
But the description of context.service is different in each table.. without reference to incoming/outgoing... doesn't make sense. And the only explanation for the attribute is for outgoing... does it apply to incoming?
we shouldn't say " the concurrent-x.y feature ", use OL feature macros instead
The intro paragraph here is not specific to incoming properties but just repeats the general info from the page intro.
Needs an introductory sentence for any tables though, for a11y purposes.
To secure communication with Kafka brokers, set the necessary security properties in the microprofile-config.properties file to support various authentication protocols.
Does one server support multiple protocols? Im not sure but this sounds like yes. Need to confirm whether thats the case and revise as needed.
mention after the example that it configures and truststore location and password that are required for a secure connection. Also- does this section apply to TLS or just SSL? We should clarify as SSL is technically deprecated, though the term is still widely used.
mp.messaging.connector.liberty-kafka.bootstrap.servers=SSL\://kafka-boostrap-server\:39647
mp.messaging.connector.liberty-kafka.security.protocol=SSL
mp.messaging.connector.liberty-kafka.ssl.truststore.location=kafka-truststore.jks
mp.messaging.connector.liberty-kafka.ssl.truststore.password=kafka-teststore
mp.messaging.connector.liberty-kafka.ssl.truststore.location=kafka-truststore.jksWhy is the truststore location specified twice?
ramkumar-k-9286
commented
6 months ago Hi David @dmuelle
Incorporated most of the comments.
I have not done the same for : https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/liberty-kafka-connector-channel-properties.html I had some doubts. thought will discuss and incorporate those.
Regards, Ramkumar
dmuelle
commented
6 months ago This paragraph could still be more concise:
Highly distributed and event-driven application architectures need to manage data transfer between system components responsively. Reactive messaging patterns enable applications to send, receive, and process messages asynchronously. By decoupling system components, this method enhances scalability and resilience. Open Liberty incorporates this paradigm with its MicroProfile Reactive Messaging support. By using MicroProfile Config properties to configure reactive messaging channels in Open Liberty, it is possible to facilitate the administration and specification of how your applications interact with message brokers like Kafka. By configuring this setting, you can precisely tailor the behavior of reactive messaging to the requirements of your application, which facilitates streamlined data processing and communication. For more information, see MicroProfile Config properties for MicroProfile Reactive Messaging.
--->
Reactive messaging patterns enhance scalability and resilience by enabling applications to send, receive, and process messages asynchronously. Open Liberty incorporates this paradigm with its MicroProfile Reactive Messaging support. You can use MicroProfile Config properties to configure reactive messaging channels in Open Liberty and control how your applications interact with message brokers like Kafka. By configuring this setting, you can precisely tailor the behavior of reactive messaging to the requirements of your application. For more information, see MicroProfile Config properties for MicroProfile Reactive Messaging.
THere's no instruction to enbale the reactive messaging feature, though you can't use RM without it. This should be step 1
The application is able to can send and receive messages through Kafka, facilitating which facilitates event-driven communication.
Although Acrolinx doesn't flag it- this is a sentence fragment:
Offering precise control over the messaging channels, enhancing your application’s scalability and robustness by efficiently managing messages, whether incoming or outgoing.
For more information:---> For more information, see the following resources:
dmuelle
commented
6 months ago ramkumar-k-9286
commented
6 months ago Hi
Incorporated comments.
Regards, Ramkumar
we need to review the reactive messaging page and it's children top-to-bottom to make the overall story more concise and clear. There are redundancies among the existing pages that need to be removed or mitigated, and the information should align better with our guides for reactive.
Optimizing asynchronous communication with MicroProfile Reactive Messaging
Intro
Provide an additional paragraph (~3-5 sentences) to set the context for reactive messaging. Refer to https://openliberty.io/guides/microprofile-reactive-messaging.html#what-youll-learn andn https://openliberty.io/guides/microprofile-reactive-messaging.html#configuring-the-microprofile-reactive-messaging-connectors-for-kafka for context.
explain that reactive messaging channels in Open Liberty are configured by setting MicroProfile Config properties and link to the reactive msg config properties table.
Configure the Liberty-Kafka connector
liberty-kafkaconnector ---> Liberty-Kafka connector, except in code examplesSending and receiving messages among applications by using connectors
This section is really just a more detailed version of step 2. Instead of a separate section, integrate this information into step 2. Look for opportunities to remove any redundancies. So step 2 should show the minimal config, as it does now, and then detail common configuration options that are discussed in this section.
Troubleshooting
Im not sure this section is even needed- can this information be integrated into other sections of the page? Eg
group.idshows up in the examples, Multiple Reactive Messaging applications using the same Kafka server is discussed in the shared libraries section.Liberty-Kafka connector options and channel properties
Kafka connector security configuration
--> Liberty-Kafka connector security configuration
For configuring the Kafka connector and security in Open Liberty, you can focus on the distinction between channel-specific and connector-wide properties for tailored messaging behavior. ---> You can configure security for reactive messaging channels at both the channel level and the connector level.
I think these are protocols, not auth methods. And "For security" seems redundant. Try to revise this sentence to describe what is supported and what its for.
I think this one needs revision too. I know "make sure" was probably a way to get around saying "ensure", which acrolinx flags, but it's awkward here. The whole sentence can be more direct.
Does the user configure multiple methods? I dont think the conclusion paragraph here is really adding anything