diff --git a/README.md b/README.md index 067457365..640683826 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ +--- + +

+ + Build Status + + + GitHub release (latest by date) + +

+ +--- + # Splunk distribution of OpenTelemetry Java Instrumentation The Splunk distribution of [OpenTelemetry Java @@ -18,7 +31,7 @@ This Splunk distribution comes with the following defaults: configured to send spans to a locally running [SignalFx Smart Agent](https://docs.signalfx.com/en/latest/apm/apm-getting-started/apm-smart-agent.html) (`http://localhost:9080/v1/trace`). -- Unlimited default limits for [configuration options](#trace-configuration) to +- Unlimited default limits for [configuration options](docs/advanced-config.md#trace-configuration) to support full-fidelity traces. > :construction: This project is currently in **BETA**. @@ -26,25 +39,29 @@ This Splunk distribution comes with the following defaults: ## Getting Started To get started, download the JAR for the agent's [latest -version](https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent-all.jar) -and add its path to your JVM startup options. +version](https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent-all.jar): + +```bash +curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent-all.jar \ + -o splunk-otel-javaagent.jar +``` +Enable the Java agent by adding the `-javaagent` flag to the runtime JVM parameters. For example, if the runtime parameters were: ```bash -$ java -jar target/java-agent-example-1.0-SNAPSHOT-shaded.jar https://google.com +java -jar myapp.jar https://google.com ``` Then the runtime parameters would be updated to: ```bash -$ curl -L https://github.com/signalfx/splunk-otel-java/releases/latest/download/splunk-otel-javaagent-all.jar \ - -o splunk-otel-javaagent.jar -$ java -javaagent:./splunk-otel-javaagent.jar -Dotel.resource.attributes=service.name=my-java-app \ - -jar target/java-agent-example-1.0-SNAPSHOT-shaded.jar https://google.com +java -javaagent:./splunk-otel-javaagent.jar \ + -Dotel.resource.attributes=service.name=my-java-app \ + -jar myapp.jar https://google.com ``` -> The `-javaagent` needs to be run before the `-jar` file, +> The `-javaagent` needs to appear before the `-jar` file, > adding it as a JVM option, not as an application argument. For more > information, see the [Oracle > documentation](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html). @@ -59,16 +76,22 @@ To see the Java Agent in action with sample applications, see our ### Basic Configuration The service name resource attribute is the only configuration option -that typically needs to be specified. You can set it by adding a `service.name` +that needs to be specified. You can set it by adding a `service.name` attribute as shown in the [example above](#getting-started). A couple other configuration options that may need to be changed or set are: - Endpoint if not sending to a locally running Smart Agent with default - configuration. See the [Jaeger exporter](#jaeger-exporter) section for more information. -- Environment resource attribute (example: - `-Dotel.resource.attributes=service.name=my-service,deployment.environment=production`) to specify what - environment the span originated from. + configuration. See the [Jaeger exporter](docs/advanced-config.md#jaeger-exporter) + configuration documentation for more information. +- Environment resource attribute `deployment.environment` to specify what environment + the span originated from. For example: + ``` + -Dotel.resource.attributes=service.name=my-java-app,deployment.environment=production + ``` + +The `otel.resource.attributes` syntax is described in detail in the +[trace configuration](docs/advanced-config.md#trace-configuration) section. ### Supported Java Versions @@ -79,49 +102,8 @@ libraries and versions are listed ## Advanced Configuration -> For the majority of users, the [Getting Started](#getting-started) section is -> all you need. The follow section contains advanced configuration options. - -The agent can be configured in the following ways: - -* System property (example: `-Dotel.resource.attributes=service.name=my-java-app`) -* Environment variable (example: `export OTEL_RESOURCE_ATTRIBUTES=service.name=my-java-app`) - -> System property values take priority over corresponding environment variables. - -Below you will find all the configuration options supported by this distribution. - -### Jaeger exporter - -| System property | Environment variable | Description | -|-----------------------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------| -| otel.traces.exporter | OTEL_TRACES_EXPORTER | Select the span exporter to use. `jaeger-thrift-splunk` is the default value. -| otel.exporter.jaeger.endpoint | OTEL_EXPORTER_JAEGER_ENDPOINT | The Jaeger endpoint to connect to. Default is `http://localhost:9080/v1/trace`. -| splunk.access.token | SPLUNK_ACCESS_TOKEN | (Optional) Auth token allowing to communicate directly with the Splunk cloud, passed as `X-SF-TOKEN` header. Default is empty. | - -### Trace configuration - -| System property | Environment variable | Default value | Purpose | -| ----------------------------------- | ---------------------------------- | -------------- | ------------------------------------------------------------------------------------ | -| otel.span.attribute.count.limit | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | unlimited | Maximum number of attributes per span. | -| otel.span.event.count.limit | OTEL_SPAN_EVENT_COUNT_LIMIT | unlimited | Maximum number of events per span. | -| otel.span.link.count.limit | OTEL_SPAN_LINK_COUNT_LIMIT | `1000` | Maximum number of links per span. | -| otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | unset | Comma-separated list of resource attributes added to every reported span.
Example`key1=val1,key2=val2`
-| otel.instrumentation.common.peer-service-mapping | OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING | unset | Used to add a `peer.service` attribute by specifying a comma separated list of mapping from hostnames or IP addresses.
ExampleIf set to `1.2.3.4=cats-service,dogs-service.serverlessapis.com=dogs-api`, requests to `1.2.3.4` will have a `peer.service` attribute of `cats-service` and requests to `dogs-service.serverlessapis.com` will have one of `dogs-api`.
| -| otel.instrumentation.methods.include | OTEL_INSTRUMENTATION_METHODS_INCLUDE | unset | Same as adding `@WithSpan` annotation functionality for the target method string.
Format`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`
| -| otel.instrumentation.opentelemetry-annotations.exclude-methods | OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS | unset | Suppress `@WithSpan` instrumentation for specific methods.
Format`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`
| - -### Java agent configuration - -| System property | Environment variable | Default value | Purpose | -| ---------------------- | ---------------------- | -------------- | -------------------------------------------------| -| otel.javaagent.enabled | OTEL_JAVAAGENT_ENABLED | `true` | Globally enables javaagent auto-instrumentation. | - -### Splunk distribution configuration - -| System property | Environment variable | Default value | Purpose | -| ------------------------------------ | ---------------------------------- | -------------- | -------------------------------------------------------- | -| splunk.context.server-timing.enabled | SPLUNK_CONTEXT_SERVER_TIMING_ENABLED | false | Enables adding `Server-Timing` header to HTTP responses. See [this document](docs/server-timing.md) for more information. | +For the majority of users, the [Getting Started](#getting-started) section is +all you need. Advanced configuration documentation can be found [here](docs/advanced-config.md). ## Manually instrument a Java application @@ -129,9 +111,12 @@ Documentation on how to manually instrument a Java application are available [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/manual-instrumentation.md). To extend the instrumentation with the OpenTelemetry Instrumentation for Java, -you have to use a compatible API version. The Splunk distribution of -OpenTelemetry Java Instrumentation version 0.9.0 is compatible with the -OpenTelemetry Instrumentation for Java version 1.0.0 and API version 1.0.0. +you have to use a compatible API version. + +The Splunk distribution of OpenTelemetry Java Instrumentation version 0.9.0 is compatible with: + +* OpenTelemetry API version 1.0.0 +* OpenTelemetry Instrumentation for Java version 1.0.0 ## Correlating traces with logs diff --git a/docs/advanced-config.md b/docs/advanced-config.md new file mode 100644 index 000000000..0f45bc722 --- /dev/null +++ b/docs/advanced-config.md @@ -0,0 +1,47 @@ +# Advanced Configuration + +The agent can be configured in the following ways: + +* System property (example: `-Dotel.resource.attributes=service.name=my-java-app`) +* Environment variable (example: `export OTEL_RESOURCE_ATTRIBUTES=service.name=my-java-app`) + +> System property values take priority over corresponding environment variables. + +Below you will find all the configuration options supported by this distribution. + +## Splunk distribution configuration + +| System property | Environment variable | Default value | Purpose | +| -------------------------------------- | -------------------------------------- | -------------- | ------- | +| `splunk.context.server-timing.enabled` | `SPLUNK_CONTEXT_SERVER_TIMING_ENABLED` | `false` | Enables adding `Server-Timing` header to HTTP responses. See [this document](server-timing.md) for more information. +| `splunk.access.token` | `SPLUNK_ACCESS_TOKEN` | unset | (Optional) Auth token allowing exporters to communicate directly with the Splunk cloud, passed as `X-SF-TOKEN` header. Currently only the [Jaeger exporter](#jaeger-exporter) supports this property. + +## Jaeger exporter + +| System property | Environment variable | Default value | Description | +| ------------------------------- | --------------------------------- | -------------------------------- | ----------- | +| `otel.traces.exporter` | `OTEL_TRACES_EXPORTER` | `jaeger-thrift-splunk` | Select the span exporter to use. +| `otel.exporter.jaeger.endpoint` | `OTEL_EXPORTER_JAEGER_ENDPOINT` | `http://localhost:9080/v1/trace` | The Jaeger endpoint to connect to. + +## Trace configuration + +| System property | Environment variable | Default value | Purpose | +| ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------- | ------- | +| `otel.span.attribute.count.limit` | `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` | unlimited | Maximum number of attributes per span. +| `otel.span.event.count.limit` | `OTEL_SPAN_EVENT_COUNT_LIMIT` | unlimited | Maximum number of events per span. +| `otel.span.link.count.limit` | `OTEL_SPAN_LINK_COUNT_LIMIT` | `1000` | Maximum number of links per span. +| `otel.resource.attributes` | `OTEL_RESOURCE_ATTRIBUTES` | unset | Comma-separated list of resource attributes added to every reported span.
Example`key1=val1,key2=val2`
+| `otel.instrumentation.common.peer-service-mapping` | `OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING` | unset | Used to add a `peer.service` attribute by specifying a comma separated list of mapping from hostnames or IP addresses.
ExampleIf set to `1.2.3.4=cats-service,dogs-service.serverlessapis.com=dogs-api`, requests to `1.2.3.4` will have a `peer.service` attribute of `cats-service` and requests to `dogs-service.serverlessapis.com` will have one of `dogs-api`.
+| `otel.instrumentation.methods.include` | `OTEL_INSTRUMENTATION_METHODS_INCLUDE` | unset | Same as adding `@WithSpan` annotation functionality for the target method string.
Format`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`
+| `otel.instrumentation.opentelemetry-annotations.exclude-methods` | `OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS` | unset | Suppress `@WithSpan` instrumentation for specific methods.
Format`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`
+ +## Java agent configuration + +| System property | Environment variable | Default value | Purpose | +| ------------------------ | ------------------------ | -------------- | -------------------------------------------------| +| `otel.javaagent.enabled` | `OTEL_JAVAAGENT_ENABLED` | `true` | Globally enables javaagent auto-instrumentation. | + +## Other OpenTelemetry Java agent configuration + +You can find all other Java agent configuration options +described [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/agent-config.md).