Add documentation on setting SpanKind and capture HttpHeaders with OTEL (#12328)

* wip add docs for capturing http headers as well as manual instrumentation using opentelemetry

* Update docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx

Co-authored-by: Alexander Dinauer <[email protected]>

---------

Co-authored-by: Alexander Dinauer <[email protected]>

Author: lbloder

docs/platforms/java/common/tracing/instrumentation/opentelemetry.mdx

@@ -69,6 +69,39 @@ You'll have to configure both OpenTelemetry and Sentry to see transactions in Se
 
 With Sentry’s OpenTelemetry SDK, an OpenTelemetry `Span` becomes a Sentry `Transaction` or `Span`. The first `Span` sent through the Sentry `SpanProcessor` is a `Transaction`, and any child `Span` gets attached to the first `Transaction` upon checking the parent `Span` context. This is true for the OpenTelemetry root `Span` and any top level `Span` in the system. For example, a request sent from frontend to backend will create an OpenTelemetry root `Span` with a corresponding Sentry `Transaction`. The backend request will create a new Sentry `Transaction` for the OpenTelemetry `Span`. The Sentry `Transaction` and `Span` are linked as a trace for navigation and error tracking purposes.
 
+### Manual Instrumentation with OpenTelemetry
+
+If you have the OpenTelemetry SDK in you classpath, you can also instrument your code manually using the OpenTelemetry API as documented [in the OpenTelemetry docs](https://opentelemetry.io/docs/languages/java/api/#span).
+
+A manually created span for HTTP requests needs to declare its `SpanKind` as well as the `HttpAttributes.HTTP_REQUEST_METHOD` attribute, so that `Sentry` can correctly process these:
+
+```java {tabTitle:Java}
+Span span = tracer.spanBuilder("myspan")
+  .setAttribute(HTTP_REQUEST_METHOD, "GET")
+  .setSpanKind(SpanKind.SERVER)
+  .startSpan();
+```
+```kotlin {tabTitle:Kotlin}
+val span = tracer.spanBuilder("myspan")
+  .setAttribute(HTTP_REQUEST_METHOD, "GET")
+  .setSpanKind(SpanKind.SERVER)
+  .startSpan()
+```
+
+### Capturing HTTP Headers
+
+By default OpenTelemetry does not capture any HTTP headers. This, however, can be configured using system properties or environment variables as per OpenTelemetry's configuration documentation [here](https://opentelemetry.io/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers). Each variable is a comma-separated list of HTTP header names that should be captured.
+
+#### Client variables
+
+- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS`
+- `OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS`
+
+#### Server variables
+
+- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS`
+- `OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS`
+
 ## Additional Configuration
 
 If you need more fine grained control over Sentry, take a look at the <PlatformLink to="/configuration/">Configuration page</PlatformLink>. In case you'd like to filter out transactions before sending them to Sentry (to get rid of health checks, for example), you may find the <PlatformLink to="/configuration/filtering/#filtering-transaction-events">Filtering page</PlatformLink> helpful.