Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README #169

Merged
merged 2 commits into from
Apr 2, 2021
Merged

Update README #169

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e894d2
Update README
Apr 2, 2021
06e80d6
Code review comments
Apr 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 45 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,16 @@
---

<p align="center">
<a href="https://github.com/signalfx/splunk-otel-java/actions?query=workflow%3A%22CI+build%22">
<img alt="Build Status" src="https://img.shields.io/github/workflow/status/signalfx/splunk-otel-java/CI%20build?style=for-the-badge">
</a>
<a href="https://github.com/signalfx/splunk-otel-java/releases">
<img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/signalfx/splunk-otel-java?include_prereleases&style=for-the-badge">
</a>
</p>

---

# Splunk distribution of OpenTelemetry Java Instrumentation

The Splunk distribution of [OpenTelemetry Java
Expand All @@ -18,33 +31,37 @@ 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**.

## 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,
mateuszrzeszutek marked this conversation as resolved.
Show resolved Hide resolved
> 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).
Expand All @@ -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 is required by the javaagent. You can set it by adding a `service.name`
mateuszrzeszutek marked this conversation as resolved.
Show resolved Hide resolved
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

Expand All @@ -79,59 +102,21 @@ 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. <details><summary>Example</summary>`key1=val1,key2=val2`</details>
| 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. <details><summary>Example</summary>If 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`.</details> |
| otel.instrumentation.methods.include | OTEL_INSTRUMENTATION_METHODS_INCLUDE | unset | Same as adding `@WithSpan` annotation functionality for the target method string. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details> |
| otel.instrumentation.opentelemetry-annotations.exclude-methods | OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS | unset | Suppress `@WithSpan` instrumentation for specific methods. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details> |

### 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

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

Expand Down
45 changes: 45 additions & 0 deletions docs/advanced-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# 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. <details><summary>Example</summary>`key1=val1,key2=val2`</details>
| `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. <details><summary>Example</summary>If 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`.</details>
| `otel.instrumentation.methods.include` | `OTEL_INSTRUMENTATION_METHODS_INCLUDE` | unset | Same as adding `@WithSpan` annotation functionality for the target method string. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details>
| `otel.instrumentation.opentelemetry-annotations.exclude-methods` | `OTEL_INSTRUMENTATION_OPENTELEMETRY_ANNOTATIONS_EXCLUDE_METHODS` | unset | Suppress `@WithSpan` instrumentation for specific methods. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details>

## Java agent configuration

| System property | Environment variable | Default value | Purpose |
| ------------------------ | ------------------------ | -------------- | -------------------------------------------------|
| `otel.javaagent.enabled` | `OTEL_JAVAAGENT_ENABLED` | `true` | Globally enables javaagent auto-instrumentation. |

You can find more Java agent configuration
mateuszrzeszutek marked this conversation as resolved.
Show resolved Hide resolved
options [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/agent-config.md).