Best practices

This section provides best practices for using the Kafka API.

Creating clients

Nuance recommends that you create a client that is dedicated to collecting logs. In addition, if multiple organizations need to access event logs for the same app ID, Nuance recommends that you create one client per organization.

For example, let’s say that two different groups in your company (research and professional services) need to access event logs. Create two different clients in the Manage Tab, one for each group, as follows:

For more information on creating clients, see Create a client ID.

Creating customer groups

If the same client must be shared between multiple organizations, Nuance recommends that you create different client groups, one per organization. Offsets are attached to a consumer group, so creating different groups will ensure that committing offsets will not impact other users.

Reusing access tokens

You must reuse the same access token across the different consumer processes. Do not acquire a new token at each API call. The same token can be used between the Kafka and AFSS APIs.

For example, if you are running 20 consumer processes for a specific app ID, generate a single access token and share it across the 20 consumers.

Nuance also recommends that you use the token until it expires. The expected token expiration validity period is returned in the token response.

Please note that the application may be limited to a certain maximum number of access token requests over a period of time.

Number of consumer instances

The number of consumer instances that you create should be less than or equal to the number of available partitions in a topic.

Nuance recommends that, for production applications, you use one consumer instance per partition.

Retention period

This section provides the retention periods for messages and audio files.

Messages

The retention period for messages is 28 days. To avoid any loss of data, consumers should make sure that the data is consumed within the retention period.

Consumers should use the same consumer group to maintain the offsets (all offsets are attached to the consumer group).

Audio files

The retention period for audio files is 14 days.

Graceful shutdown of consumers

Consumers should call the Delete Consumer and Unsubscribe endpoints for a graceful shutdown of the consumer.

Handling incoming event logs

Event logs are generated as your customers use your application; as such, they are often generated in waves and usually consist of a combination of peaks and slower periods.

Nuance recommends that you write your client so that it pulls data continuously; however, keep in mind that the client may not always be able to consume logs at the same rate as they are being produced. For example, a client may keep up with data collection during off-peak hours, fall behind in peak hours, and then catch up again in off-peak hours.

If your peak periods are so busy that your client cannot keep up, Nuance does not recommend that you use the log API for realtime monitoring.