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

Jump to bottom

more edits #7477

Merged
merged 1 commit into from
Aug 21, 2024
+233 −168
Merged

more edits #7477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 8 additions & 1 deletion modules/ROOT/pages/microprofile-config-properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -616,6 +616,8 @@ This property or `*/mp-rest/url` is considered required. However, some implement

The following MicroProfile Config properties can be specified when MicroProfile Telemetry is enabled. This table lists the most important properties. For the full list, see the https://download.eclipse.org/microprofile/microprofile-telemetry-1.0/tracing/microprofile-telemetry-tracing-spec-1.0.html#_configuration[MicroProfile Telemetry specification].

For more information about collecting Open Liberty logs, metrics, and traces, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry].

.MicroProfile Config properties for MicroProfile Telemetry
[options="header"]
|===
Expand All @@ -642,7 +644,7 @@ The following MicroProfile Config properties can be specified when MicroProfile
|`otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans`

|`otel.sdk.disabled`
|Enables tracing by MicroProfile Telemetry. The default is `true`.
|Enables logs, metrics, and traces to be sent to OpenTelemetry. The default is `true`.
|Application startup
|`otel.sdk.disabled=false`

Expand All @@ -651,6 +653,11 @@ The following MicroProfile Config properties can be specified when MicroProfile
|Application startup
|`otel.service.name=system`

|`otel.logs.exporter`
|You can use this property to change where the logs that MicroProfile Telemetry collects are exported. For more information, see xref:microprofile-telemetry.adoc#logs[Configuring Open Liberty to use MicroProfile Telemetry to collect logs]
|Application startup
|`otel.traces.exporter=console`

|`otel.traces.exporter`
|Sets the exporter that is used to collect traces. Possible values are `otlp`, `zipkin`, `jaeger`, or `logging`. The default value is `otlp`. For the Jaeger trace service versions 1.35 and later, the `otlp` exporter value is recommended, rather than `jaeger`.
|Application startup
Expand Down
204 changes: 43 additions & 161 deletions modules/ROOT/pages/microprofile-telemetry.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,24 +22,31 @@ MicroProfile Telemetry replaces MicroProfile OpenTracing. For more information a

The following sections explain how to prepare your Open Liberty runtime and application code to use MicroProfile Telemetry.

- <<#ol-config, Configuring Open Liberty to use MicroProfile Telemetry>>
- <<#traces, Configuring Open Liberty to use MicroProfile Telemetry>>
- <<#code, Code instrumentation>>
- <<#trouble, Troubleshooting MicroProfile Telemetry>>

