Configurable Span Naming via Method params

[agent-adam]

Is your feature request related to a problem? Please describe.

The OpenTelemetry Java agent already excels in automatically generating spans around specified methods via the otel.instrumentation.methods.include configuration. This feature, however, currently assigns span names directly from method names, a default behavior that, while straightforward, does not leverage the potential depth of observability that could be achieved by more dynamically naming spans. Dynamic span naming could utilize method parameters or returned values, offering richer insights, particularly in complex application scenarios.

To enhance this capability, I propose the introduction of configurable span naming based on method parameter values or return values, inspired by similar features found in APM tools like AppDynamics' SplitbyPOJOMethodCall. This enhancement would permit the specification of span naming directly within configuration files, greatly simplifying the process of instrumentation by allowing for more descriptive and contextually relevant span names without additional coding.

Describe the solution you'd like

Feature Outline

I propose extending the otel.instrumentation.methods.include configuration to allow specifying a template for dynamic span naming directly within the method specification. This enhancement would enable users to define span names based on the values of method parameters or even values obtained through getter chains on those parameters.

Proposed Syntax

The new syntax would allow including a spanName attribute within the method specification, where the span name can be dynamically constructed using indices to refer to method parameters and/or employing getter chains for more complex objects. Here's how the proposed syntax looks:

otel.instrumentation.methods.include=
my.package.OrderProcessor[processOrder(spanName="OrderProcess-{0}")],
my.package.CustomerService[handleInquiry(spanName="SupportInquiry-{2}")],
my.package.OrderService[submitOrder(spanName="OrderSubmit-{0.getOrderDetails().getType()}")]

• processOrder(spanName="OrderProcess-{0}"): Automatically names spans based on the value of the first parameter of the processOrder method.
• handleInquiry(spanName="SupportInquiry-{2}"): Names spans based on the third parameter of the handleInquiry method.
• submitOrder(spanName="OrderSubmit-{0.getOrderDetails().getType()}"): Demonstrates a complex example where the span name is derived using a recursive getter chain on the first parameter.

Describe alternatives you've considered

No response

Additional context

No response

[steverao]

Thank you for your suggestion! For your solution mentioned above, first, there is a specification description about span name, If we provide such an approach for users to generate their span names by using parameters, it will break the specification and cause some problems.

Dynamic span naming could utilize method parameters or returned values, offering richer insights, particularly in complex application scenarios.

For the purpose, whether recording these informations as attributes is a better solution? just like @SpanAttribute https://opentelemetry.io/docs/languages/java/automatic/annotations/#adding-attributes-to-the-span-with-spanattribute

[agent-adam]

Thanks for the feedback @steverao !!

I recognize the importance of adhering to the specification when naming spans. Currently, users like myself are directly setting the span name in the code, which already gives us the ability to either comply with or deviate from the specification. For example:

public void handleAppCall( AppServerProcessor appServerProcessor) {
    String realRequestRoute = appServerProcessor.getClientRequest().getRouteName();
    Span span = tracer.spanBuilder(realRequestRoute).startSpan();
    .....

In this example, the span name accurately reflects the work performed by my application, as outlined in the specification. However, achieving this level of instrumentation currently necessitates a code change. The proposal aims to transition this logic to the configuration file while maintaining the same naming conventions.

otel.instrumentation.methods.include=my.package.MyService[handleAppCall(spanName="{0.getClientRequest().getRouteName()}")]

I acknowledge that while this flexibility greatly simplifies user processes, it could lead to custom spans names that deviate from the specification. However, this is something users can already achieve through existing methods.

[steverao]

Currently, users like myself are directly setting the span name in the code, which already gives us the ability to either comply with or deviate from the specification.

I understand your opinion, we really can't do anything when users set span name in their codes, but for the situation you mentioned above, I think it may be a better choice by recording these informations as attributes just like @SpanAttribute in annotation approach. But the issue is indeed worthy of discussion! @open-telemetry/java-instrumentation-approvers WDYT?

[trask]

otel.instrumentation.methods.include=my.package.MyService[handleAppCall(spanName="{0.getClientRequest().getRouteName()}")]

we're currently holding off on introducing complex configuration like this until the OpenTelemetry (yaml-based) Configuration is available for use in the Java agent.

I'm personally interested in being able to set SpanKind for methods instrumented via otel.instrumentation.methods.include.

setting the span name would require some kind of templating mechanism, it might be worth considering creating a Java implementation of OTTL, since that could be helpful in other use cases as well

[johnbley]

We (Splunk/Cisco) recently developed a solution to this problem in which instrumentation (including custom attributes) can be applied via a yml config file: https://github.com/signalfx/splunk-otel-java/tree/main/instrumentation/nocode

I'd be very happy to donate this work upstream in whatever shape the maintainers would want.

[trask]

yes, I totally support this feature!

my wishlist would include integration into declarative configuration and potentially OTTL instead of JEXL even if it's not as powerful

[johnbley]

yes, I totally support this feature!

my wishlist would include integration into declarative configuration and potentially OTTL instead of JEXL even if it's not as powerful

I would happily migrate the configuration away from an external file into this new method of schemaed configuration - can you point me to an example in otel-java-instrumentation that I can adapt for these needs?

I'm not sure if OTTL is the best choice given that the goal is to specify invocation of Java methods/statements and not process otel signals. I surveyed expression libraries that (a) looked or could be configured to look as much like Java as possible (e.g., not a different scripting language in its own right), and (b) were compatible with the Apache 2 licensing of otel, and landed on jexl. I tried to balance "expressivity for this niche instrumentation case" against "not wanting to put a full Java compiler and interpreter into the runtime".

In terms of how upstreaming this capability could work, I would probably break it into two PRs (one for config and infrastructure and the second for actually wiring up expression evaluation into span creation) since the size of the feature including tests is pushing 1000 lines of code which might be too big for a single careful review.

[trask]

can you point me to an example in otel-java-instrumentation that I can adapt for these needs?

I don't think we've used it yet in Java instrumentation, but check out the incubating ConfigProvider/GlobalConfigProvider that just landed in the latest SDK release (open-telemetry/opentelemetry-java#6549), and ping me and/or @jack-berg if you run into issues as we are excited to start exercising it

I'm not sure if OTTL is the best choice given that the goal is to specify invocation of Java methods/statements and not process otel signals. I surveyed expression libraries that (a) looked or could be configured to look as much like Java as possible (e.g., not a different scripting language in its own right), and (b) were compatible with the Apache 2 licensing of otel, and landed on jexl. I tried to balance "expressivity for this niche instrumentation case" against "not wanting to put a full Java compiler and interpreter into the runtime".

makes sense 👍