|
1 | | -<!-- |
2 | | -Goal of this doc: |
3 | | -Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) |
4 | | ---> |
5 | | - |
6 | | -# Configure the Elastic Distribution |
7 | | - |
8 | | -Configure the Elastic Distribution of OpenTelemetry Java (EDOT Java) to send data to Elastic. |
9 | | - |
10 | | -<!-- ✅ How users set configuration options --> |
11 | | -## Configuration methods |
12 | | - |
13 | | -Set OpenTelemetry configuration options using one of the mechanisms listed in the |
14 | | -[OpenTelemetry agent documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/) |
15 | | -and [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/java/configuration/), |
16 | | -including: |
17 | | - |
18 | | -* [Environment variables](#environment-variables) |
19 | | -* [System properties](#system-properties) |
20 | | -* [Configuration file](#configuration-file) |
21 | | - |
22 | | -<!-- ✅ Order of precedence --> |
23 | | -Configuration options set using environment variables take precedence over system properties, and |
24 | | -system properties take precedence over configuration options set using file properties. |
25 | | - |
26 | | -### Environment variables |
27 | | - |
28 | | -<!-- ✅ What and why --> |
29 | | -EDOT Java can be configured using environment variables. |
30 | | -This is a cross-platform way to configure EDOT Java and is especially useful in containerized environments. |
31 | | - |
32 | | -<!-- ✅ How --> |
33 | | -Define environment variables before starting the JVM: |
34 | | - |
35 | | -```sh |
36 | | -export OTEL_SERVICE_NAME=my-service |
37 | | -java ... |
38 | | -``` |
39 | | - |
40 | | -### System properties |
41 | | - |
42 | | -<!-- ✅ What and why --> |
43 | | -EDOT Java can be configured using system properties. |
44 | | -These configuration options can be seen by anything that can see the executed command-line. |
45 | | - |
46 | | -<!-- ✅ How --> |
47 | | -Define system properties at the JVM start, usually on the command-line: |
48 | | - |
49 | | -```sh |
50 | | -java -Dotel.service.name=my-service ... |
51 | | -``` |
52 | | - |
53 | | -### Configuration file |
54 | | - |
55 | | -<!-- ✅ What and why --> |
56 | | -EDOT Java can be configured using a configuration file. |
57 | | - |
58 | | -<!-- ✅ How --> |
59 | | -Before starting the JVM, create and populate the configuration file and specify where to find it: |
60 | | - |
61 | | -```sh |
62 | | -echo otel.service.name=my-service > my.properties |
63 | | -java -Dotel.javaagent.configuration-file=my.properties ... |
64 | | -``` |
65 | | - |
66 | | -## Configuration options |
67 | | - |
68 | | -Because the Elastic Distribution of OpenTelemetry Java is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it supports: |
69 | | - |
70 | | -* OpenTelemetry configuration options |
71 | | -* Configuration options from OpenTelemetry extensions that are included with EDOT Java |
72 | | -* Configuration options that are _only_ available in EDOT Java |
73 | | - |
74 | | -### OpenTelemetry configuration options |
75 | | - |
76 | | -EDOT Java supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/) and [OpenTelemetry Java agent documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/). |
77 | | - |
78 | | -EDOT Java uses different defaults than the OpenTelemetry Java agent for the following configuration options: |
79 | | - |
80 | | -| Option | EDOT Java default | OpenTelemetry Java agent default | |
81 | | -|---|---|---| |
82 | | -| `OTEL_RESOURCE_PROVIDERS_AWS_ENABLED` | true (enabled) | false (disabled) ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default)) | |
83 | | -| `OTEL_RESOURCE_PROVIDERS_GCP_ENABLED` | true (enabled) | false (disabled) ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default)) | |
84 | | -| `OTEL_INSTRUMENTATION_RUNTIME-TELEMETRY_EMIT-EXPERIMENTAL-TELEMETRY` | true (enabled) | false (disabled) ([docs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/ec0223de59a6c7c09b0dcf72ba89addc0975a40d/instrumentation/runtime-telemetry/README.md)) | |
85 | | - |
86 | | -#### Micrometer metrics |
87 | | - |
88 | | -Micrometer metrics can be captured and automatically converted to OpenTelemetry metrics, however |
89 | | -this is not enabled by default. |
90 | | - |
91 | | -To enable micrometer metrics, the `OTEL_INSTRUMENTATION_MICROMETER_ENABLED` configuration option must |
92 | | -be explicitly set to `true` (default `false`). |
93 | | - |
94 | | -See also [micrometer configuration options](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/javaagent) |
95 | | -for other Micrometer related configuration options. |
96 | | - |
97 | | -### Configuration options from OpenTelemetry extensions |
98 | | - |
99 | | -EDOT Java includes several OpenTelemetry extensions from the [OpenTelemetry Java agent contrib repo](https://github.com/open-telemetry/opentelemetry-java-contrib/). These extensions offer the following additional `OTEL_` options: |
100 | | - |
101 | | -| Option(s) | Extension | Description | |
102 | | -|---|---|---| |
103 | | -| `OTEL_SERVICE_NAME` | [Resource providers](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/resource-providers) | This can be [set as usual](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_service_name), but if not set the value will be inferred when the EDOT Java agent is running in various application servers. | |
104 | | -| `OTEL_INFERRED_SPANS_*` | [Inferred Spans](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/inferred-spans) | Generates additional spans using profiling instead of instrumentation. | |
105 | | - |
106 | | -### Configuration options that are _only_ available in EDOT Java |
107 | | - |
108 | | -In addition to general OpenTelemetry configuration options, there are two kinds of configuration options that are _only_ available in EDOT Java. |
109 | | - |
110 | | -**Elastic-authored options that are not yet available upstream** |
111 | | - |
112 | | -Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation) but are not yet available in the OpenTelemetry Java agent. |
113 | | - |
114 | | -_Currently there are no additional `OTEL_` options waiting to be contributed upstream._ |
115 | | - |
116 | | -**Elastic-specific options** |
117 | | - |
118 | | -`ELASTIC_OTEL_` options that are specific to Elastic and will always live in EDOT Java (in other words, they will _not_ be added upstream): |
119 | | - |
120 | | -| Option(s) | Extension | Description | |
121 | | -|---|---|---| |
122 | | -| `ELASTIC_OTEL_UNIVERSAL_PROFILING_INTEGRATION_*` | [Universal profiling integration](https://github.com/elastic/elastic-otel-java/tree/main/universal-profiling-integration) | Correlates traces with profiling data from the Elastic universal profiler. | |
123 | | -| `ELASTIC_OTEL_JAVA_SPAN_STACKTRACE_MIN_DURATION` | [Span stacktrace capture](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/span-stacktrace) | Define the minimum duration for attaching stack traces to spans. Defaults to 5ms. | |
124 | | - |
125 | | -### Instrumentations that are _only_ available in EDOT Java |
126 | | - |
127 | | -Some instrumentation are only available in EDOT Java and might or might not be added upstream in future versions. |
128 | | - |
129 | | -#### OpenAI Java Client |
130 | | - |
131 | | -Instrumentation for the [official OpenAI Java Client](https://github.com/openai/openai-java). |
132 | | -It supports: |
133 | | - * Tracing for requests, including GenAI-specific attributes such as token usage |
134 | | - * Opt-In logging of OpenAI request and response content payloads |
135 | | - |
136 | | -The minimum supported version is `0.8.0`. |
137 | | - |
138 | | -Note that this instrumentation is currently in **tech preview**, because the OpenAI client itself is still in beta. |
139 | | -Once the OpenAI client is stable, this instrumentation will be GAed. We'll drop support for older beta versions of the client after some time. |
140 | | -The instrumentation is on by default and can be disabled by setting either the `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED` environment variable or the `otel.instrumentation.openai-client.enabled` JVM property to `false`. |
141 | | - |
142 | | -In addition, this instrumentation provides the following configuration options: |
143 | | - |
144 | | -| Option(s) | Description | |
145 | | -|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
146 | | -| `ELASTIC_OTEL_JAVA_INSTRUMENTATION_GENAI_EMIT_EVENTS` | If set to `true`, the agent will generate log events for OpenAI requests and responses. Potentially sensitive content will only be included if `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is true. Defaults to the value of `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`, so that just enabling `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` ensures that log events are generated. | |
147 | | -| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | If set to `true`, enables the capturing of OpenAI request and response content in the log events outputted by the agent. Defaults to `false` | |
148 | | - |
149 | | -<!-- ✅ List auth methods --> |
150 | | -## Authentication methods |
151 | | - |
152 | | -When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. |
153 | | -Both EDOT Java and APM Server must be configured with the same secret token for the request to be accepted. |
154 | | - |
155 | | -### Use an APM agent key (API key) |
156 | | - |
157 | | -<!-- ✅ What and why --> |
158 | | -[APM agent keys](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) are |
159 | | -used to authorize requests to an Elastic Observability endpoint. |
160 | | -APM agent keys are revocable, you can have more than one of them, and |
161 | | -you can add or remove them without restarting APM Server. |
162 | | - |
163 | | -<!-- ✅ How do you authenticate using this method? --> |
164 | | -To create and manage APM Agent keys in Kibana: |
165 | | - |
166 | | -1. Go to **APM Settings**. |
167 | | -1. Select the **Agent Keys** tab. |
168 | | - |
169 | | -When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a |
170 | | -different auth schema (`ApiKey` rather than `Bearer`). For example: |
171 | | - |
172 | | -<!-- ✅ Code example --> |
173 | | -```sh |
174 | | -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io |
175 | | -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" |
176 | | -``` |
177 | | - |
178 | | -### Use a secret token |
179 | | - |
180 | | -<!-- ✅ What and why --> |
181 | | -[Secret tokens](https://www.elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize requests to the APM Server. |
182 | | - |
183 | | -<!-- ✅ How do you authenticate using this method? --> |
184 | | -You can find the values of these variables in Kibana's APM tutorial. |
185 | | -In Kibana: |
186 | | - |
187 | | -1. Go to **Setup guides**. |
188 | | -1. Select **Observability**. |
189 | | -1. Select **Monitor my application performance**. |
190 | | -1. Scroll down and select the **OpenTelemetry** option. |
191 | | -1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. |
192 | | - For example: |
193 | | - |
194 | | - ```sh |
195 | | - export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io |
196 | | - export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" |
197 | | - ``` |
| 1 | +This page has been moved to [EDOT documentation](https://elastic.github.io/opentelemetry/edot-sdks/java/setup/index.html) |
0 commit comments