Skip to content

Commit 7a3722c

Browse files
SylvainJugeSylvainJuge
authored
java-troubleshooting-faq (#117)
* bootstrap FAQ * faq wip * document update * keep stuff for later * remove apm server from troubleshooting + add api key with collector
1 parent 46ee5d3 commit 7a3722c

File tree

2 files changed

+87
-17
lines changed

2 files changed

+87
-17
lines changed

‎docs/_edot-sdks/java/faq.md

+82-1
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,85 @@ parent: EDOT Java
77

88
# Frequently Asked Questions on EDOT Java
99

10-
TODO
10+
## Does agent requires access to or modification of application code ?
11+
12+
No, the agent modifies the Java application binaries in bytecode form and does not requires original code nor
13+
recompiling or re-packaging the application.
14+
15+
## How to disable the agent ?
16+
17+
There are two ways to disable the instrumentation agent:
18+
19+
- remove `-javaagent:` JVM argument
20+
- set `OTEL_JAVAAGENT_ENABLED` environment variable or `otel.javaagent.enabled` Java system property to `false`
21+
22+
In both cases you need to restart the JVM.
23+
24+
## How to partially enable or disable the agent ?
25+
26+
It is possible to partially disable the agent, or to only selectively enable a limited set of instrumentations
27+
by following instructions in the [upstream documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/).
28+
29+
## How to know if EDOT is attached to a running JVM ?
30+
31+
There are a few ways we can detect if the agent has been attached to a JVM
32+
- in JVM logs, agent startup log message (see [below](#how-to-identify-the-version-of-edot-agent-)) might be included
33+
- in JVM arguments `ps -ef|grep javaagent`
34+
- in environment variables, for example `JAVA_TOOL_OPTIONS`, for example by inspecting the output of `export|grep javaagent`
35+
36+
## How to identify the version of EDOT agent ?
37+
38+
When the agent starts, a log message in the standard error provides the agent version:
39+
```
40+
INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.2.3
41+
```
42+
43+
In addition, the `-javaagent:` JVM argument can provide the path to the agent file name, which _might_ also contain
44+
the agent version, for example `-javaagent:elastic-otel-javaagent-1.2.3.jar`
45+
46+
When the original agent jar file has been renamed, it is still possible to inspect the `Implementation-Version` entry in `META-INF/MANIFEST.MF` file of the agent jar,
47+
for example with `unzip -p elastic-otel-javaagent.jar META-INF/MANIFEST.MF|grep 'Implementation-Version'`
48+
49+
## What are the versions of the OpenTelemetry upstream dependencies ?
50+
51+
Because EDOT Java is a distribution of [OpenTelemetry Java instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation),
52+
it includes the following dependencies:
53+
54+
- [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
55+
- [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java)
56+
- [Semantic Conventions Java mappings](https://github.com/open-telemetry/semantic-conventions-java)
57+
- [OpenTelemetry Java Contrib](https://github.com/open-telemetry/opentelemetry-java-contrib)
58+
59+
The versions of those included in EDOT is usually aligned with the OpenTelemetry Java Instrumentation, for reference we
60+
provide in the [release notes](https://github.com/elastic/elastic-otel-java/releases) details of versions included in each release.
61+
62+
## When and how to update EDOT
63+
64+
The general recommendation is to update EDOT agent to the latest version when possible to benefit from:
65+
- bug fixes and technical improvements
66+
- support of new features and instrumentation
67+
- evolution of semantic conventions
68+
- frequent and regular updates usually makes reviewing and handling changes easier.
69+
70+
Updating to the latest EDOT version involves reviewing changes of the included dependencies:
71+
72+
- [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
73+
- [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java)
74+
- [Semantic Conventions Java mappings](https://github.com/open-telemetry/semantic-conventions-java)
75+
- [OpenTelemetry Java Contrib](https://github.com/open-telemetry/opentelemetry-java-contrib)
76+
77+
In order to review each of those individually, you can use the [EDOT release notes](https://github.com/elastic/elastic-otel-java/releases)
78+
for links to the respective versions of each component.
79+
80+
### OpenTelemetry API/SDK update
81+
82+
In order to implement manual instrumentation, some applications use the OpenTelemetry API and/or SDK which allows them
83+
to capture custom spans, metrics or even send data without any instrumentation agent.
84+
85+
Updates of the OpenTelemetry API/SDK in the application and the EDOT Java agent can be done independently.
86+
- EDOT Java is backward-compatible with all previous versions of OpenTelemetry API/SDK
87+
- Using a more recent version of API/SDK than the one in EDOT should usually work without problem, however to ensure maximum compatibility keeping OpenTelemetry API/SDK version ≤ EDOT OpenTelemetry API/SDK version is recommended.
88+
89+
### How to update
90+
91+
Updating EDOT Java agent is done by replacing the agent binary `.jar` that has been [added during setup](./setup/).

‎docs/_edot-sdks/java/troubleshooting.md

+5-16
Original file line numberDiff line numberDiff line change
@@ -9,37 +9,26 @@ parent: EDOT Java
99

1010
The sections below are in the order you should follow, unless you have already identified the section you need.
1111

12-
This guide assumes you have tested the other components in the route from application+agent to Elastic Observability (eg collector or APM server, Elasticsearch, and Kibana) and that the problem has been isolated to the application+agent.
12+
This guide assumes you have tested the other components in the route from application+agent to Elastic Observability (eg collector, Elasticsearch, and Kibana) and that the problem has been isolated to the application+agent.
1313

1414
## General
1515

1616
Ensure you have set a service name (eg `-Dotel.service.name=Service1` or environment variable `OTEL_SERVICE_NAME` set to `Service1`) otherwise by default the data (traces, metrics, logs) will be sent to `unknown_service_java` - you may be getting data but it may all be under that service
1717

1818
## Connectivity to endpoint
1919

20-
Check _from_ the host/VM/pod/container/image running the app, that connectivity is available to the APM server or collector. The examples here use a default URL, which you should replace with the endpoint you are using:
20+
Check _from_ the host/VM/pod/container/image running the app, that connectivity is available to the collector.
21+
22+
The examples here use a default URL `http://127.0.0.1:4318/, which you should replace with the endpoint you are using:
2123

2224
- OpenTelemetry or EDOT collector without authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json`
23-
- APM server without authentication: `curl --verbose -X GET http://127.0.0.1:8200`
24-
- APM server with secret token authentication: `curl -X POST http://127.0.0.1:8200/ -H "Authorization: Bearer <secret_token>"`
25-
- APM server with API key authentication: `curl -X POST http://127.0.0.1:8200/ -H "Authorization: ApiKey <api_key>"`
25+
- OpenTelemetry or EDOT collector with API key authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json -H "Authorization:ApiKey <api_key>"`
2626

2727
The collector should produce output similar to
2828
```
2929
{"partialSuccess":{}}
3030
```
3131

32-
The APM server should produce output similar to
33-
```
34-
{
35-
"build_date": "2021-12-18T19:59:06Z",
36-
"build_sha": "24fe620eeff5a19e2133c940c7e5ce1ceddb1445",
37-
"publish_ready": true,
38-
"version": "8.17.3"
39-
}
40-
```
41-
42-
4332
## Is it the agent?
4433

4534
Determine if the issue is related to the agent by

0 commit comments

Comments
 (0)