[APM] Provide better guidance for transactions named unknown route

[eyalkoren]

Summary of the problem
As I user I want a clear hint for possible resolution for transactions that are not properly named, specifically - such named <HTTP_METHOD> unknown route:

Typically, we get such transactions when the capturing agent doesn't support a specific framework or use case. However, we have ways to work around these issues, that are agent specific, for example:

• Set a config option to fallback to use the URL path for transaction name
• Use an API to manually name improperly named transactions

Since the unknown route string is aligned across agents (and we will make sure to align if there are exceptions), it would be very useful if the UI will contain a link to the proper troubleshooting documentation (e.g. in the Java agent docs), preferably for the relevant agent based on the event metadata.
This fits well for other efforts we now make to provide such in-UI guidance for data onboarding.

[elasticmachine]

Pinging @elastic/observability-design (design)

[formgeist]

@eyalkoren Thanks for raising this - I've moved this into our design backlog and will keep it in mind for upcoming planning. I think we'd need an effort to identify possible other "signs of incomplete data or use" but this is a good start.

[elasticmachine]

Pinging @elastic/apm-ui (Team:apm)

[yngrdyn]

I don't know is this is applicable to all apm agents but I tried to find documentation about it for agents like go, python or ruby and I didn't find information related to this. Would it be worthy to align the documentation on this matter for all the agents? If we do, we could easily build an agent based doc link for troubleshooting

[yngrdyn]

@elastic/apm-agent-devs would it be possible to have a troubleshooting section for unknown route for every agent as we have in java agent? This will enable us in the task of generating a link to the proper agent documentation whenever we encounter unknown route.

[gregkalapos]

@yngrdyn what's the idea here? Would we link to those docs from the UI in case we show transactions with unknown route?

Would it be worthy to align the documentation on this matter for all the agents?

If I understand the idea correctly, then yeah, I think that makes sense.

Fyi I added this topic to the next agents weekly. I'll try to figure out which agents have such transactions (I think most of them do), and then create issues to add those docs and link the issues here.

[yngrdyn]

hey @gregkalapos,

yes, the idea is to provide a link for the documentation from the UI whenever we get unknown route transaction name, something for example like

[gregkalapos]

Opened an issue to document this for .NET: elastic/apm-agent-dotnet#2179

[trentm]

I've added elastic/apm-agent-nodejs#3619 for the Node.js APM agent.