search

OpenLiberty / docs

See Open Liberty documentation on https://openliberty.io/docs/
https://openliberty.io/docs/
Other
13 stars 47 forks source link

MicroProfile 6.0 Docs #6179

Closed tevans78 closed 1 year ago

tevans78 commented 1 year ago

This is a docs issue for the MicroProfile 6.0 umbrella feature.

We will need a new page which describes the differences between MP 5.0 and MP 6.0 (Similar to this one - https://openliberty.io/docs/latest/mp-41-50-diff.html).

A good starting point for this content would be to take the MP 6.0 section of the 22.0.0.13-beta blog post - https://openliberty.io/blog/2022/12/06/22.0.0.13-beta.html#mp6

More details to follow.

Emily-Jiang commented 1 year ago

The doc should have a page to highlight how to migrate from MP 5.0 to MP 6.0. This include the differences:

  1. migrating MP Metrics 4.0 to 5.0
  2. migrating MP OpenTracing 3.0 to MP Telemetry 1.0
Emily-Jiang commented 1 year ago

@dmuelle please add the following paragraph to MicroProfile 6.0 MicroProfile 6.0 is a major release. It includes Jakarta EE 10 Core Profile and replaces MicroProfile OpenTracing with MicroProfile Telemetry. Consequently, MicroProfile OpenTracing moves out of the umbrella release and becomes standalone.

Azquelt commented 1 year ago

Here's the doc for migration from mpOpenTracing-3.0 to mpTelemetry-1.0. @yasmin-aumeeruddy @fmhwong please can you review what I've written and see if there's anything I've missed.

Differences between MicroProfile OpenTracing 3.0 and MicroProfile Telemetry 1.0

MicroProfile Telemetry 1.0 replaces MicroProfile OpenTracing 3.0 due to the upstream OpenTracing project combining with OpenCensus to form the OpenTelemetry project.

Configuration changes

As well as updating the features in your server.xml, you must provide the correct configuration to allow the MicroProfile Telemetry feature to connect to your distributed trace service. See Enable distributed tracing with MicroProfile Telemetry for how to do this.

It's no longer necessary to package a client for your particular tracing service. MicroProfile Telemetry includes exporters for the OpenTelemetry Protocol (OTLP) (used Jaeger since v1.35), Zipkin and the older Jaeger protocol. If you need to export to a different service, it's possible to provide a custom exporter using the ConfigurableSpanExporterProvider SPI.

Selecting a compatible propagator

There are several different standards for propagating span information between microservices using HTTP headers. If you're upgrading microservices one at a time, you must enable a propagation method which is compatible with your other microservices.

The otel.propagators config property configures which propagators are used. The following values are available:

The default is tracecontext,baggage.

If more than one is enabled then all headers are added to outgoing requests and any header is accepted for incoming requests. For example, if you are migrating from using a Jaeger client, you might want to set otel.propagators=jaeger to use the Jaeger propagation protocol, or to otel.propagators=jaeger,tracecontext,baggage to use allow use of both the Jaeger and W3C protocols.

API changes

The OpenTelemetry API replaces the OpenTracing API. Both APIs are quite similar but any code which used the OpenTracing API will need to be updated to use the OpenTelemetry API. To ease migration, the OpenTelemetry project has created the OpenTracing shim which translates OpenTracing API calls into OpenTelemetry API calls allowing applications to be migrated piece by piece rather than all at once.

@Traced annotation

The @Traced annotation has been removed and how you migrate depends on where you were using it.

Beginning migration using the OpenTracing Shim

Update your application dependencies to remove the OpenTracing API and add the OpenTelemetry API as a provided dependency and the OpenTracing Shim as a regular dependency. For example, in your maven pom add these dependencies:

<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>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-opentracing-shim</artifactId>
    <version>1.19.0-alpha</version>
</dependency>

Note that just like mpOpenTracing-3.0, mpTelemetry-1.0 requires that you enable third-party APIs to use the API classes in your application.

The shim translates most calls to the OpenTracing API into calls to the OpenTelemetry API, but it doesn't make the OpenTracing Tracer available for injection.

To make injection of the OpenTracing Tracer work, you also need to add a CDI Producer Method which uses the shim to provide instances of the OpenTracing Tracer class for injection. Assuming that you haven't disabled CDI discovery, adding the following class to your application should be sufficient:

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.opentracingshim.OpenTracingShim;
import io.opentracing.Tracer;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;

@ApplicationScoped
public class ShimProvider {

    @Produces
    @ApplicationScoped
    private Tracer provideTracer(OpenTelemetry openTelemetry) {
        return OpenTracingShim.createTracerShim(openTelemetry);
    }

}

With the configuration changes and the shim in place, your application should run and export traces to your trace service. Be aware that there are some limitations when using the shim.

Switching to the OpenTelemetry API

Though the OpenTracing Shim allows you to continue using the OpenTracing API in your code, you may want to switch to using the OpenTelemetry API directly to take advantage of new features and to avoid the limitations of using the shim.

The OpenTelemetry API is quite similar to the OpenTracing API so the changes to your code will likely be quite straightforward. Where you previously injected io.opentracing.Tracer, you now need to inject io.opentelemetry.api.trace.Tracer and use the methods on that class to create new spans.

As an example, take the following code written for the OpenTracing API which creates and activates a span around an operation:

Span span = tracer.buildSpan("doOperation").start();
try (Scope childScope = tracer.activateSpan(span)) {
    doOperation();
} finally {
    span.finish();
}

The corresponding code which uses the OpenTelemetry API would look like this:

Span span = tracer.spanBuilder("doOperation").startSpan();
try (Scope childScope = span.makeCurrent()) {
    doOperation();
} finally {
    span.end();
}

The details of the OpenTelemetry API can be found in the javadoc. The OpenTelemetry documentation also contains some guidance on migrating to the OpenTelemetry API.

yasmin-aumeeruddy commented 1 year ago

@Azquelt That all looks good to me. I can't see anything that's missing

dmuelle commented 1 year ago

Hi @Azquelt @yasmin-aumeeruddy - I've updated the draft with these changes:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/mp-50-60-diff.html#telemetry

Azquelt commented 1 year ago

Can we change the section on OpenAPI? At the moment it says we've added a new config option but I think it would make more sense if we said we've added a new feature, and here is the config option to control it.

I would suggest something like this:

Differences between MicroProfile OpenAPI 3.1 and 3.0

The MicroProfile OpenAPI 3.1 release introduces support for enhancing generated schemas using information from Jakarta Bean Validation annotations. If this is not desired, it can be disabled by setting the mp.openapi.scan.beanvalidation MicroProfile Config property to false. This property can be set in [any of the configuration sources that are available to MicroProfile Config]. More information about this feature can be found in the MicroProfile OpenAPI 3.1 specification.

Not sure whether we should also keep the link to the list of config properties supported by MP OpenAPI.

dmuelle commented 1 year ago

Thanks, @Azquelt - I've made this update, with minor edits per ID guidelines:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/mp-50-60-diff.html#openapi

Azquelt commented 1 year ago

Look great, thanks @dmuelle

dmuelle commented 1 year ago

Hi @tevans78 @Emily-Jiang I believe this issue is ready for final review/signoff. Updates include:

Let me know if any further edits are needed. If not, either of you can sign off by adding the Technical reviewed label to this issue. Thanks

tevans78 commented 1 year ago

I think i would re-order the opening sentences a bit. From this

If you are updating your application from using MicroProfile 5.0 features to using [MicroProfile 6.0](https://github.com/eclipse/microprofile/releases/tag/6.0) features, changes in API behavior might require you to update your application code.

MicroProfile 6.0 is a major release. It includes [Jakarta EE 10 Core Profile](https://jakarta.ee/specifications/coreprofile/10/) and replaces MicroProfile OpenTracing with MicroProfile Telemetry. Consequently, MicroProfile OpenTracing moves out of the umbrella release and becomes a stand-alone specification.

The following sections provide details about migrating your applications from MicroProfile 5.0 to 6.0:

to this

[MicroProfile 6.0](https://github.com/eclipse/microprofile/releases/tag/6.0) is a major release. It includes [Jakarta EE 10 Core Profile](https://jakarta.ee/specifications/coreprofile/10/) and replaces MicroProfile OpenTracing with MicroProfile Telemetry. Consequently, MicroProfile OpenTracing moves out of the umbrella release and becomes a stand-alone specification.

If you are updating your application from using MicroProfile 5.0 features to using MicroProfile 6.0 features, changes in API behavior might require you to update your application code. The following sections provide details about migrating your applications from MicroProfile 5.0 to 6.0:
tevans78 commented 1 year ago

Confirm with Emily but I am not sure that I would bother mentioning the implementation details of Metrics 5.0 in a section that is really only talking about the APIs. In previous versions, Open Liberty implemented the specification in its own codebase. However, starting in MicroProfile Metrics 5.0, Open Liberty consumes SmallRye implementation of the specification to produce the [mpMetrics-5.0](https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpMetrics-5.0.html) feature.

The second mention of the implementation is fine. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/mp-50-60-diff.html#_integration_with_micrometer

dmuelle commented 1 year ago

Emily is ok with mentioning SmallRye in this context. I edited the opening sentences per Tom's recommendation but had to make some slight changes per ID guidelines for short description/opening paragraph. If any further changes are need please let me know. Otherwise, either of you can sign off by adding the Technical reviewed label to the issue.

Differences between MicroProfile 6.0 and 5.0

dmuelle commented 1 year ago

@ramkumar-k-9286 this is ready for peer review

ramkumar-k-9286 commented 1 year ago

Peer Review

Consequently, MicroProfile OpenTracing moves out of the umbrella release and becomes a stand-alone specification. -> Acrolinx suggestion ( Therefore / So to be used instead of Consequently)

The following sections provide details about migrating your applications from MicroProfile 5.0 to 6.0: (Replace : with .)

However, starting in MicroProfile Metrics 5.0, Open Liberty consumes SmallRye implementation of the specification to produce the mpMetrics-5.0 feature. -> However, starting in MicroProfile Metrics 5.0, Open Liberty uses the SmallRye implementation of the specification to produce the mpMetrics-5.0 feature. ( Acrolinx suggestion)

The following metric types are removed from the MicroProfile Metrics 5.0 release: (Replace : with .)

The following metric types are modified in the MicroProfile Metrics 5.0 release or have extra configuration properties from the SmallRye implementation: (Replace : with .)

The Prometheus formatted output is also updated, including the following changes : (Replace : with .)

In MicroProfile Metrics 5.0, this information is displayed with an mp_scope tag, for example, {mp_scope="base"}. -> In MicroProfile Metrics 5.0, this information is displayed with an mp_scope tag . For example, {mp_scope="base"}.

If you need to export to a different service, you can provide a custom exporter by using the ConfigurableSpanExporterProvider SPI. Q: SPI is mentioned only once in this doc. Should we expand - service provider interface (SPI)?

The otel.propagators configuration property configures which propagators are used. The following values are available: (Replace : with .)

Is there supposed to be a space before the baggage? The default value is tracecontext,baggage.

For example, add the following dependencies in your Maven pom.xml file: (Replace : with .)

If CDI discovery is enabled, you can add the following class to your application: (Replace : with .)

As an example, take the following code for the OpenTracing API, which creates and activates a span around an operation: (Replace : with .)

Corresponding code that uses the OpenTelemetry API is similar to the following example: (Replace : with .)

For more information about on the OpenTelemetry API, see the Javadoc. -> For more information on the OpenTelemetry API, see the Javadoc.

Can we put the 2 For more information in 2 separate lines?

dmuelle commented 1 year ago

Thanks for reviewing @ramkumar-k-9286 - all suggestions implemented except:

Open Liberty consumes SmallRye implementation

I think consumes is ok in this context

In MicroProfile Metrics 5.0, this information is displayed with an mp_scope tag . For example, {mp_scope="base"}.

I left this as is because "For example..." in this suggestion is a sentence fragment.

Is there supposed to be a space before the baggage? The default value is tracecontext,baggage.

No, these are 2 csv values. Not sure if whitespace is allowed but and I dont think it's needed in this context