[#ol-config]
== Configuring Open Liberty to use MicroProfile Telemetry
[#global]
== Enabling MicroProfile Telemetry for Open Liberty

To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports traces.
To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file and enable the OpenTelemetry SDK by specifying the `otel.sdk.disabled=false` MicroProfile Config property or the `OTEL_SDK_DISABLED=false` environment variable. in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config].

. Add a version of the feature:mpTelemetry[display=MicroProfile Telemetry] feature to your `server.xml` file.
. Enable the feature:mpTelemetry[display=MicroProfile Telemetry] feature in your `server.xml` file. To export metrics or logs, you must enable `mpTelemetry-2.0` or later.

. Enable tracing and configure a trace storage system by specifying MicroProfile Config properties.
. OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property.
+
You can configure how MicroProfile Telemetry collects and exports traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable.
You can configure how MicroProfile Telemetry collects and exports logs, metrics, and traces by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. Alternatively, if you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable.

.. OpenTelemetry is disabled by default. To enable the generation of traces, set the `otel.sdk.disabled=false` property.
[#traces]
== Configuring Open Liberty to use MicroProfile Telemetry to collect traces

To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file, enable the OpenTelemetry SDK. Optionally, you specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports traces.

. Enable the MicroProfile Telemetry feature 2.0 or later and specify a MicroProfile Config property or environment variable to enable the OpenTelemetry SDK.
+
.. Configure a trace storage system by specifying an exporter definition that includes the exporter type and the endpoint to connect to.
For more information, see <<#global,Enabling MicroProfile Telemetry for Open Liberty>>

. Configure a trace storage system by specifying an exporter definition that includes the exporter type and the endpoint to connect to.
+
For example, to use a Jaeger server, you might add configuration similar to the following example to your `bootstrap.properties` file:
+
Expand All @@ -59,7 +66,7 @@ otel.traces.exporter=zipkin
otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans
----

.. Optionally, set other MicroProfile Config properties to configure trace details.
. Optionally, set other MicroProfile Config properties to configure trace details.
+
For example, if you want to export traces to Open Liberty log files, set the following property:
+
Expand All @@ -72,173 +79,48 @@ For more information about the available properties, see xref:microprofile-confi

. Depending on how you choose to instrument your application code for tracing, further configuration might be required.
+
For more information, see the following section.

[#code]
== Code instrumentation

After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code by using one of the following methods:
For more information, see xref:telemetry-trace.adoc#t[Code instrumentation for MicroProfile Telemetry tracing].

* <<#auto, Automatic instrumentation>>, which automatically traces your JAX-RS or RESTful web services.
* <<#manual, Manual instrumentation>>, which allows you to start and end telemetry spans manually for applications that are not JAX-RS or RESTful web services.
* <<#agent, Agent instrumentation>>, which automatically adds telemetry to popular open source libraries. However, agent instrumentation also imposes certain <<#limit, limitations>>.
[#logs]
== Configuring Open Liberty to use MicroProfile Telemetry to collect logs

[#auto]
=== Automatic instrumentation

With automatic instrumentation, you can observe traces without modifying the source code in your applications. All you need to do is configure runtime as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>. However, automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications.

In Open Liberty version 23.0.0.11 and later, spans are automatically generated for incoming HTTP requests, including static files, servlets, and JSPs.

////
To start emitting traces with automatic instrumentation, enable the MicroProfile Telemetry feature in your `server.xml` file by adding `<feature>mpTelemetry-1.0</feature>` or `<feature>mpTelemetry-1.1</feature>` to your server.xml file. By default, MicroProfile Telemetry tracing is off. To enable tracing, specify the `otel.sdk.disabled=false` MicroProfile Config property and any exporter configuration that your tracing service requires.
To enable MicroProfile Telemetry in your Open Liberty runtime, you must add the MicroProfile Telemetry feature to your `server.xml` file, enable the OpenTelemetry SDK. Optionally, you can specify MicroProfile Config properties to configure how MicroProfile Telemetry collects and exports logs.

For example, to export traces to a Jaeger server with the OpenTelemetry Protocol (OTLP) enabled, add the following entries to your `bootstrap.properties` file.

[source,properties]
----
otel.sdk.disabled=false
otel.traces.exporter=otlp
otel.exporter.otlp.endpoint=http://localhost:4317/
----
. Enable the MicroProfile Telemetry feature 2.0 or later and specify a MicroProfile Config property or environment variable to enable the OpenTelemetry SDK.
+
For more information, see <<#global,Enabling MicroProfile Telemetry for Open Liberty>>

To export traces to a Zipkin server, you can use the following properties instead:
. Optionally, configure the log sources that MicroProfile Telemetry collects and where the logs are exported
+
You can configure how MicroProfile Telemetry collects and exports logs by specifying configuration properties in any of the xref:external-configuration.adoc#default[config sources that are available to MicroProfile Config]. If you choose to set these configuration properties by using environment variables, make the key name uppercase and convert any punctuation to underscores. For example, the `otel.sdk.disabled=false` property is equivalent to the `OTEL_SDK_DISABLED=false` environment variable.

.. Change the log exporter that MicroProfile Telemtry uses.
+
By default, all OpenTelemetry data is exported to link:https://opentelemetry.io/docs/languages/java/exporters/#otlp[OTLP]. You can change this setting by specifying the `otel.logs.exporter` property.
+
For example, to send logs to the `console.log` file for debugging purposes, you might add configuration similar to the following example to your `bootstrap.properties` file:
+
[source,properties]
----
otel.sdk.disabled=false
otel.traces.exporter=zipkin
otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans
otel.logs.exporter=console
----
////

[#manual]
=== Manual instrumentation

Automatic instrumentation is available only for JAX-RS and Jakarta RESTful web service applications. To create spans for other operations, such as database calls, you can add manual instrumentation to the source code for those operations by using the https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.19.0/io/opentelemetry/api/trace/package-summary.html[OpenTelemetry API]. However, before you manually instrument your code, you must complete the following prerequisites.

. Enable MicroProfile Telemetry, as described in <<#ol-config,Configuring Open Liberty to use MicroProfile Telemetry>>.

. xref:class-loader-library-config.adoc#3rd-party[Enable third-party APIs] for your application by adding the following code in your `server.xml` file:
+
[source,xml]
----
<webApplication id="app-name" location="app-name.war">
<classloader apiTypeVisibility="+third-party"/>
</webApplication>
----

. Add the `opentelemetry` API and OpenTelemetry instrumentation annotations as a provided dependency to your build path. For example, with Maven, add the following code to your `pom.xml` file.
If it is set to `console`, all the logs are exported to standard out (`stdout`) and the `console.log` file. The `console.log` file the contains the usual logs, along with duplicate OpenTelemetry-mapped logs. This setting is only for debugging purposes because the the `console.log`file does not roll over and could affect performance if it gets too large.
+
[source,xml]
----
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
<version>1.19.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-instrumentation-annotations</artifactId>
<version>1.19.0-alpha</version>
<scope>provided</scope>
</dependency>
----

After you complete those prerequisites, you're ready to instrument your code. The following examples show configuration options with the OpenTelemetry API.

- Add extra information, such as the user ID, to the current span. Any information that you add to a span is visible when you look at traces on your trace server.
.. Configure MicroProfile Telemetry to use the OpenTelemetry Batch LogRecord Processor.
+
[source,java]
----
private static final AttributeKey<String> USER_ID_ATTR = AttributeKey.stringKey("userId");

@Inject private Span currentSpan;

@GET
public String myMethod() {
...
currentSpan.setAttribute(USER_ID_ATTR, getUserId());
...
}
----

- Create a subspan around a particular operation, such as querying a database. This subspan shows you how long it took and the order in which it occurred relative to other spans.
By default, the SimpleLogRecordProcessor is enabled, so the records are sent immediately. However, if you want to send the records in batches, you can also configure the following logging specific Batch LogRecord Processor properties:
+
[source,java]
----
@Inject private Tracer tracer;

@GET
public String myMethod() {
...
Span newSpan = tracer.spanBuilder("QueryDatabase").startSpan();
try (Scope s = newSpan.makeCurrent()) {
queryDatabase();
} finally {
newSpan.end();
}
...
}
----

- Annotate methods in any Jakarta CDI beans by using the `@WithSpan` annotation. This annotation creates a new Span and establishes any required relationships with the current trace context. You can annotate method parameters with the `@SpanAttribute` annotation to indicate which method parameters are part of the trace, as shown in the following example.
* `otel.blrp.schedule.delay`
* `otel.blrp.max.queue.size`
* `otel.blrp.max.export.batch.size`
* `otel.blrp.export.timeout`
+
[source,java]
----
@ApplicationScoped
class SpanBean {
For more information, see link:https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-logrecord-processor[Batch LogRecord Processor].

@WithSpan("name")
void spanName() {
...
}

@WithSpan
void spanArgs(@SpanAttribute(value = "arg") String arg) {
...
}
}
----

==== Considerations for using manual instrumentation

The following important considerations apply to manual instrumentation.

- You must call the `.end()` method on any span you create, otherwise the span is not recorded.
- The current span is used as the parent for any new spans that are created. Therefore, when you create a span, you usually also want to make it current. However, you must close the `Scope` instance that is returned by the `Span.makeCurrent()` method. You can close a `Scope` instance by specifying a try-with-resources block, as shown in the previous example for creating a subspan.
- Because Liberty supports per-application configuration, it does not support `GlobalOpenTelemetry`. Using that class does not produce any telemetry data.
- If you set any properties by using environment variables, including those in the `server.env` file, the keys must be in uppercase and all punctuation must be replaced by an underscore. Values must be written normally.

For more information, see the https://opentelemetry.io/docs/instrumentation/java/manual[OpenTelemetry manual instrumentation documentation]. However, remember when you use the MicroProfile Telemetry feature in Open Liberty, you must obtain the `OpenTelemetry` and `Tracer` objects by injecting them, not by creating your own. Furthermore, be aware that this documentation includes information for the OpenTelemetry Metrics and Logging APIs, which are not supported by MicroProfile Telemetry.

[#agent]
=== Agent instrumentation
The https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Instrumentation for Java] project provides a Java agent JAR file that can be attached to any Java 8+ application. This file dynamically injects bytecode that adds telemetry support to popular open source libraries and frameworks. If you are using any of the https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks[supported libraries] in your application, you can use this agent with Open Liberty to instrument them.

To enable the Java agent on your Open Liberty runtime, https://github.com/open-telemetry/opentelemetry-java-instrumentation#getting-started[download the latest agent version from OpenTelemetry] and add the following line to your `jvm.options` file.

[subs=+quotes]
----
-javaagent: _path/to/opentelemetry-javaagent.jar_
----

You can configure the agent with https://github.com/open-telemetry/opentelemetry-java-instrumentation#configuring-the-agent[environment variables and system properties]. You can find a list of supported libraries and frameworks in the https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks[OpenTelemetry Java instrumentation documentation].

[#limit]
==== Limitations of agent instrumentation

The OpenTelemetry Java agent is a tool that is provided by the OpenTelemetry project. Although it is compatible with Open Liberty, it is a separate project and is subject to the following limitations.
For more information about the available properties, see xref:microprofile-config-properties.adoc#telemetry[MicroProfile Config properties: MicroProfile Telemetry].

* Configuration works differently when you use the agent. https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/[Configuration of the agent is well documented], but the following aspects are different from configuration without the agent:
** Configuration is shared between all applications that are deployed to the server.
** Configuration properties are only read from system properties and environment variables. They are not read from MicroProfile Config configuration sources.
** Because the agent reads its configuration early in the startup process, system properties are not read from the `bootstrap.properties` file. Alternatively, you can set system properties in the `jvm.options` file by using the following syntax: `-Dname=value`
** Implementations of https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-autoconfigure-spi/1.19.0/index.html[SPI extensions] within applications are ignored. For more information, see the https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/#extensions[agent documentation for providing SPI extensions].
* When you use the agent, it takes over the instrumentation of REST calls and methods that are annotated with `@WithSpan`. As a result, the created spans might be slightly different.
* The agent is not compatible with https://www.ibm.com/docs/en/was-liberty/base?topic=security-java-2[Java 2 security].
* Open Liberty uses many open source libraries internally. Some of these libraries might be automatically instrumented by the agent.

[#trouble]
== Troubleshooting MicroProfile Telemetry
Expand Down
Loading