diff --git a/modules/ROOT/pages/microprofile-config-properties.adoc b/modules/ROOT/pages/microprofile-config-properties.adoc index b737b673b..2ebf3596f 100644 --- a/modules/ROOT/pages/microprofile-config-properties.adoc +++ b/modules/ROOT/pages/microprofile-config-properties.adoc @@ -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"] |=== @@ -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` @@ -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 diff --git a/modules/ROOT/pages/microprofile-telemetry.adoc b/modules/ROOT/pages/microprofile-telemetry.adoc index 60f116a11..7f6c3b146 100644 --- a/modules/ROOT/pages/microprofile-telemetry.adoc +++ b/modules/ROOT/pages/microprofile-telemetry.adoc @@ -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: + @@ -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: + @@ -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 `mpTelemetry-1.0` or `mpTelemetry-1.1` 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] ----- - - - ----- - -. 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] ----- - - io.opentelemetry - opentelemetry-api - 1.19.0 - provided - - - io.opentelemetry.instrumentation - opentelemetry-instrumentation-annotations - 1.19.0-alpha - provided - ----- - -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 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 diff --git a/modules/ROOT/pages/mptel-log-events-list.adoc b/modules/ROOT/pages/mptel-log-events-list.adoc index f55ec9175..7540683cc 100644 --- a/modules/ROOT/pages/mptel-log-events-list.adoc +++ b/modules/ROOT/pages/mptel-log-events-list.adoc @@ -14,7 +14,7 @@ MicroProfile Telemetry can collect logging events from the server runtime and applications. You can use these events to gather and analyze data that can help to better understand the behavior of applications. -For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry] +For more information, see xref:microprofile-telemetry.adoc[Enable observability with MicroProfile Telemetry]. MicroProfile Telemetry can collect the following types of events: @@ -22,15 +22,15 @@ MicroProfile Telemetry can collect the following types of events: * <> * <> -For information about trace log detail levels and how Open Liberty settings map to OpenTelemetry severity numbers, see <>. +For information about trace log detail levels and how Open Liberty settings map to OpenTelemetry severity numbers, see <>. == Message events -The following table provides the fields for message events and a description for each field: +The following table provides the fields for Liberty message events, a description for each field, and the mapping to the OpenTelemetry logs data model and Java agent: .Message event fields [options="header"] |======================= -| Liberty message event fields | Description | Maps to OTel Logs Data Model | OTel Java Agent JUL Mapping +| Liberty message event fields | Description | Maps to OTel logs data model | OTel Java agent (JUL) mapping | type | A string that identifies the type of event. | Attributes[`io.openliberty.type`] | N/A | host | Host name of the server that is the source of the event. | Resource[`host.name`] | Resource[`host.name`] | message | The message from the log record, starting with the message ID. | Body | body @@ -67,7 +67,7 @@ Attributes: ---- == Trace events -The following table provides the fields for trace events and a description for each field: +The following table provides the fields for Liberty trace events, a description for each field, and the mapping to the OpenTelemetry logs data model and Java agent: .Trace event fields [options="header"] @@ -108,7 +108,7 @@ Attributes: ---- == FFDC events -The following table provides the fields for the first failure data capture (FFDC) events and a description for each field: +The following table provides the fields for the first failure data capture (FFDC) events, a description for each fiel, and the mapping to the OpenTelemetry logs data model: .FFDC event fields |======================= diff --git a/modules/ROOT/pages/telemetry-trace.adoc b/modules/ROOT/pages/telemetry-trace.adoc new file mode 100644 index 000000000..585bec6ed --- /dev/null +++ b/modules/ROOT/pages/telemetry-trace.adoc @@ -0,0 +1,176 @@ +// Copyright (c) 2022 IBM Corporation and others. +// Licensed under Creative Commons Attribution-NoDerivatives +// 4.0 International (CC BY-ND 4.0) +// https://creativecommons.org/licenses/by-nd/4.0/ +// +// Contributors: +// IBM Corporation +// +:page-description: +:seo-description: +:page-layout: general-reference +:page-type: general += Code instrumentation for MicroProfile Telemetry tracing + +After you enable MicroProfile Telemetry and configure a trace server, you can instrument tracing in your application code. You can instrument your code automatically, manually, or by using the Java agent. + +* <<#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>>. + +[#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 `mpTelemetry-1.0` or `mpTelemetry-1.1` 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. + +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/ +---- + +To export traces to a Zipkin server, you can use the following properties instead: + +[source,properties] +---- +otel.sdk.disabled=false +otel.traces.exporter=zipkin +otel.exporter.zipkin.endpoint=http://localhost:9411/api/v2/spans +---- +//// + +[#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] +---- + + + +---- + +. 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. ++ +[source,xml] +---- + + io.opentelemetry + opentelemetry-api + 1.19.0 + provided + + + io.opentelemetry.instrumentation + opentelemetry-instrumentation-annotations + 1.19.0-alpha + provided + +---- + +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. ++ +[source,java] +---- +private static final AttributeKey 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. ++ +[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. ++ +[source,java] +---- +@ApplicationScoped +class SpanBean { + + @WithSpan("name") + void spanName() { + ... + } + + @WithSpan + void spanArgs(@SpanAttribute(value = "arg") String arg) { + ... + } +} +---- + +=== Considerations for 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. + +* 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.