Custom messaging services

Dynatrace automatically detects event-based message queue handlers. To get insight into applications using non-standard or non-event-based message queue handlers, you must first define a custom messaging service for your consumers.

Define a messaging service

To define a custom messaging service for your consumers

Go to Settings > Service detection > Custom service detection.
Select whether your messaging service is based on Java, .NET, or Node.js, and then select Define messaging service.
Define the name of your messaging service, choose your messaging technology from the list, and then select Find entry point.
Select the process that contains your entry point from the list and select Continue.
Find the class you want to instrument, select the required class or file, and select Continue.
Java .NET To instrument the class, you can
- Use the selected class for instrumenting methods of the selected class only.
- Use an implemented interface or superclass for instrumenting methods in any interface or superclass in the class hierarchy. In such cases, select Load inheritance to load all available superclasses and interfaces, and then select the one you need.
Node.js Select the file containing the custom service. Dynatrace presents a list of methods that can be used as a custom service. Select the desired method to complete the configuration.
Select the methods you want to instrument and select Finish.

See the requirements for Apache Kafka in the section below.

The Define custom service page displays the newly added entry point and methods.
optional Add more entry points if needed.
optional Restrict the new custom service to certain process groups. See the Restrict a custom service to specific process groups section below.
Review the entry point and methods to be instrumented.
In the lower-right corner of the page, select Save.
.NET Node.js Restart your consumer application so that the custom messaging service can be detected.

Apache Kafka

Custom messaging services for Apache Kafka must define a method in your code that is responsible for processing a single Kafka message. Only such methods can be used as an entry point for Kafka messaging services.

Select a method that has a Kafka org.apache.kafka.clients.consumer.ConsumerRecord as an argument. The full package path is required.

Select a method that has a Kafka ConsumeResult or Message object as an argument. The argument can be placed anywhere in the parameter list.

If the selected method doesn't have an argument, the context will be propagated via ThreadLocal (on .NET Framework 4.5) or via AsyncLocal (on .NET Framework 4.6+ and .NET Core 2.0+).

Asynchronous methods without any arguments or without the Kafka type arguments (ConsumeResult or Message) are only supported on .NET Framework 4.6+ and .NET Core 2.0+.

OneAgent version 1.233+ OneAgent automatically detects message handlers that are registered through the eachMessage-handler as an argument for consumer.run().

To detect an eachBatch-handler,

Create an exported function with EachMessagePayload as the first argument and select that function as a custom service. Note that for the function to be detectable, it must be imported from a file that's separate from the file where eachBatch-handler is stored.
Adapt the eachBatch-handler to call the exported function for every message in the batch.

// file: handlers.ts
export async function processSingleMessage(msg: EachMessagePayload) : Promise<void> {}

// file: eachBatchHandler.ts
import { processSingleMessage } from "./handlers";

async function eachBatchHandler(pl: EachBatchPayload): Promise<void> {
  /* ... */
  for (const message of pl.batch.messages) {
    /* ... */
    const singlePayload: EachMessagePayload = {
      message: message,
      topic: pl.batch.topic,
      partition: pl.batch.partition
    };
    await processSingleMessage(singlePayload);
    /* ... */
  }
}

Priority of messaging services

If you have several custom services defined, the evaluation goes from top to bottom, applying the first matching rule. If for some reason you have the same class and method defined in several custom services, make sure to prioritize the services accordingly.

Edit messaging service

You can edit any custom service at any time. For changes to take effect, you need to restart the affected processes, unless real-time updates are activated for Java and PHP. For .NET and Node.js, you must restart the process.

To edit a custom service, select the service's Edit button in the list of services. You can

Activate or deactivate existing entry points.
Add or delete entry points.
Add or delete methods in entry points.
Restrict the custom service to certain process groups. See the Restrict a custom service to specific process groups section below.

Real-time updates

Updates to Java and PHP custom messaging services can be applied in near real time, without process restarts. To activate this feature, go to Settings > Server-side service detection > Deep monitoring > Real-time updates to Java and PHP services and enable the dedicated switches.

Note that with real-time updates, you do not need to restart processes; however, such updates might cause CPU spikes when deployed.

Restrict a messaging service to specific process groups

You can restrict usage of any custom service to certain process groups. Custom service rules apply in specified process groups only and are ignored in other process groups. You can restrict a custom service when you create it or edit it.

To restrict a custom service

On the Define custom service or Edit service page, expand the Optionally restrict custom service rules by process groups dropdown menu.
Select Add process group and select the process group where you want to apply the custom service.
Select Add.
In the lower-right corner of the Define custom service or Edit service page, select Save.