document RUM integration for server-side HTML rendering

[SylvainJuge]

With server-side HTML rendering, the integration of RUM requires to make the generated HTML page include the trace ID, span ID and sampling decision directly into the RUM setup snippet. This is required because the server-side HTTP request is the first transaction created and the RUM agent can't add any header yet, unlike XHR requests in "single-page-applications" (SPA).

With the classic agent this is documented in the public API: https://www.elastic.co/docs/reference/apm/agents/java/public-api#api-ensure-parent-id

This is however possible to do the same with any OpenTelemetry-based agent, but it's not yet documented.

Two things are needed for this:

• adding opentelemetry API to the application (gradle/maven variants).
• modifying the HTML template: as many variants as there are template engines, but we should probably document it for JSP which is the most "basic but standard" one.

[SylvainJuge]

example tested with this sample application: https://github.com/spring-petclinic/spring-framework-petclinic

adding one dependency in pom.xml (maven)

        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
            <version>1.48.0</version>
        </dependency>

In the HTML page header template:

    <script src="https://unpkg.com/@elastic/apm-rum/dist/bundles/elastic-apm-rum.umd.min.js" crossorigin></script>
    <script>
        elasticApm.init({
            serviceName: 'petclinic',
            serverUrl: 'https://673a5fb8e39e4f1389d79ec7e0ee3ecc.apm.europe-west3.gcp.cloud.es.io:443',
            environment: 'test',
            pageLoadTraceId: "<%=io.opentelemetry.api.trace.Span.current().getSpanContext().getTraceId()%>",
            pageLoadSpanId: "<%=io.opentelemetry.api.trace.Span.current().getSpanContext().getSpanId()%>",
            pageLoadSampled: <%=io.opentelemetry.api.trace.Span.current().getSpanContext().isSampled()%>
        })
    </script>