Thank you for this PR. As usual, we need PRs to link to an issue. I found issue #44090 to link it, so consider this resolved.

If we want people to use it in their custom templates, it would need to be documented on the tracing page and the the page to customize themes, and maybe the error template should have a commented-out section that people could enable when they want to show that information.

In addition, it would be great to have a test for that - and it would be so much easier if it would be showing automatically on the error page. So I'd say I'm +1 for item (2), which is adding it by default to the error page. Once that's done, TracingDistTest might a please for a test?

Let's also hear from others what they think.

One more comment: The trace ID might be considered user provided content, and we should ensure not to encode malicious content. Given that it is "32-character lowercase hexadecimal string representing a 16-byte value", I'd assume it is safe to reflect it to user. Happy to hear from other if they think differently.

Thanks for linking it to one of the issues, I'm used to an issue number being part of a commit message automatically linking an issue, so I forgot that that's necessary :)

In addition, it would be great to have a test for that - and it would be so much easier if it would be showing automatically on the error page. So I'd say I'm +1 for item (2), which is adding it by default to the error page. Once that's done, TracingDistTest might a please for a test?

maybe it would be a good idea to introduce a realm attribute (or a top level config flag?) along the lines of includeTraceIdInErrorTemplates so that users can opt in at the realm or keycloak level. If that flag is set, and the attribute is set in the freemarker context, we include a standard message like traceIdMessage=If contacting support, please include this identifier in your message: {0}. Either way (realm or config) would be fine with me, and both would yield themselves well for a test scenario

One more comment: The trace ID might be considered user provided content, and we should ensure not to encode malicious content. Given that it is "32-character lowercase hexadecimal string representing a 16-byte value", I'd assume it is safe to reflect it to user. Happy to hear from other if they think differently.

Personally, I've always assumed that the opentelemetry integration would reject inbound trace IDs that are not valid in some way. I've not personally verified it, but everything else just seems wrong, and I feel like I would have heard about CVEs with malicious trace IDs, if that was not the case. What remains is the potential DoS vector: If you accept trace IDs from the public internet without filtering, people can just always send 00000000000000000000000000000000 as a trace ID and confuse the tracing system. But that is, at least to me, outside the scope of this PR

Any opinion to also add the traceId to the freemarker context for emails? I don't really see a usecase for it to be included in any emails that Keycloak sends by default, but others may have use cases for their own custom email templates

I've added a small message template to error.ftl which contains the trace ID if it is present, as well as two test-cases to test for the presence (when tracing is enabled) as well as the absence (when tracing is disabled) of the message.

I did not add an additional flag to guard it, so for now, when tracing is enabled, and the theme is not changed, the message will always be displayed every time error.ftl is rendered and a valid trace context is available. I'm not sure if this is something that is wanted - if users don't want this part of the default template in their themes, they can always override it and not include the message in their theme.

I've also added a short paragraph on the tracing.adoc on how it can be used. Do you think it should be additionally also mentioned explicitly somewhere in themes.adoc?