Java agent API for asynchronous applications

Consider the method parallelStream() in the code snippet below. Because some of the calls to requestItemAsync() will occur on a separate thread, a token is created and passed to link that asynchronous work back to the requesting thread.

/**
* Example showing multi-threaded implementation of requesting data using a parallel {@link Stream}.
*/
@RequestMapping("parallel_stream")
@Trace(dispatcher = true) // starts a transaction
public ResponseEntity<String> parallelStream(@RequestParam("ids") List<Long> ids) {
    final Token token = NewRelic.getAgent().getTransaction().getToken();
    List<item> results = ids
            .parallelStream()
            .map(id -> requestItemAsync(id, token)) // requestItemAsync represents an  example of work being passed to another thread. The token is passed along to allow linking the work on the new thread back to the thread that the token was originally created on.
            .filter(item -> item != null)
            .collect(Collectors.toList());
    token.expire();
    return formattedResponse("parallel_stream", results);
}

The agent API calls in this sample are:

• @Trace(dispatcher = true): Tells the agent to start a transaction. For more on this method, see the Javadoc.
• getToken(): Creates the token which will link the work together. For more on this method, see the Javadoc.
• token.expire(): Expires the token. This allows the transaction to end. For more on this method, see the Javadoc.

The following code example shows requestItemAsync, which might execute on a separate thread from the requesting thread. For this reason, the token that was created in the previous code example is linked to the Transaction in requestItemAsync. Note that requestItemAsync() has the @Trace(async=true) annotation, which tells the agent to trace this method if it's linked to an existing transaction.

After parallelStream() collects all results, the token is expired. This is important because it makes sure the transaction doesn't stay open after parallelStream() completes.

@Trace(async = true)
private Item requestItemAsync(long id, Token token) {
    token.link();
    return requestItem(id);
}

The agent API calls in this sample are:

• @Trace(async = true): Starts a transaction. For more on this method, see the Javadoc.
• token.link(): Links the work being done in requestItemAsync() (which is executing on a different thread) to the requesting thread. For more on this method, see the Javadoc.

To view transaction trace details, go to: one.newrelic.com APM & services > (select an app) > Transactions > Transaction trace > Trace details.

Asynchronous activity is shown in the trace waterfall view by segments that overlap each other horizontally, in the time dimension.

It's not necessary to link methods that are on the same thread, but doing so will have no negative effect. It's often the case that a single token can be shared, like in the parallelStream() example.

The method below makes a call to an external service (in this case a database) using the method storeItem():

/**
* Example showing single threaded implementation of inserting data into a datasource.
*/
@RequestMapping("insert")
@Trace(dispatcher = true) //starts a transaction
public ResponseEntity insert(@RequestParam("id") Long id) {
    if (id != null) {
        storeItem(id);
        return new ResponseEntity<>("insert", HttpStatus.OK);
    } else {
        return new ResponseEntity<>("insert", HttpStatus.BAD_REQUEST);
    }
}

The goal in this case it to find out how long the Callable in the Lambda statement is waiting in the thread pool before executing, rather than determining how long storeItem() runs. For this reason, a segment is used instead of a token, and @Trace(async = true) is not necessary like it was for a token.

The agent API call in this sample is:

• @Trace(dispatcher = true): Starts a transaction. For more on this method, see the Javadoc.

The following code example shows a segment starting in the storeItem method to measure how long the Lambda statement is waiting in the thread pool. To stop timing the segment, you must call either .end() or .ignore(). If you don't want to report the segment as part of its parent transaction, call .ignore(). Otherwise, to report the segment as part of its parent transaction, call .end().

private void storeItem(long id) {
    Segment segment = NewRelic.getAgent().getTransaction().startSegment("storeItem");

    segment.reportAsExternal(DatastoreParameters
           .product("H2")
           .collection(null)
           .operation("insert")
           .instance("localhost", 8080)
           .databaseName("test")
           .build());

    // fire and forget
    DB_POOL.submit(() -> {
        segment.end();
        insertData(id);
    });
}

The agent API calls in this sample are:

• startSegment(...): Begins the segment that will time the code. For more on this method, see the Javadoc.
• reportAsExternal(DatastoreParameters()): Associates the time with a datastore external call This will show up in APM with datastore data. For more information, see reportAsExternal API.
• segment.end(): Stops timing this segment. For more on this method, see the Javadoc.

When the method completes, APM displays a transaction trace with one external call.