Signals processing

[LikeTheSalad]

Description:

Feature addition - Tools for globally processing signal data items in order to allow for:

• Modification
• Filtering

As part of the Splunk Android SDK donation, some of the items requested from the community were related to moving generic tools used in the Splunk code over to the java-contrib repo. Some of these tools enabled filtering spans based on predefined predicates as well as adding attributes to them.

The proposed tools in this PR aren't exact replicas of the classes used in the Splunk SDK although they aim to enable the same use cases (signal modification and filtering) not only for spans but also for logs and metrics in a quite generic way that should allow for more use cases to be supported, albeit in a less verbose way, but flexible enough to be further extended to add more specific use cases on top, such as "rejectSpansNamed()" and "rejectSpansWithAttributesMatching()" for example, as some of the ones currently available in here.

There are no defined guidelines on how to accomplish this functionality, so what I'm proposing here is just a way to do so that I consider simple and flexible enough to accommodate different use cases. So I'm open to any alternatives or adjustments that could improve this feature in any way!

How it works

There's an Interceptor interface that can modify or eliminate a signal right before it gets exported. This example shows how to modify and/or filter a span out from exporting:

    InMemorySpanExporter myExporter = InMemorySpanExporter.create();
    ComposableInterceptor interceptor = new ComposableInterceptor();
    Tracer tracer = createTracerWithExporter(new InterceptableSpanExporter(myExporter, interceptor));

    // This interceptor will modify all the spans by adding a new attr.
    interceptor.add(
        spanData -> {
          ModifiableSpanData modified = new ModifiableSpanData(spanData);
          modified.attributes.put("global.attr", "from interceptor");
          return modified;
        });

    // This interceptor will prevent some spans from getting exported:
    interceptor.add(
        spanData -> {
          if (spanData.getName().endsWith("deleted")) {
            return null;
          }
          return spanData;
        });

     // All the spans will go through both interceptors when getting exported
    tracer.spanBuilder("My Span").startSpan()//etc...

You can find more examples in the tests added as part of this PR.

Existing Issue(s):

Testing:

Unit tests

Documentation:

Outstanding items:

[breedx-splk]

Let's use composition here instead. Recommend:

• Rename Interceptable to MultiInterceptor or something and make it final It might also implement Interceptor<Collection<T>>
• Remove extends .... from each of the exporters.
• Add constructor arg and field of type MultiInterceptor (or the interface) to each exporter
• Call interceptor.interceptAll() in the export method.

[breedx-splk]

You can add me here. I think the literal ? breaks things.

[LikeTheSalad]

Thanks! You're added now.

[breedx-splk]

I strongly believe that we should not use object inheritance as a mechanism for reusing code.

[LikeTheSalad]

Generally speaking, I understand the benefits of composition over inheritance, although I still believe that there are cases where inheritance makes more sense. I think the problem comes when people start adding more than one responsibility to a base class. That being said though, after my recent changes to this PR I realized that it was actually better not to use inheritance for this use case 😅 so thanks for your input! Though I guess my point is that the best approach might vary depending on the use case.

[breedx-splk]

I could think of a few contrived scenarios where order might matter. I'd use a list.

[LikeTheSalad]

Makes sense, I've added the changes into ComposableInterceptor.

[LikeTheSalad]

Let's use composition here instead. Recommend:

Rename Interceptable to MultiInterceptor or something and make it final It might also implement Interceptor<Collection>
Remove extends .... from each of the exporters.
Add constructor arg and field of type MultiInterceptor (or the interface) to each exporter
Call interceptor.interceptAll() in the export method.

Sounds good, I've applied the changes you mentioned with some small diffs, for the multi interceptor name I went with "ComposableInterceptor" and for the exporters' constructor arg for an interceptor I went with the interface Interceptor instead of any implementation to allow users to use any kind of implementation they'd like. Also, the interceptAll method was made a default Interceptor method since it seems appropriate as a reusable functionality regardless of the implementation.

[LikeTheSalad]

Thanks @mateuszrzeszutek ! I've applied your suggestions.

[mateuszrzeszutek]

👍

[trask]

@breedx-splk could you give this another look? thx