38 changes: 21 additions & 17 deletions docs/framework-splunk_otel_java_agent.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# Splunk Distribution of OpenTelemetry Java Instrumentation

The Splunk OpenTelemetry Java Agent buildpack framework will cause an application to be automatically instrumented
with the [Splunk distribution of OpenTelemetry Java Instrumentation](https://github.com/signalfx/splunk-otel-java).

Trace data will be sent directly to Splunk Observability Cloud.
This buildpack framework automatically instruments your Java application
with the [Splunk distribution of OpenTelemetry Java Instrumentation](https://github.com/signalfx/splunk-otel-java)
to send trace data to Splunk Observability Cloud.

<table>
<tr>
Expand All @@ -16,15 +15,18 @@ Trace data will be sent directly to Splunk Observability Cloud.
</tr>
</table>

Tags are printed to standard output by the buildpack detect script
The buildpack detect script prints tags to standard output.

## User-Provided Service

Users are currently expected to `create-user-provided-service` (cups) of the collector
and bind it to their application. The service MUST contain the string `splunk-o11y`.

Provide your own "user provided service" (cups) instance and bind
it to your application.

The service name MUST contain the string `splunk-o11y`.

For example, to create a service named `splunk-o11y` that represents Observability Cloud
realm `us0` and represents a user environment named `cf-demo`, you could use the following
realm `us0` and represents a user environment named `cf-demo`, use the following
commands:

```
Expand All @@ -34,27 +36,29 @@ $ cf bind-service myApp splunk-o11y
$ cf restage myApp
```

The `credential` field of the service should provide these entries:
Provide the following values using the `credential` field of the service:

| Name | Required? | Description
|------------------------|-----------| -----------
| `splunk.access.token` | Yes | The Splunk [org access token](https://docs.splunk.com/observability/admin/authentication-tokens/org-tokens.html).
| `splunk.realm` | Yes | The Splunk realm where data will be sent. This is commonly `us0` or `eu0` etc.
| `otel.*` or `splunk.*` | Optional | All additional credentials starting with these prefixes will be appended to the application's JVM arguments as system properties.
| `splunk.access.token` | Yes | Splunk [org access token](https://docs.splunk.com/observability/admin/authentication-tokens/org-tokens.html).
| `splunk.realm` | Yes | Splunk realm where data will be sent. This is commonly `us0`, `eu0`, and so on. See [Available regions or realms](https://docs.splunk.com/observability/en/get-started/service-description.html#available-regions-or-realms) for more information.
| `otel.*` or `splunk.*` | Optional | All additional credentials starting with these prefixes are appended to the application's JVM arguments as system properties.

### Choosing a version

Most users should skip this and simply use the latest version of the agent available (the default).
To override the default and choose a specific version, you can use the `JBP_CONFIG_*` mechanism
To override the default and choose a specific version, use the `JBP_CONFIG_*` mechanism
and set the `JBP_CONFIG_SPLUNK_OTEL_JAVA_AGENT` environment variable for your application.

For example, to use version 1.16.0 of the Splunk OpenTelemetry Java Instrumentation, you
could run:
For example, to use version 1.16.0 of the Splunk OpenTelemetry Java Instrumentation, run:

```
$ cf set-env testapp JBP_CONFIG_SPLUNK_OTEL_JAVA_AGENT '{version: 1.16.0}'
```


In most cases you can use the latest or default version of the agent available.

# Additional Resources

* [Splunk Observability](https://www.splunk.com/en_us/products/observability.html)
* [Official documentation of the Splunk Java agent](https://docs.splunk.com/observability/en/gdi/get-data-in/application/java/get-started.html)
* [Splunk Distribution of OpenTelemetry Java](https://github.com/signalfx/splunk-otel-java) on GitHub
4 changes: 2 additions & 2 deletions lib/java_buildpack/framework/java_cf_env.rb
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,8 @@ def supports?
private

def spring_boot_3?
@spring_boot_utils.is?(@application) && Gem::Version.new((@spring_boot_utils.version @application)).release >=
Gem::Version.new('3.0.0')
@spring_boot_utils.is?(@application) &&
Gem::Version.new((@spring_boot_utils.version_strict @application)).release >= Gem::Version.new('3.0.0')
end

def java_cfenv?
Expand Down
8 changes: 8 additions & 0 deletions lib/java_buildpack/util/spring_boot_utils.rb
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,14 @@ def version(application)
@jar_finder.version(application)
end

# The version of Spring Boot used by the application - only considers the MANIFEST entry
#
# @param [Application] application the application to search
# @return [String] the version of Spring Boot used by the application
def version_strict(application)
JavaBuildpack::Util::JavaMainUtils.manifest(application)[SPRING_BOOT_VERSION]
end

private

SPRING_BOOT_LIB = 'Spring-Boot-Lib'
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Main-Class: org.springframework.boot.loader.JarLauncher

Empty file.
6 changes: 6 additions & 0 deletions spec/java_buildpack/framework/java_cfenv_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@
expect(component.detect).to be_nil
end

it 'does not detect with Spring Boot 3 named jar but not Spring Boot 3 Manifest',
app_fixture: 'framework_java_not_spring_boot3' do

expect(component.detect).to be_nil
end

it 'does not detect with Spring Boot 3 & java-cfenv present',
app_fixture: 'framework_java_cf_exists' do

Expand Down