diff --git a/CHANGELOG.md b/CHANGELOG.md index ac72eee791..ee0d2f2bf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ ## Version 1.5.0 2021-08-13: ### API -- The `io.opentelemetry.context.ContextStorage` interface now allows providing a root `Context`. +- The `io.opentelemetry.context.ContextStorage` interface now allows providing a root `Context`. ### SDK - The `io.opentelemetry.sdk.trace.samplers.SamplingResult` class has been enhanced with new factory methods for the static result values. @@ -16,7 +16,7 @@ #### SDK Extensions - The `opentelemetry-sdk-extension-resources` module now provides a new `ContainerResource` that auto-detects docker container Resource attributes. -- The Jaeger Remote Sampler in the `opentelemetry-sdk-extension-jaeger-remote-sampler` module is now `java.io.Closeable`. +- The Jaeger Remote Sampler in the `opentelemetry-sdk-extension-jaeger-remote-sampler` module is now `java.io.Closeable`. #### Testing - The SDK testing module (`opentelemetry-sdk-testing`) has been enhanced with additional assertions for Spans and Attributes. @@ -31,7 +31,7 @@ - The `opentelemetry-sdk-extension-autoconfigure` module now provides an option to *not* set the GlobalOpenTelemetry instance when auto-configuring. - The `opentelemetry-sdk-extension-autoconfigure` module now has support for signal-specific timeout, header and TLS certificate configuration. - A new SPI option is available for configuring a metrics exporter. See `io.opentelemetry.sdk.autoconfigure.spi.ConfigurableMetricExporterProvider` for details. -- A new `OTEL_TRACES_SAMPLER`/`otel.traces.sampler` option is available: `jaeger_remote`. +- A new `OTEL_TRACES_SAMPLER`/`otel.traces.sampler` option is available: `jaeger_remote`. - It can be configured using the `OTEL_TRACES_SAMPLER_ARG`/`otel.traces.sampler.arg`, which is parsed as a comma-separated map. - For example `-Dotel.traces.sampler=jaeger_remote -Dotel.traces.sampler.arg=endpoint=192.168.1.5:14250,pollingInterval=5000,initialSamplingRate=0.01` @@ -40,8 +40,8 @@ as of specification release `1.5.0`. ### Metrics (alpha) -- BREAKING CHANGE: The Metrics API has been completely re-written to match the newly specified API. -Please reach out on CNCF slack in the [#otel-java](https://cloud-native.slack.com/archives/C014L2KCTE3) channel, +- BREAKING CHANGE: The Metrics API has been completely re-written to match the newly specified API. +Please reach out on CNCF slack in the [#otel-java](https://cloud-native.slack.com/archives/C014L2KCTE3) channel, or in a [github discussion](https://github.com/open-telemetry/opentelemetry-java/discussions) if you need assistance with converting to the new API. - A new `opentelemetry-exporter-otlp-http-metrics` module is now available to support OTLP over HTTP exports. @@ -55,7 +55,7 @@ OpenTelemetry Collector which do not support the new protocol yet. ### API #### Enhancements -- You can now assign an OpenTelemetry schema URL to a `Tracer` via the new `TracerBuilder` class that is +- You can now assign an OpenTelemetry schema URL to a `Tracer` via the new `TracerBuilder` class that is accessed via the `TracerProvider` or any of the global instances that delegate to one. #### Extensions @@ -65,21 +65,21 @@ has no implementation in this release, but should be supported by the auto-instr ### Exporters #### Bugfixes - Calling `shutdown()` multiple times on the OTLP and Jaeger GRPC-based exporters will now work correctly and return a proper -implementation of `CompletableResultCode` for the calls beyond the first. +implementation of `CompletableResultCode` for the calls beyond the first. ### SDK #### Bugfixes - If the `jdk.unsupported` package is not available, the `BatchSpanProcessor` will now fall back to a supported, standard `Queue` implementation. #### Enhancements -- A `Resource` can now be assigned an OpenTelemetry schema URL via the `ResourceBuilder` or the `create(Attributes, String)` +- A `Resource` can now be assigned an OpenTelemetry schema URL via the `ResourceBuilder` or the `create(Attributes, String)` method on the `Resource` itself. - You can now obtain a default `Clock` based on system time via `Clock.getDefault`. The sdk-testing artifact also provides a `TestClock` for unit testing. ### Semantic Conventions (alpha) - The `SemanticAttributes` and `ResourceAttributes` classes have been updated to match the semantic conventions -as of specification release `1.4.0`. These classes also now expose a `SCHEMA_URL` field which points at the +as of specification release `1.4.0`. These classes also now expose a `SCHEMA_URL` field which points at the version of the OpenTelemetry schema the files were generated from. There are no breaking changes in this update, only additions. ### Metrics (alpha) @@ -99,7 +99,7 @@ accessed via the `MeterProvider` or any global instances that delegate to one. #### Behavioral Changes - The implementation of SpanBuilder will no longer throw exceptions when null parameters are passed in. Instead, it will treat these calls as no-ops. - + #### Enhancements - Memory usage of the Tracing SDK has been greatly reduced when exporting via the OTLP or Jaeger exporters. - The OTLP protobuf version has been updated to v0.9.0 @@ -142,7 +142,7 @@ a more Android-friendly `IdGenerator` instance in that case. This will affect an explicitly specify a custom `IdGenerator` instance when running on Android. #### Behavioral Changes -- The name used for Tracer instances that do not have a name has been changed to be an empty String, rather than the +- The name used for Tracer instances that do not have a name has been changed to be an empty String, rather than the previously used `"unknown"` value. This change is based on a specification clarification. ### Propagators @@ -158,14 +158,14 @@ the headers are unparsable. It will now return the provided Context instance una ### Exporters - The `jaeger-thrift` exporter has had its dependency on the `jaeger-client` library updated to version `1.6.0`. -- The `zipkin` exporter now has an option to specific a custom timeout. -- The `zipkin`, `jaeger` and `jaeger-thrift` exporters will now report the `otel.dropped_attributes_count` and `otel.dropped_events_count` +- The `zipkin` exporter now has an option to specific a custom timeout. +- The `zipkin`, `jaeger` and `jaeger-thrift` exporters will now report the `otel.dropped_attributes_count` and `otel.dropped_events_count` tags if the numbers are greater than zero. ### Semantic Conventions (alpha) #### Breaking Changes -- The SemanticAttributes and ResourceAttributes have both been updated to match the OpenTelemetry Specification v1.3.0 release, which +- The SemanticAttributes and ResourceAttributes have both been updated to match the OpenTelemetry Specification v1.3.0 release, which includes several breaking changes. - Values that were previously defined as `enum`s are now defined as static `public static final ` constants of the appropriate type. @@ -175,13 +175,13 @@ includes several breaking changes. - Error logging support in the shim is now implemented according to the v1.2.0 specification. ### SDK Extensions -- A new `HostResource` Resource and the corresponding `ResourceProvider` has been added. +- A new `HostResource` Resource and the corresponding `ResourceProvider` has been added. It will populate the `host.name` and `host.arch` Resource Attributes. - A new `ExecutorServiceSpanProcessor` has been added to the `opentelemetry-sdk-extension-tracing-incubator` module. This implementation of a batch SpanProcessor allows you to provide your own ExecutorService to do the background export work. -- The `autoconfigure` module now supports providing the timeout setting for the Jaeger GRPC exporter via +- The `autoconfigure` module now supports providing the timeout setting for the Jaeger GRPC exporter via a system property (`otel.exporter.jaeger.timeout`) or environment variable (`OTEL_EXPORTER_JAEGER_TIMEOUT`). -- The `autoconfigure` module now supports providing the timeout setting for the Zipkin exporter via +- The `autoconfigure` module now supports providing the timeout setting for the Zipkin exporter via a system property (`otel.exporter.zipkin.timeout`) or environment variable (`OTEL_EXPORTER_ZIPKIN_TIMEOUT`). - The `autoconfigure` module now exposes the `EnvironmentResource` class to provide programmatic access to a `Resource` built from parsing the `otel.resource.attributes` configuration property. @@ -193,10 +193,10 @@ built from parsing the `otel.resource.attributes` configuration property. be changed once the `SdkMeterProvider` has been built. #### Bugfixes -- OTLP summaries now have the proper percentile value of `1.0` to represent the maximum; previously it was wrongly set to `100.0`. +- OTLP summaries now have the proper percentile value of `1.0` to represent the maximum; previously it was wrongly set to `100.0`. #### Enhancements -- There is now full support for delta-aggregations with the `LongSumAggregator` and `DoubleSumAggregator`. +- There is now full support for delta-aggregations with the `LongSumAggregator` and `DoubleSumAggregator`. See `AggregatorFactory.sum(AggregationTemporality)`. The previous `AggregatorFactory.sum(boolean)` has been deprecated and will be removed in the next release. @@ -208,20 +208,20 @@ deprecated and will be removed in the next release. #### Bugfixes -- We now use our own internal `@GuardedBy` annotation for errorprone so there won't be an accidental +- We now use our own internal `@GuardedBy` annotation for errorprone so there won't be an accidental transitive dependency on a 3rd-party jar. - The `TraceStateBuilder` now will not crash when an empty value is provided. - + #### Enhancements -- The `Context` class now provides methods to wrap `java.util.concurrent.Executor` and `java.util.concurrent.ExecutorService` +- The `Context` class now provides methods to wrap `java.util.concurrent.Executor` and `java.util.concurrent.ExecutorService` instances to do context propagation using the current context. See `io.opentelemetry.context.Context.taskWrapping(...)` for more details. - + ### OpenTracing Shim (alpha) -- The shim now supports methods that take a timestamp as a parameter. -- You can now specify both the `TEXT_MAP` and the `HTTP_HEADER` type propagators for the shim. +- The shim now supports methods that take a timestamp as a parameter. +- You can now specify both the `TEXT_MAP` and the `HTTP_HEADER` type propagators for the shim. See `io.opentelemetry.opentracingshim.OpenTracingPropagators` for details. ### Extensions @@ -240,7 +240,7 @@ via a CompletableResultCode when `forceFlush()` is called. Similiarly, this is a #### Enhancements -- The SpanBuilder provided by the SDK will now ignore `Link` entries that are reference an invalid SpanContext. +- The SpanBuilder provided by the SDK will now ignore `Link` entries that are reference an invalid SpanContext. This is an update from the OpenTelemetry Specification v1.1.0 release. - The OTLP Exporters will now log more helpful messages when the collector is unavailable or misconfigured. - The internals of the `BatchSpanProcessor` have had some optimization done on them, to reduce CPU @@ -260,16 +260,16 @@ log message per minute. #### Enhancements - The `autoconfigure` module now supports `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` -settings, in addition to the combined `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. Corresponding +settings, in addition to the combined `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. Corresponding system properties are also supported (`-Dotel.exporter.otlp.metrics.endpoint` and `-Dotel.exporter.otlp.traces.endpoint`). -- An `SdkMeterProviderConfigurer` SPI is now available in the `autoconfigure` module. +- An `SdkMeterProviderConfigurer` SPI is now available in the `autoconfigure` module. ### Semantic Conventions (alpha) - The SemanticAttributes and ResourceAttributes have both been updated to match the OpenTelemetry Specification v1.1.0 release. This includes a breaking changes to the constants defined in the `ResourceAttributes` class: `ResourceAttributes.CLOUD_ZONE` has been replaced with `ResourceAttributes.CLOUD_AVAILABILITY_ZONE`. - + ### Metrics (alpha) #### Breaking Changes @@ -281,7 +281,7 @@ to add views have been deprecated. They will be removed in the next release. #### Enhancements -- A new option for aggregation as Histograms is now available. +- A new option for aggregation as Histograms is now available. --- ## Version 1.0.1 - 2021-03-11 @@ -295,14 +295,14 @@ to add views have been deprecated. They will be removed in the next release. ### General -This releases marks the first stable release for the tracing, baggage and context APIs and the SDK. +This releases marks the first stable release for the tracing, baggage and context APIs and the SDK. Please see the [Versioning](VERSIONING.md) document for stability guarantees. -The best source of lsit of the now stable packages can be found in the +The best source of lsit of the now stable packages can be found in the [opentelemetry-bom](https://repo1.maven.org/maven2/io/opentelemetry/opentelemetry-bom/1.0.0/opentelemetry-bom-1.0.0.pom) artifact in maven central. -Javadoc is available at javadoc.io. +Javadoc is available at javadoc.io. For example, [javadoc.io](https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/1.0.0/index.html) for the API module. @@ -323,7 +323,7 @@ internal package. --- ## Version 0.17.1 - 2021-02-19 -- Removed the unused `ResourceProvider` interface from the SDK. This interface is still available +- Removed the unused `ResourceProvider` interface from the SDK. This interface is still available in the `opentelemetry-sdk-extension-autoconfigure` module, where it is actually used. ## Version 0.17.0 - 2021-02-17 - RC#3 @@ -336,7 +336,7 @@ aware that these changes will impact users. If you need assistance in migrating please open a [discussion topic](https://github.com/opentelemetry/opentelemetry-java/discussions) at [https://github.com/opentelemetry/opentelemetry-java/discussions](https://github.com/opentelemetry/opentelemetry-java/discussions). -Many classes have been made final that previously were not. Please reach out if you have a need to +Many classes have been made final that previously were not. Please reach out if you have a need to provide extended functionality, and we can figure out how best to solve your use-case. ### API @@ -344,10 +344,10 @@ provide extended functionality, and we can figure out how best to solve your use #### Breaking Changes - `TraceStateBuilder.set(String, String)` has been renamed to `TraceStateBuilder.put(String, String)`. -- `BaggageBuilder.setParent()` and `BaggageBuilder.setNoParent()` have been removed from the Baggage APIs. +- `BaggageBuilder.setParent()` and `BaggageBuilder.setNoParent()` have been removed from the Baggage APIs. In addition, Baggage will no longer be implicitly generated from Baggage that is in the current context. You now must explicitly get the `Baggage` instance from the `Context` and call `toBuilder()` on it in order to get the entries pre-populated in your builder. -- `TextMapPropagator.Setter` and `TextMapPropagator.Getter` have been moved to the top level and renamed to +- `TextMapPropagator.Setter` and `TextMapPropagator.Getter` have been moved to the top level and renamed to `TextMapSetter` and `TextMapGetter` respectively. - `OpenTelemetry.getDefault()` has been renamed to `OpenTelemetry.noop()`. - `OpenTelemetry.getPropagating()` has been renamed to `OpenTelemetry.propagating()`. @@ -361,14 +361,14 @@ get the `Baggage` instance from the `Context` and call `toBuilder()` on it in or #### Breaking Changes -- The SPI for configuring Resource auto-populators has been removed from the SDK and moved to the `opentelemetry-sdk-extension-autoconfigure` module. +- The SPI for configuring Resource auto-populators has been removed from the SDK and moved to the `opentelemetry-sdk-extension-autoconfigure` module. This means that `Resource.getDefault()` will no longer be populated via SPI, but only include the bare minimum values from the SDK itself. In order to get the auto-configured Resource attributes, you will need to use the `opentelemetry-sdk-extension-autoconfigure` module directly. - `InstrumentationLibraryInfo.getEmpty()` has been renamed to `InstrumentationLibraryInfo.empty()`. - `Resource.getEmpty()` has been renamed to `Resource.empty()`. - When specifying the endpoints for grpc-based exporters, you now are required to specify the protocol. Hence, you must include the `http://` or `https://` in front of your endpoint. -- The option on `SpanLimits` to truncate String-valued Span attributes has been removed (this is still pending in the specification). +- The option on `SpanLimits` to truncate String-valued Span attributes has been removed (this is still pending in the specification). - The `InMemoryMetricsExporter` has been removed from the `opentelemetry-sdk-testing` module. #### Miscellaneous @@ -401,7 +401,7 @@ the `http://` or `https://` in front of your endpoint. Note: In an effort to accelerate our work toward a 1.0.0 release, we have skipped the deprecation phase on a number of breaking changes. We apologize for the inconvenience this may have caused. We are very aware that these changes will impact users. If you need assistance in migrating from previous releases, -please open a [discussion topic](https://github.com/opentelemetry/opentelemetry-java/discussions) at +please open a [discussion topic](https://github.com/opentelemetry/opentelemetry-java/discussions) at [https://github.com/opentelemetry/opentelemetry-java/discussions](https://github.com/opentelemetry/opentelemetry-java/discussions). #### Breaking Changes @@ -418,7 +418,7 @@ implementation, it can be accessed via new static methods on the `OpenTelemetry` - The `TraceFlags` interface has been re-introduced. This is now used, rather than a bare `byte` wherever trace flags is used. In particular, `SpanContext.create()`, `SpanContext.createFromRemoteParent()` now require a `TraceFlags` instance, and `SpanContext.getTraceFlags()` returns a `TraceFlags` instance. -- The names of static methods on `TraceFlags` have been normalized to match other similar classes, and now +- The names of static methods on `TraceFlags` have been normalized to match other similar classes, and now return `TraceFlags` instead of `byte` where appropriate. - The `Labels` interface and related classes have been moved into the alpha metrics modules and repackaged. - `TraceId.copyHexInto(byte[] traceId, char[] dest, int destOffset)` has been removed. @@ -429,7 +429,7 @@ return `TraceFlags` instead of `byte` where appropriate. - `TraceFlags.isSampledFromHex(CharSequence src, int srcOffset)` has been removed. - `SpanId` and `TraceId` methods that had a `String` parameter now accept `CharSequence` and assume the id starts at the beginning. -- `SpanId.getSize()` and `TraceId.getSize()` have been removed. +- `SpanId.getSize()` and `TraceId.getSize()` have been removed. - `SpanId.bytesFromHex()` has been removed. - `SpanId.asLong(CharSequence)` has been removed. - `SpanId.asBytes(CharSequence)` has been removed. @@ -449,7 +449,7 @@ and assume the id starts at the beginning. - The `W3CTraceContextPropagator` class now directly implements the `TextMapPropagator` interface. - The `OpenTelemetry` interface now has a `getDefault()` method which will return a completely no-op implementation. - The `OpenTelmmetry` interface now has a `getPropagating(ContextPropagators propagators)` method which will -return an implementation that contains propagators, but is otherwise no-op. +return an implementation that contains propagators, but is otherwise no-op. #### Misc Notes @@ -480,16 +480,16 @@ All related method names have been renamed to match. #### Breaking Changes -- In the `opentelemetry-autoconfigure` module, three environment variables/system properties +- In the `opentelemetry-autoconfigure` module, three environment variables/system properties have been renamed to match the spec: * `OTEL_TRACE_EXPORTER`/`otel.trace.exporter` has been replaced with `OTEL_TRACES_EXPORTER`/`otel.traces.exporter` * `OTEL_TRACE_SAMPLER`/`otel.trace.sampler` has been replaced with `OTEL_TRACES_SAMPLER`/`otel_traces_sampler` - * `OTEL_TRACE_SAMPLER_ARG`/`otel.trace.sampler.arg` has been replaced with `OTEL_TRACES_SAMPLER_ARG`/`otel.traces.sampler.arg` + * `OTEL_TRACE_SAMPLER_ARG`/`otel.trace.sampler.arg` has been replaced with `OTEL_TRACES_SAMPLER_ARG`/`otel.traces.sampler.arg` #### Enhancements -- The `opentelemetry-autoconfigure` module now supports using non-millisecond values for duration & -interval configuration options. See the javadoc on the `io.opentelemetry.sdk.autoconfigure.ConfigProperties.getDuration(String)` +- The `opentelemetry-autoconfigure` module now supports using non-millisecond values for duration & +interval configuration options. See the javadoc on the `io.opentelemetry.sdk.autoconfigure.ConfigProperties.getDuration(String)` method for details on supported formats. - The `opentelemetry-autoconfigure` module now provides automatic SPI-based parsing of the `OTEL_RESOURCE_ATTRIBUTES` env var (and the corresponding `otel.resource.attributes` system property). If you include this module on your @@ -499,7 +499,7 @@ classpath, it will automatically update the `Resource.getDefault()` instance wit #### API -- The `Labels` interface has been moved into the metrics API module and repackaged into the +- The `Labels` interface has been moved into the metrics API module and repackaged into the `io.opentelemetry.api.metrics.common` package. --- @@ -525,8 +525,8 @@ generated form the Resource semantic conventions have been deprecated. Please us #### Enhancements -- A new `io.opentelemetry.semconv.resource.attributes.ResourceAttributes` has been introduced to hold the -generated semantic attributes to be used in creating `Resource`s. +- A new `io.opentelemetry.semconv.resource.attributes.ResourceAttributes` has been introduced to hold the +generated semantic attributes to be used in creating `Resource`s. ### SDK @@ -535,13 +535,13 @@ generated semantic attributes to be used in creating `Resource`s. - `SamplingResult.Decision` has been removed in favor of the `io.opentelemetry.sdk.trace.samplers.SamplingDecision` top-level class. - `Resource.merge(Resource)` now will resolve conflicts by preferring the `Resource` passed in, rather than the original. - The default Resource (accessible via `Resource.getDefault()`) now includes a fallback `service.name` attribute. The implication -of this is that exporters that have configured fallback service names will only use them if the SDK is intentionally +of this is that exporters that have configured fallback service names will only use them if the SDK is intentionally configured with a Resource that does not utilize the default Resource for its underlying Resource data. -- The `Sampler` is now specified when building the SdkTracerProvider directly, rather than being a part of the TraceConfig. +- The `Sampler` is now specified when building the SdkTracerProvider directly, rather than being a part of the TraceConfig. #### Bugfixes -- The Jaeger exporters will now properly populate the process service name from the Resource service.name attribute. +- The Jaeger exporters will now properly populate the process service name from the Resource service.name attribute. #### Deprecations @@ -556,19 +556,19 @@ Please use the new `io.opentelemetry.semconv.resource.attributes.ResourceAttribu module. - The serviceName configuration option for the Jaeger and Zipkin exporters has been deprecated. In the next release, those configuration options will be removed, and the fallback `service.name` will always be pulled from the default Resource. - + #### Enhancements - `Resource.getDefault()` now includes a fallback `service.name` attribute. Exporters that require a `service.name` should acquire the fallback from the default resource, rather than having it configured in. - + ### SDK Extensions #### Breaking Changes -- The `otel.bsp.schedule.delay.millis` env var/system property configuration option for the batch span processor has been renamed to +- The `otel.bsp.schedule.delay.millis` env var/system property configuration option for the batch span processor has been renamed to `otel.bsp.schedule.delay` to match the specification. -- The `otel.bsp.export.timeout.millis` env var/system property configuration option for the batch span processor has been renamed to +- The `otel.bsp.export.timeout.millis` env var/system property configuration option for the batch span processor has been renamed to `otel.bsp.export.timeout` to match the specification. #### Enhancements @@ -598,7 +598,7 @@ property for specifying a path to a trusted certificate for the OTLP exporters. #### Breaking Changes - Code that was deprecated in `0.13.0` has been removed from the project. - - Metrics interfaces are no longer available as a part of the `opentelemetry-pom` or from the `opentelemetry-api` modules. + - Metrics interfaces are no longer available as a part of the `opentelemetry-pom` or from the `opentelemetry-api` modules. To access the alpha metrics APIs, you will need to explicitly add them as a dependency. - `OpenTelemetry.setPropagators()` has been removed. You should instead create your `OpenTelemetry` implementations with the Propagators preset, via the various builder options. For example, use @@ -606,12 +606,12 @@ property for specifying a path to a trusted certificate for the OTLP exporters. - The `OpenTelemetry.builder()` and the `OpenTelemetryBuilder` interface have been removed. The builder functionality is now only present on individual implementations of OpenTelemetry. For instance, the `DefaultOpenTelemetry` class has a builder available. - + #### Deprecations - The SemanticAttributes class has been moved to a new module: `opentelemetry-semconv` and repackaged into a new package: `io.opentelemetry.semconv.trace.attributes`. The old `SemanticAttributes` class will be removed in the next release. -- The SPI interfaces for OpenTelemetry have been deprecated. We are moving to a new auto-configuration approach with the +- The SPI interfaces for OpenTelemetry have been deprecated. We are moving to a new auto-configuration approach with the new SDK auto-configuration module: `io.opentelemetry.sdk.autoconfigure`. This module should be considered the officially supported auto-configuration library moving forward. @@ -623,19 +623,19 @@ supported auto-configuration library moving forward. #### Bugfixes -- Environment variables/system properties that are used to set extra headers for the OTLP exporters have been fixed to now +- Environment variables/system properties that are used to set extra headers for the OTLP exporters have been fixed to now split on commas, rather than semicolons. This has been brought in line with the specification for these environment variables. This includes `otel.exporter.otlp.span.headers`, `otel.exporter.otlp.metric.headers`, and `otel.exporter.otlp.headers`. -- Passing a null span name when creating a span will no longer cause a NullPointerException. Instead, a default span name will be +- Passing a null span name when creating a span will no longer cause a NullPointerException. Instead, a default span name will be provided in place of the missing name. #### Breaking Changes - The deprecated `SpanData.Link.getContext()` method has been removed in favor of `SpanData.Link.getSpanContext()`. - The `TracerProviderFactorySdk` SPI class has been renamed to `SdkTracerProviderFactory`. -- The `OpenTelemetrySdkBuilder.build()` method has been renamed to `OpenTelemetrySdkBuilder.buildAndRegisterGlobal()`. +- The `OpenTelemetrySdkBuilder.build()` method has been renamed to `OpenTelemetrySdkBuilder.buildAndRegisterGlobal()`. The `build()` method still exists, but no longer sets the instance on the `GlobalOpenTelemetry` when invoked. -- The `SdkTracerManagement.shutdown()` method now returns `CompletableResultCode` which can be used to wait +- The `SdkTracerManagement.shutdown()` method now returns `CompletableResultCode` which can be used to wait asynchronously for shutdown to complete. - The `sampling.probability` sampling attribute previously generated by the `TraceIdRatioBasedSampler` is no longer generated, as it was not conformant with the specifications. @@ -650,7 +650,7 @@ will be removed in the next release. module. The existing ones will be removed in the next release. - The methods with the term "deadline" has been deprecated in the configuration of the grpc-based exporters (OTLP and Jaeger) in favor of the word "timeout". The deadline-named methods will be removed in the next release. -- The `StringUtils` class in the `opentelemetry-extension-trace-propagators` extension module has been deprecated +- The `StringUtils` class in the `opentelemetry-extension-trace-propagators` extension module has been deprecated and will be made non-public in the next release. - The `StatusData.isUnset()` and `StatusData.isOk()` methods have been deprecated. They will be removed in the next release. @@ -660,7 +660,7 @@ and will be made non-public in the next release. - A new module for supporting auto-configuration of the SDK has been added. The new module, `io.opentelemetry.sdk.autoconfigure` will be the new path for auto-configuration of the SDK, including via SPI, environment variables and system properties. - The `TraceConfig` class now exposes a `builder()` method directly, so you don't need to get the default then call `toBuilder()` on it. -- The OTLP protobuf definitions were updated to the latest released version: `0.7.0`. +- The OTLP protobuf definitions were updated to the latest released version: `0.7.0`. Both the `Span` and (alpha) `Metric` exporters were updated to match. - Timeouts in the exporters can now be specified with `java.util.concurrent.TimeUnit` and `java.time.Duration` based configurations, rather than requiring milliseconds. @@ -677,9 +677,9 @@ of the builders in the project. #### Deprecations - The `AwsXrayIdGenerator` constructor has been deprecated in favor of using a simple `getInstance()` singleton, since it has no state. -- The `TraceProtoUtils` class in the `opentelemetry-sdk-extension-otproto` module has been deprecated and +- The `TraceProtoUtils` class in the `opentelemetry-sdk-extension-otproto` module has been deprecated and will be removed in the next release. - + #### Bugfixes - The JaegerRemoteSampler now uses the ParentBased sampler as the basis for any sampling that is done. @@ -701,21 +701,21 @@ the methods on the Builder have changed to use the same naming patterns as the r ### General - Starting with 0.13.0, all unstable modules (the 2 metrics modules for now) will have a `-alpha` appended to their - base version numbers to make it clear they are not production ready, and will not be when we get to releasing 1.0. + base version numbers to make it clear they are not production ready, and will not be when we get to releasing 1.0. See our [Rationale](docs/rationale.md) document for details. ### API #### Breaking Changes -- The `Labels.ArrayBackedLabelsBuilder` class has been made non-public. +- The `Labels.ArrayBackedLabelsBuilder` class has been made non-public. You can still access the `LabelsBuilder` functionality via the `Labels.builder()` method. - Methods deprecated in the 0.12.0 release have been removed or made non-public: - The `HttpTraceContext` class has been removed. - The `toBuilder()` method on the OpenTelemetry interface has been removed. - The `Attributes.builder(Attributes)` method has been removed in favor of `Attributes.toBuilder(Attributes)`. - The `DefaultContextPropagators` class has made non-public. - - The `TraceMultiPropagator` builder has been removed in favor of a simple factory method. + - The `TraceMultiPropagator` builder has been removed in favor of a simple factory method. - The `value()` method on the `StatusCode` enum has been removed. - The Baggage `EntryMetadata` class has been removed in favor of the `BaggageEntryMetadata` interface. - The `setCallback()` method on the asynchronous metric instruments has been removed. @@ -725,9 +725,9 @@ You can still access the `LabelsBuilder` functionality via the `Labels.builder() - An `asMap` method has been added to the `Labels` interface, to expose them as a `java.util.Map`. - You can now enable strict Context verification via a system property (`-Dio.opentelemetry.context.enableStrictContext=true`) - Enabling this mode will make sure that all `Scope`s that are created are closed, and generate log messages if they + Enabling this mode will make sure that all `Scope`s that are created are closed, and generate log messages if they are not closed before being garbage collected. This mode of operation is CPU intensive, so be careful before - enabling it in high-throughput environments that do not need this strict verification. See the javadoc on the + enabling it in high-throughput environments that do not need this strict verification. See the javadoc on the `io.opentelemetry.context.Context` interface for details. - Several of the methods on the `Span` interface have been given default implementations. - The Semantic Attributes constants have been updated to the version in the yaml spec as of Dec 14, 2020. @@ -742,14 +742,14 @@ You can still access the `LabelsBuilder` functionality via the `Labels.builder() The builder functionality is now only present on individual implementations of OpenTelemetry. For instance, the `DefaultOpenTelemetry` class has a builder available. - The `OpenTelemetry.setPropagators()` has been deprecated and will be removed in the next release. You should instead create your - `OpenTelemetry` implementations with the Propagators preset, via the various builder options. For example, use + `OpenTelemetry` implementations with the Propagators preset, via the various builder options. For example, use `DefaultOpenTelemetry.builder().setPropagators(propagators).build()` to configure your no-sdk implementation. ### SDK #### Miscellaneous -- The `SpanData.Link.getContext()` method has been deprecated in favor of a new `SpanData.Link.getSpanContext()`. +- The `SpanData.Link.getContext()` method has been deprecated in favor of a new `SpanData.Link.getSpanContext()`. The deprecated method will be removed in the next release of the SDK. - The internals of the (alpha) Metrics SDK have been significantly updated. - OTLP adapter classes have been moved into the `opentelemetry-sdk-extension-otproto` module so they can be shared across OTLP usages. @@ -769,11 +769,11 @@ You can still access the `LabelsBuilder` functionality via the `Labels.builder() - The built-in ParentBasedSampler `Builder` class has been moved to the top level, rather than inner classes. Access to the builder is still available via methods on the Sampler interface. - The `DaemonThreadFactory` class has been moved to an internal module and should not be used outside of this repository. -- The builder class for the `OpenTelemetrySdk` class has been slimmed down. The configurable details have been moved into +- The builder class for the `OpenTelemetrySdk` class has been slimmed down. The configurable details have been moved into the specific provider builders, where they apply more specifically and obviously. - Many public classes have been made `final`. - The MetricExporter interface's `shutdown()` method now returns `CompletableResultCode` rather than void. -- The `OpenTelemetrySdk`'s builder class has been moved to the top level, rather than being an inner class. It has been renamed to +- The `OpenTelemetrySdk`'s builder class has been moved to the top level, rather than being an inner class. It has been renamed to `OpenTelemetrySdkBuilder` as a part of that change. - The OTLP exporters have been split into two separate modules, and the metrics exporter has been tagged with the `-alpha` version. If you continue to depend on the `opentelemetry-exporters-otlp` module, you will only get the trace exporter as a transitive dependency. @@ -786,14 +786,14 @@ You can still access the `LabelsBuilder` functionality via the `Labels.builder() #### Breaking Changes -- The deprecated `opentelemetry-extension-runtime-metrics` module has been removed. The functionality is available in the +- The deprecated `opentelemetry-extension-runtime-metrics` module has been removed. The functionality is available in the opentelemetry-java-instrumentation project under a different module name. - The deprecated `trace-utils` module has been removed. - Several public classes have been made `final`. #### Enhancements -- Some common OTLP adapter utilities have been moved into the `opentelemetry-sdk-extension-otproto` module so they can +- Some common OTLP adapter utilities have been moved into the `opentelemetry-sdk-extension-otproto` module so they can be shared across OTLP exporters. --- @@ -817,7 +817,7 @@ This has been corrected, and all instances should have independent Tracer and Me used or returned `ReadableAttributes` should accept or return standard `Attributes` implementations. - `SpanContext` has been converted to an interface, from an abstract class. Its API has otherwise remained the same. - The functional `AttributeConsumer` interface has been removed and replaced with a standard `java.util.function.BiConsumer`. -- The signature of the `BaggageBuilder.put(String, String, EntryMetadata entryMetadata)` +- The signature of the `BaggageBuilder.put(String, String, EntryMetadata entryMetadata)` method has been changed to `put(String, String, BaggageEntryMetadata)` #### Enhancements @@ -834,18 +834,18 @@ method has been changed to `put(String, String, BaggageEntryMetadata)` - The `toBuilder()` method on the OpenTelemetry interface has been deprecated and will be removed in 0.13.0. - The `DefaultContextPropagators` class has been deprecated. Access to it will be removed in 0.13.0. - The `TraceMultiPropagator` builder has been deprecated in favor of a simple factory method. The builder will be removed in 0.13.0. -You can access the same functionality via static methods on the `ContextPropagators` interface. -- The `setCallback()` method on the asynchronous metric instruments has been deprecated and will be removed in 0.13.0. +You can access the same functionality via static methods on the `ContextPropagators` interface. +- The `setCallback()` method on the asynchronous metric instruments has been deprecated and will be removed in 0.13.0. Instead, use the `setCallback()` method on the builder for the instruments. - The `value()` method on the `StatusCode` enum has been deprecated and will be removed in 0.13.0. - The Baggage `EntryMetadata` class has been deprecated in favor of the `BaggageEntryMetadata` interface. The class will be made non-public in 0.13.0. ### Extensions -- The `opentelemetry-extension-runtime-metrics` module has been deprecated. The functionality is available in the +- The `opentelemetry-extension-runtime-metrics` module has been deprecated. The functionality is available in the opentelemetry-java-instrumentation project under a different module name. The module here will be removed in 0.13.0. - The `trace-utils` module has been deprecated. If you need this module, please let us know! The module will be removed in 0.13.0. - + ### SDK #### Breaking Changes @@ -875,7 +875,7 @@ you can now call `SpanData.getParentSpanContext().isRemote()`. #### Breaking Changes -- The `opentelemetry-sdk-extension-aws-v1-support` module has been renamed to `opentelemetry-sdk-extension-aws` +- The `opentelemetry-sdk-extension-aws-v1-support` module has been renamed to `opentelemetry-sdk-extension-aws` and the classes in it have been repackaged into the `io.opentelemetry.sdk.extension.aws.*` packages. #### Bugfixes: @@ -896,7 +896,7 @@ This is included in the Resource SPI implementation that the module provides. #### Breaking changes: - The SPI interfaces have moved to a package (not a module) separate from the API packages, and now live in `io.opentelemetry.spi.*` package namespace. -- Builder classes have been moved to the top level, rather than being inner classes. +- Builder classes have been moved to the top level, rather than being inner classes. For example, rather than `io.opentelemetry.api.trace.Span.Builder`, the builder is now in its own top-level class: `io.opentelemetry.api.trace.SpanBuilder`. Methods to create the builders remain in the same place as they were before. - SpanBuilder.setStartTimestamp, Span.end, and Span.addEvent methods which accept a timestamp now accept a timestamp with a TimeUnit instead of requiring a nanos timestamp. @@ -916,7 +916,7 @@ available. #### Breaking Changes: -- The builder class for the `OpenTelemetrySdk` now strictly requires its components to be SDK implementations. +- The builder class for the `OpenTelemetrySdk` now strictly requires its components to be SDK implementations. You can only build an `OpenTelemetrySdk` with `TracerSdkProvider` and `MeterSdkProvider` instances. #### Enhancements: @@ -934,16 +934,16 @@ evolve over the coming months before the metrics implementation is complete. See #### Breaking Changes: -- The `@WithSpan` annotation has been moved to the `io.opentelemetry.extension.annotations` package in the `opentelemetry-extension-annotations` module +- The `@WithSpan` annotation has been moved to the `io.opentelemetry.extension.annotations` package in the `opentelemetry-extension-annotations` module #### Bugfixes: - The memory pool metrics provided by the MemoryPools class in the `opentelemetry-extension-runtime-metrics` module have been fixed to properly report the committed memory values. - + #### Enhancements: -- A new module has been added to assist with propagating the OTel context in kotlin co-routines. +- A new module has been added to assist with propagating the OTel context in kotlin co-routines. See the `opentelemetry-extension-kotlin` module for details. --- @@ -986,7 +986,7 @@ See the `opentelemetry-extension-kotlin` module for details. #### Enhancements -- A new `MetricData` gauge metric type is now available. +- A new `MetricData` gauge metric type is now available. - A new `opentelemetry-sdk-testing` module with a JUnit 5 extension to assist with testing is now available. - The Prometheus metric exporter now consumes `gauge` metrics. - The Jaeger gRPC exporter now maps `Resource` entries to process tags. @@ -1012,7 +1012,7 @@ See the `opentelemetry-extension-kotlin` module for details. #### Enhancements -- A new JUnit5 extension was added for writing tests. For more information, see [OpenTelemetryExtension.java](sdk/testing/src/main/java/io/opentelemetry/sdk/testing/junit5/OpenTelemetryExtension.java). +- A new JUnit5 extension was added for writing tests. For more information, see [OpenTelemetryExtension.java](sdk/testing/src/main/java/io/opentelemetry/sdk/testing/junit5/OpenTelemetryExtension.java). - A Jaeger `SpanExporter` which exports via the `thrift-over-http protocol` is now available. - A Jaeger Propagator is now available. @@ -1020,14 +1020,14 @@ See the `opentelemetry-extension-kotlin` module for details. - The in-memory exporter(s) have been moved to the `opentelemetry-sdk-testing` artifact. - The OpenTracing shim factory class has been renamed from `TraceShim` to `OpenTracingShim`. The factory methods have changed because `BaggageManager` was removed and non-global `OpenTelemetry` instances are now available. -- The 's' was removed from the word "exporters" for every exporter artifact. For example, `opentelemetry-exporters-logging` was renamed to `opentelemetry-exporter-logging`. +- The 's' was removed from the word "exporters" for every exporter artifact. For example, `opentelemetry-exporters-logging` was renamed to `opentelemetry-exporter-logging`. - The 's' was removed from the word "extensions" for the package for every SDK extension. For example, `io.opentelemetry.sdk.extensions.otproto.TraceProtoUtils` was renamed to `io.opentelemetry.sdk.extension.otproto.TraceProtoUtils`. ### Thanks Many thanks to everyone who made this release possible! -@anuraaga @bogdandrutu @Oberon00 @thisthat @HaloFour @jkwatson @kenfinnigan @MariusVolkhart @malafeev @trask @tylerbenson @XiXiaPdx @dengliming @hengyunabc @jarebudev @brianashby-sfx +@anuraaga @bogdandrutu @Oberon00 @thisthat @HaloFour @jkwatson @kenfinnigan @MariusVolkhart @malafeev @trask @tylerbenson @XiXiaPdx @dengliming @hengyunabc @jarebudev @brianashby-sfx --- ## 0.9.1 - 2020-10-07 @@ -1065,7 +1065,7 @@ Many thanks to everyone who made this release possible! - BREAKING CHANGE: Metric Descriptor attributes have been flattened into the MetricData for export. - BREAKING CHANGE: The OpenTelemetrySdk class now returns a TraceSdkManagement interface, rather than the concrete TracerSdkProvider. - BUGFIX: Zipkin span durations are now rounded up to 1 microsecond, if less than 1. - - BUGFIX: The insecure option for OTLP export now does the correct thing. + - BUGFIX: The insecure option for OTLP export now does the correct thing. - Added a configuration option for disabling SPI-provided ResourceProviders - New incubator module with helper classes for working with SpanData - AWS resources now include the `cloud.provider` attribute. @@ -1076,11 +1076,11 @@ Many thanks to everyone who made this release possible! - New incubator module with some utilities for mutating SpanData instances. - The AWS Resource extension will now pull in EKS Resource attributes. - New pre-release extension for handling logging natively. - -### Thanks + +### Thanks Many thanks to all who made this release possible: - -@bogdandrutu @Oberon00 @jkwatson @thisthat @anuraaga @jarebudev @malafeev @quijote @JasonXZLiu @zoercai @eunice98k @dengliming @breedx-nr @iNikem @wangzlei @imavroukakis + +@bogdandrutu @Oberon00 @jkwatson @thisthat @anuraaga @jarebudev @malafeev @quijote @JasonXZLiu @zoercai @eunice98k @dengliming @breedx-nr @iNikem @wangzlei @imavroukakis --- ## 0.8.0 - 2020-09-01 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae62654528..f7b33fd6d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,12 +36,12 @@ you must run a local docker daemon. check formatting: `./gradlew build` - + 4. If you are a Windows user, use the alternate command mentioned below to run tests and check formatting: `gradlew.bat` - + ## Checks Before submitting a PR, you should make sure the style checks and unit tests pass. You can run these @@ -60,7 +60,7 @@ particular PR, but merging to the base branch is authorized to restricted member ## Style guideline -We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). +We follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Our build will fail if source code is not formatted according to that style. To fix any style failures the above [checks](#checks) show, automatically apply the formatting with: @@ -68,7 +68,7 @@ style failures the above [checks](#checks) show, automatically apply the formatt $ ./gradlew spotlessApply ``` -To verify code style manually run the following command, +To verify code style manually run the following command, which uses [google-java-format](https://github.com/google/google-java-format) library: `./gradlew spotlessCheck` @@ -99,12 +99,12 @@ of all `toString()` methods should be considered to be unstable unless explicitl If you notice any practice being applied in the project consistently that isn't listed here, please consider a pull request to add it. ### Pre-commit hook -To completely delegate code style formatting to the machine, +To completely delegate code style formatting to the machine, you can add [git pre-commit hook](https://git-scm.com/docs/githooks). We provide an example script in `buildscripts/pre-commit` file. Just copy or symlink it into `.git/hooks` folder. -### Editorconfig +### Editorconfig As additional convenience for IntelliJ Idea users, we provide `.editorconfig` file. Idea will automatically use it to adjust its code formatting settings. It does not support all required rules, so you still have to run `spotlessApply` from time to time. @@ -135,8 +135,8 @@ It does not support all required rules, so you still have to run `spotlessApply` possible, for any new value classes. Remember to add package-private constructors to all AutoValue classes to prevent classes in other packages from extending them. - - + + ### Unit Tests * Unit tests target Java 8, so language features such as lambda and streams can be used in tests. diff --git a/QUICKSTART.md b/QUICKSTART.md index 46358aac9e..e277cc0d31 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -4,4 +4,4 @@ Our quickstart guide has been migrated to the [OpenTelemetry documentation websi The source for the documentation website can be found in our [website_docs](website_docs) folder in this repository. If you have updates to the documentation, please open a pull request that updates the documents -in that location. Thanks! \ No newline at end of file +in that location. Thanks! diff --git a/README.md b/README.md index 04e48082cb..0d83646a96 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ If you are looking for an all-in-one, easy-to-install auto-instrumentation javaagent, please visit our sibling project, [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). -If you are looking for examples on how to use the OpenTelemetry APIs to write your own manual instrumentation, or -how to set up the OpenTelemetry Java SDK, please visit our [quickstart guide](QUICKSTART.md). We also have +If you are looking for examples on how to use the OpenTelemetry APIs to write your own manual instrumentation, or +how to set up the OpenTelemetry Java SDK, please visit our [quickstart guide](QUICKSTART.md). We also have fully-functioning example projects in our [examples sub-module](examples), which can be a good way to get your feet wet in a local environment. If you are looking to get involved with the project, please read our [contributing guide](CONTRIBUTING.md). We welcome -contributions! +contributions! If you are looking for a general overview of the OpenTelemetry project, please visit the [official website](https://opentelemetry.io). @@ -23,9 +23,9 @@ If you are looking for a general overview of the OpenTelemetry project, please v We hold regular meetings. See details at [community page](https://github.com/open-telemetry/community#java-sdk). We use [GitHub Discussions](https://github.com/open-telemetry/opentelemetry-java/discussions) -for support or general questions. Feel free to drop us a line. +for support or general questions. Feel free to drop us a line. -We are also present in the `#otel-java` channel in the [CNCF slack](https://slack.cncf.io/). +We are also present in the `#otel-java` channel in the [CNCF slack](https://slack.cncf.io/). Please join us for more informal discussions. ## Overview @@ -59,7 +59,7 @@ Both API and SDK extensions consist of various additional components which are e to keep them from growing too large. We still aim to provide the same level of quality and guarantee for them as for the core components. -Please don't hesitate to use them if you find them useful. +Please don't hesitate to use them if you find them useful. ## Project setup and contribute @@ -146,7 +146,7 @@ We strongly recommend using our published BOM to keep all dependency versions in ```groovy repositories { - maven { url 'https://oss.sonatype.org/content/repositories/snapshots' } + maven { url 'https://oss.sonatype.org/content/repositories/snapshots' } } dependencies { @@ -161,7 +161,7 @@ of the APIs. ## Releases -See the [VERSIONING.md](VERSIONING.md) document for our policies for releases and compatibility +See the [VERSIONING.md](VERSIONING.md) document for our policies for releases and compatibility guarantees. Check out information about the [latest release](https://github.com/open-telemetry/opentelemetry-java/releases). diff --git a/RELEASING.md b/RELEASING.md index 79479ecf06..b722a3d327 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -11,11 +11,11 @@ Open the release build workflow in your browser [here](https://github.com/open-t You will see a button that says "Run workflow". Press the button, enter the version number you want to release in the input field that pops up, and then press "Run workflow". -This triggers the release process, which builds the artifacts. It will not automatically update the +This triggers the release process, which builds the artifacts. It will not automatically update the documentation, because the Github Actions cannot push changes to the main branch. ## Announcement - + Once the GitHub workflow completes, go to Github [release page](https://github.com/open-telemetry/opentelemetry-java/releases), press `Draft a new release` to write release notes about the new release. If there is already a draft @@ -48,13 +48,13 @@ Next, update the Create a PR to mark the new release in README.md and CHANGELOG.md on the main branch. Finally, update the files `website_docs` directory to point at the newly released version. Once that has -been merged to the main branch, use the "Update OpenTelemetry Website" github action to create a PR +been merged to the main branch, use the "Update OpenTelemetry Website" github action to create a PR in the website repository with the changes. ## Patch Release All patch releases should include only bug-fixes, and must avoid -adding/modifying the public APIs. +adding/modifying the public APIs. Open the patch release build workflow in your browser [here](https://github.com/open-telemetry/opentelemetry-java/actions/workflows/patch-release-build.yml). diff --git a/VERSIONING.md b/VERSIONING.md index 47608b6ab5..3346bad0d3 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -7,17 +7,17 @@ that all artifacts have a version of the format `MAJOR.MINOR.PATCH` or `MAJOR.MI For any artifact with a stable release, that is its version does not end in `-alpha`, no backwards-incompatible changes will be made unless incrementing the `MAJOR` version number. In practice, this means that backwards-incompatible changes will be avoided as long as possible. Most releases are made by -incrementing the `MINOR` version. Patch releases with urgent cherry-picked bugfixes will be made by +incrementing the `MINOR` version. Patch releases with urgent cherry-picked bugfixes will be made by incrementing the `PATCH` version. A backwards-incompatible change affects the public API of a module. The public API is any public class or method that is not in a package which includes the word `internal`. Examples of incompatible changes are: -- API changes that could require code using the artifact to be changed, e.g., removing a method, +- API changes that could require code using the artifact to be changed, e.g., removing a method, reordering parameters, adding a method to an interface or abstract class without adding a default implementation. - + - ABI changes that could require code using the artifact to be recompiled, but not changed, e.g., changing the return type of a method from `void` to non-`void`, changing a `class` to an `interface`. The [JLS](https://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html) has more information on @@ -41,7 +41,7 @@ new artifact which requires adding the new artifact to dependency declarations. As a user, if you always depend on the latest version of the BOM for a given `MAJOR` version, and you do not use classes in the `internal` package (which you MUST NOT do), you can be assured that -your app will always function and have access to the latest features of OpenTelemetry without needing +your app will always function and have access to the latest features of OpenTelemetry without needing any changes to code. ## API vs SDK @@ -65,7 +65,7 @@ for at least three more years. This includes When incrementing the `MAJOR` version of the SDK, previously released `MAJOR` versions will be supported for at least one year. -## Stable vs alpha +## Stable vs alpha Not all of our artifacts are published as stable artifacts - any non-stable artifact has the suffix `-alpha` on its version. NONE of the guarantees described above apply to alpha artifacts. They may diff --git a/api/all/README.md b/api/all/README.md index c1d88ac022..beb0cd791a 100644 --- a/api/all/README.md +++ b/api/all/README.md @@ -4,7 +4,7 @@ * The code in this module is the implementation of stable OpenTelemetry signals. * Semantic Conventions for OpenTelemetry are in the `opentelemetry-semconv` module. -* The default implementation of the interfaces in this module is in the OpenTelemetry SDK module. +* The default implementation of the interfaces in this module is in the OpenTelemetry SDK module. * The interfaces in this directory can be implemented to create alternative implementations of the OpenTelemetry library. diff --git a/api/metrics/README.md b/api/metrics/README.md index bc5c618277..40728e8bb6 100644 --- a/api/metrics/README.md +++ b/api/metrics/README.md @@ -3,10 +3,10 @@ [![Javadocs][javadoc-image]][javadoc-url] * The code in this module is the implementation of the [experimental OpenTelemetry metrics signal][metrics-spec]. -* The default implementation of the interfaces in this module is in the OpenTelemetry metrics SDK module. +* The default implementation of the interfaces in this module is in the OpenTelemetry metrics SDK module. * The interfaces in this directory can be implemented to create alternative implementations of the OpenTelemetry library. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-api-metrics.svg [javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api-metrics -[metrics-spec]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md \ No newline at end of file +[metrics-spec]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md diff --git a/build.gradle.kts b/build.gradle.kts index fe518eafca..70f4066e6a 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -2,10 +2,11 @@ import nebula.plugin.release.git.opinion.Strategies import java.time.Duration plugins { - id("com.diffplug.spotless") id("com.github.ben-manes.versions") id("io.github.gradle-nexus.publish-plugin") id("nebula.release") + + id("otel.spotless-conventions") } if (!JavaVersion.current().isJava11Compatible()) { @@ -58,16 +59,6 @@ nexusPublishing { } } -allprojects { - apply(plugin = "com.diffplug.spotless") - - spotless { - kotlinGradle { - ktlint("0.42.1").userData(mapOf("indent_size" to "2", "continuation_indent_size" to "2")) - } - } -} - subprojects { group = "io.opentelemetry" } diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index 1834ad6441..cfaf597862 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -9,7 +9,7 @@ repositories { } dependencies { - implementation("com.diffplug.spotless:spotless-plugin-gradle:5.13.0") + implementation("com.diffplug.spotless:spotless-plugin-gradle:5.14.3") // Needed for japicmp but not automatically brought in for some reason. implementation("com.google.guava:guava:30.1-jre") implementation("com.squareup:javapoet:1.13.0") diff --git a/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts b/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts index c6b78a3996..270f7b5a69 100644 --- a/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts @@ -8,10 +8,9 @@ plugins { eclipse idea - id("com.diffplug.spotless") - id("otel.errorprone-conventions") id("otel.jacoco-conventions") + id("otel.spotless-conventions") } val otelJava = extensions.create("otelJava") @@ -166,14 +165,6 @@ configurations.configureEach { } } -spotless { - java { - googleJavaFormat("1.9") - licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|class|// Includes work from:)") - targetExclude("build/**") - } -} - val dependencyManagement by configurations.creating { isCanBeConsumed = false isCanBeResolved = false diff --git a/buildSrc/src/main/kotlin/otel.spotless-conventions.gradle.kts b/buildSrc/src/main/kotlin/otel.spotless-conventions.gradle.kts new file mode 100644 index 0000000000..2133fc4990 --- /dev/null +++ b/buildSrc/src/main/kotlin/otel.spotless-conventions.gradle.kts @@ -0,0 +1,47 @@ +plugins { + id("com.diffplug.spotless") +} + +spotless { + java { + googleJavaFormat() + licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|public|// Includes work from:)") + target("src/**/*.java") + } + plugins.withId("groovy") { + groovy { + licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|class)") + } + } + plugins.withId("scala") { + scala { + scalafmt() + licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|public)") + target("src/**/*.scala") + } + } + plugins.withId("org.jetbrains.kotlin.jvm") { + kotlin { + ktlint().userData(mapOf("indent_size" to "2", "continuation_indent_size" to "2", "disabled_rules" to "no-wildcard-imports")) + licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|class|// Includes work from:)") + } + } + kotlinGradle { + ktlint().userData(mapOf("indent_size" to "2", "continuation_indent_size" to "2", "disabled_rules" to "no-wildcard-imports")) + } + format("misc") { + // not using "**/..." to help keep spotless fast + target( + ".gitattributes", + ".gitconfig", + ".editorconfig", + "*.md", + "src/**/*.md", + "docs/**/*.md", + "*.sh", + "src/**/*.properties") + indentWithSpaces() + trimTrailingWhitespace() + endWithNewline() + } +} diff --git a/docs/jmh.md b/docs/jmh.md index fed02923d3..698e017441 100644 --- a/docs/jmh.md +++ b/docs/jmh.md @@ -3,19 +3,19 @@ [jmh] (Java Benchmark Harness) is a tool for running benchmarks and reporting results. -opentelemetry-java has a lot of micro benchmarks. They live inside +opentelemetry-java has a lot of micro benchmarks. They live inside `jmh` directories in the appropriate module. The benchmarks are run with a gradle plugin. -To run an entire suite for a module, you can run the jmh gradle task. -As an example, here's how you can run the benchmarks for all of +To run an entire suite for a module, you can run the jmh gradle task. +As an example, here's how you can run the benchmarks for all of the sdk trace module. ``` `./gradlew :sdk:trace:jmh` ``` -If you just want to run a single benchmark and not the entire suite: +If you just want to run a single benchmark and not the entire suite: -`./gradlew -PjmhIncludeSingleClass=BatchSpanProcessorBenchmark :sdk:trace:jmh` \ No newline at end of file +`./gradlew -PjmhIncludeSingleClass=BatchSpanProcessorBenchmark :sdk:trace:jmh` diff --git a/docs/rationale.md b/docs/rationale.md index f0fa1d8217..641cf6515c 100644 --- a/docs/rationale.md +++ b/docs/rationale.md @@ -34,17 +34,17 @@ Because this is a common usage for spans, we do not support try-with-resources. ### Goals -- API Stability: - - Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, code instrumented with that API module will -function, *with no recompilation required*, with any API+SDK that has the same major version, and equal or greater minor or patch version. - - For example, libraries that are instrumented with `opentelemetry-api-trace:1.0.1` will function, at runtime with -SDK library `opentelemetry-sdk-trace:1.11.33` plus `opentelemetry-api-trace:1.11.33` (or whatever specific versions are specified by - the bom version `1.11.33`, if the individual versions have diverged). - - We call this requirement the "ABI" compatibility requirement for "Application Binary Interface" compatibility. +- API Stability: + - Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, code instrumented with that API module will +function, *with no recompilation required*, with any API+SDK that has the same major version, and equal or greater minor or patch version. + - For example, libraries that are instrumented with `opentelemetry-api-trace:1.0.1` will function, at runtime with +SDK library `opentelemetry-sdk-trace:1.11.33` plus `opentelemetry-api-trace:1.11.33` (or whatever specific versions are specified by + the bom version `1.11.33`, if the individual versions have diverged). + - We call this requirement the "ABI" compatibility requirement for "Application Binary Interface" compatibility. - SDK Stability: - Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. - Precisely what this includes has yet to be delineated. -- Internal implementation details of both the API and SDK are allowed to be changed, +- Internal implementation details of both the API and SDK are allowed to be changed, as long as the public APIs are not changed in an ABI-incompatible manner. ### Methods @@ -62,10 +62,10 @@ SDK library `opentelemetry-sdk-trace:1.11.33` plus `opentelemetry-api-trace:1.11 - API modules for immature signals will not be transitive dependencies of the `opentelemetry-api` module. - API modules will be versioned with an "-alpha" suffix to make it abundantly clear that depending on them is at your own risk. - API modules for immature signals will be co-versioned along with mature API modules, with the added suffix. - - The java packages for immature APIs will be used as if they were mature signals. This will enable users to easily transition from immature to - mature usage, without having to change imports. + - The java packages for immature APIs will be used as if they were mature signals. This will enable users to easily transition from immature to + mature usage, without having to change imports. - SDK modules for immature signals will also be versioned with an "-alpha" suffix, in parallel to their API modules. - + ### Examples Purely for illustration purposes, not intended to represent actual releases: @@ -89,7 +89,7 @@ Purely for illustration purposes, not intended to represent actual releases: - `io.opentelemetry:opentelemetry-sdk-trace:1.15.0` - `io.opentelemetry:opentelemetry-sdk-common:1.15.0` - Shared code for metrics/trace implementations (clocks, etc) - - `io.opentelemetry:opentelemetry-sdk-metrics:1.15.0` + - `io.opentelemetry:opentelemetry-sdk-metrics:1.15.0` - Note: packages here have not changed from the experimental jar...just a jar rename happened. - `io.opentelemetry:opentelemetry-sdk-all:1.15.0` - The SDK side of io.opentelemetry:opentelemetry-api:1.15.0 diff --git a/docs/sdk-configuration.md b/docs/sdk-configuration.md index e7cd1abd70..f1f4429411 100644 --- a/docs/sdk-configuration.md +++ b/docs/sdk-configuration.md @@ -1,5 +1,5 @@ -> This is a design document and is not necessarily updated with evolving APIs. For up-to-date -> examples of SDK configuration see the +> This is a design document and is not necessarily updated with evolving APIs. For up-to-date +> examples of SDK configuration see the > [documentation](https://opentelemetry.io/docs/java/manual_instrumentation/). # Design for configuring the SDK @@ -11,7 +11,7 @@ continuation of discussion started with https://github.com/open-telemetry/opente There are a few different target audiences that are related to our configuration story. -- Application developers, aka end-users. Often have no knowledge of tracing but want to add +- Application developers, aka end-users. Often have no knowledge of tracing but want to add OpenTelemetry to their app and see traces show up in a console. Application developers will increase in number forever, while the below are more constant. @@ -53,8 +53,8 @@ custom SDKs can fall on their authors, we optimize for our standard usage, the f reference to "the SDK" in this document refers to the full SDK with all signals. - Make sure everything is auto-configurable. This is out of the scope of the SDK, and instead is -left to auto-configuration layers, which are also described below but not as part of the core SDK. -The SDK provides an autoconfiguration extension as an option which is not internal to the main SDK +left to auto-configuration layers, which are also described below but not as part of the core SDK. +The SDK provides an autoconfiguration extension as an option which is not internal to the main SDK components. ## Configuring an instance of the SDK @@ -214,7 +214,7 @@ setting a property once - `Resource` and `Clock` are shared among signals but co An alternative is to flatten all settings onto `OpenTelemetrySdkBuilder` - this has a downside that it makes it very natural to create new tracer / meter providers for each configuration of the SDK, which could result in a lot of duplication of resources like threads, workers, TCP connections. So -instead, this can make it clearer that those signals themselves are full-featured, and +instead, this can make it clearer that those signals themselves are full-featured, and `OpenTelemetry` is just a bag of signals. Keep in mind, reconfiguring `Clock` is expected to be an extremely uncommon operation. @@ -245,7 +245,7 @@ public class OpenTelemetryModule { public Resource resource() { return Resource.getDefault().merge(CoolResource.getDefault()); } - + @Bean public Clock otelClock() { return AtomicClock.create(); @@ -281,7 +281,7 @@ public class OpenTelemetryModule { .setIdGenerator(TimestampedIdGenerator.create()) .build(); } - + @Bean public MeterSdkProvider meterProvider(Resource resource, Clock clock) { return SdkMeterProvider.builder() @@ -326,13 +326,13 @@ public class OpenTelemetryModule { .setTracerProvider(tracerProvider) .build(); } - + @Bean public AuthServiceStub authService(@ForJaeger OpenTelemetry openTelemetry, AuthConfig config) { return AuthServiceGrpc.newBlockingStub(ManagedChannelBuilder.forEndpoint(config.getEndpoint())) .withInterceptor(TracingClientInterceptor.create(openTelemetry)); } - + @Bean public ServletFilter servletFilter(OpenTelemetry openTelemetry) { return TracingServletFilter.create(openTelemetry); @@ -344,12 +344,12 @@ public class OpenTelemetryModule { public class MyAuthInterceptor { private final AuthServiceStub authService; - + @Inject public MyAuthInterceptor(AuthServiceStub authService) { this.authService = authService; } - + public void doAuth() { if (!authService.getToken("credential").isAuthenticated()) { throw new HackerException(); @@ -363,13 +363,13 @@ public class MyService { private final Tracer tracer; private final Meter meter; - + @Inject public MyService(TracerProvider tracerProvider, MeterProvider meterProvider) { tracer = tracerProvider.get("my-service"); meter = meterProvider.get("my-service"); } - + public void doLogic() { Span span = tracer.spanBuilder("logic").startSpan(); try (Scope ignored = span.makeCurrent()) { @@ -384,7 +384,7 @@ public class MyService { ## The global instance of the SDK A built instance is convenient to use in most Java apps because of dependency injection. Because it -has a easy-to-reason initialization ordering, being tied into the dependency ordering (even if dependency +has a easy-to-reason initialization ordering, being tied into the dependency ordering (even if dependency injection happened to be done manually through constructor invocation), we encourage application developers to only use it. @@ -394,7 +394,7 @@ built instance of a signal provider. For this case, we must store an SDK instanc variable. It is expected that frameworks or end-users will set the SDK as the global to support instrumentation that requires this. -Before an SDK has been set, access to the global `OpenTelemetry` will return a no-op +Before an SDK has been set, access to the global `OpenTelemetry` will return a no-op `DefaultOpenTelemetry`. This is because it is possible library instrumentation is using the global, and it may even use it during the processing of a request (rather than only at initialization time). For this reason, we cannot throw an exception. Instead, if the SDK is detected on the classpath, we @@ -428,14 +428,14 @@ interface OpenTelemetryComponent { interface SpanExporter extends OpenTelemetryComponent { } public class BatchExporter implements SpanExporter { - + private volatile Tracer tracer; - + @Override public void setOpenTelemetry(OpenTelemetry openTelemetry) { tracer = openTelemetry.getTracerProvider().get("spanexporter"); } - + @Override public void export() { Tracer tracer = this.tracer; @@ -449,12 +449,12 @@ public class OpenTelemetrySdkBuilder { tracerProvider.addSpanExporter(exporter); components.add(exporter); } - + public OpenTelemetrySdkBuilder setSampler(Sampler sampler) { tracerProvider.setSampler(sampler); components.add(sampler); } - + public OpenTelemetry build() { OpenTelemetrySdk sdk = new OpenTelemetrySdk(tracerProvider.build(), meterProvider.build()); for (OpenTelemetryComponent component : components) { @@ -470,7 +470,7 @@ natively support lazy injection. ```java @Component public class MonitoringModule { - + @Bean @ForSpanExporter public Tracer tracer(TracerProvider tracerProvider) { @@ -482,12 +482,12 @@ public class MonitoringModule { public class MyExporter implements SpanExporter { private Lazy tracer; - + @Inject public MyExporter(@ForSpanExporter Lazy tracer) { this.tracer = tracer; } - + @Override public void export() { tracer.get().spanBuilder("export").startSpan(); @@ -503,9 +503,9 @@ hindrance), can reduce performance (require volatile read on most operations), a safety issues if not well implemented. In particular, compared to the current state as of writing, - `TracerSdkManagement.addSpanProcessor` is not needed. We needed a mutable SDK to allow span -processors to use global APIs for telemetry, but because we instead push the complexity of handling -[telemetry within SDK components](#Telemetry within SDK components) to those components, where the -maintainers will have more domain knowledge. It allows this mutator method to be removed from the +processors to use global APIs for telemetry, but because we instead push the complexity of handling +[telemetry within SDK components](#Telemetry within SDK components) to those components, where the +maintainers will have more domain knowledge. It allows this mutator method to be removed from the end-user API. - `TracerSdkManagement.updateTraceConfig` - instead of allowing replacing of the config at the top level, we should consider making @@ -522,7 +522,7 @@ Some highly buggy code that could be enabled by mutability. ```java class SleuthUsingService { - + @Inject private OpenTelemetry openTelemetry; @@ -546,7 +546,7 @@ tracing interceptor, when configuring observability. The above presents programmatic configuration for the SDK and proposes that the core SDK has no other mechanism for configuration. There is no SPI nor processing of environment variables or -system properties. There are many mechanisms for configuration, for example Spring Boot. +system properties. There are many mechanisms for configuration, for example Spring Boot. Integration with these systems becomes easier to reason about if we consider auto-configuration at a layer above the core SDK. @@ -582,7 +582,7 @@ presence of the wrapper and invoke it automatically. ### Spring Sleuth -[Spring Sleuth](https://spring.io/projects/spring-cloud-sleuth) (or any similar observability-aware server framework such as +[Spring Sleuth](https://spring.io/projects/spring-cloud-sleuth) (or any similar observability-aware server framework such as [curio-server-framework](https://github.com/curioswitch/curiostack/blob/master/common/server/framework/src/main/java/org/curioswitch/common/server/framework/monitoring/MonitoringModule.java) or internal frameworks developed by devops teams at companies) is also a mechanism for automatically configuring the SDK. In general, we would expect Sleuth users to not be using the java agent. @@ -612,7 +612,7 @@ public OpenTelemetry openTelemetry() { .setMeterProvider(MicrometerProvider.builder().build()) .build(); } -``` +``` As this should be a fairly minor use case, and commonly handled by framework developers, this seems reasonable. We can also hope that where it is important, it is the author of partial SDKs that diff --git a/docs/zpages/TRACEZ_DESIGN.md b/docs/zpages/TRACEZ_DESIGN.md index 70687ed20f..9db9465466 100644 --- a/docs/zpages/TRACEZ_DESIGN.md +++ b/docs/zpages/TRACEZ_DESIGN.md @@ -25,7 +25,7 @@ details. For example, here are the details of the `ChildSpan` latency sample (ro ### /traceconfigz zPage -The /traceconfigz zPage displays information about the currently active tracing configuration and +The /traceconfigz zPage displays information about the currently active tracing configuration and provides an interface for users to modify relevant parameters: ![traceconfigz](img/traceconfigz.png) diff --git a/exporters/jaeger-thrift/README.md b/exporters/jaeger-thrift/README.md index 767e651ceb..cb770718b6 100644 --- a/exporters/jaeger-thrift/README.md +++ b/exporters/jaeger-thrift/README.md @@ -2,7 +2,7 @@ [![Javadocs][javadoc-image]][javadoc-url] -This is the OpenTelemetry exporter, sending span data to Jaeger via Thrift over HTTP. +This is the OpenTelemetry exporter, sending span data to Jaeger via Thrift over HTTP. ## Configuration diff --git a/exporters/jaeger/README.md b/exporters/jaeger/README.md index c3f0fd1f17..7c4df73ef9 100644 --- a/exporters/jaeger/README.md +++ b/exporters/jaeger/README.md @@ -2,7 +2,7 @@ [![Javadocs][javadoc-image]][javadoc-url] -This is the OpenTelemetry exporter, sending span data to Jaeger via gRPC. +This is the OpenTelemetry exporter, sending span data to Jaeger via gRPC. ## Configuration @@ -27,7 +27,7 @@ As with the OpenTelemetry SDK itself, this exporter is compatible with Java 8+ a ## Proto files -The proto files in this repository were copied over from the [Jaeger main repository][proto-origin]. +The proto files in this repository were copied over from the [Jaeger main repository][proto-origin]. At this moment, they have to be manually synchronized, but a [discussion exists][proto-discussion] on how to properly consume them in a more appropriate manner. [proto-origin]: https://github.com/jaegertracing/jaeger/tree/5b8c1f40f932897b9322bf3f110d830536ae4c71/model/proto diff --git a/exporters/logging-otlp/README.md b/exporters/logging-otlp/README.md index 3615e4d5ce..82018d4cdd 100644 --- a/exporters/logging-otlp/README.md +++ b/exporters/logging-otlp/README.md @@ -6,4 +6,4 @@ Exporters for writing data to logs using OTLP JSON format. They are appropriate metrics to logs in a way that is both human-readable and structured for machine parsing. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-logging-otlp.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-logging-otlp \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-logging-otlp diff --git a/exporters/logging/README.md b/exporters/logging/README.md index 1e6d3b7769..1609476a39 100644 --- a/exporters/logging/README.md +++ b/exporters/logging/README.md @@ -3,4 +3,4 @@ [![Javadocs][javadoc-image]][javadoc-url] [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-logging.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-logging \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-logging diff --git a/exporters/otlp-http/metrics/README.md b/exporters/otlp-http/metrics/README.md index 6919f4a47c..b15e95db52 100644 --- a/exporters/otlp-http/metrics/README.md +++ b/exporters/otlp-http/metrics/README.md @@ -5,4 +5,4 @@ This is the OpenTelemetry exporter, sending metric data to OpenTelemetry collector via HTTP without gRPC. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp-http-metrics.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-http-metrics \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-http-metrics diff --git a/exporters/otlp-http/trace/README.md b/exporters/otlp-http/trace/README.md index a633e9a79f..c7f09e2e5e 100644 --- a/exporters/otlp-http/trace/README.md +++ b/exporters/otlp-http/trace/README.md @@ -5,4 +5,4 @@ This is the OpenTelemetry exporter, sending span data to OpenTelemetry collector via HTTP without gRPC. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp-http-trace.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-http-trace \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-http-trace diff --git a/exporters/otlp/all/README.md b/exporters/otlp/all/README.md index 4b18a2270f..fdfb211013 100644 --- a/exporters/otlp/all/README.md +++ b/exporters/otlp/all/README.md @@ -3,4 +3,4 @@ [![Javadocs][javadoc-image]][javadoc-url] [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp diff --git a/exporters/otlp/common/README.md b/exporters/otlp/common/README.md index f3a29fe820..f080534388 100644 --- a/exporters/otlp/common/README.md +++ b/exporters/otlp/common/README.md @@ -5,4 +5,4 @@ This module contains common utility code used by other OpenTelemetry OTLP modules, including conversion between OpenTelemetry API or SDK objects and proto objects. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp-common.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-common \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-common diff --git a/exporters/otlp/common/src/main/proto/README.md b/exporters/otlp/common/src/main/proto/README.md index 3e4195a60a..f36259bdd2 100644 --- a/exporters/otlp/common/src/main/proto/README.md +++ b/exporters/otlp/common/src/main/proto/README.md @@ -1 +1 @@ -Non-empty folder required for wire proto compiler. \ No newline at end of file +Non-empty folder required for wire proto compiler. diff --git a/exporters/otlp/metrics/README.md b/exporters/otlp/metrics/README.md index 0698d10f1d..a3b75a9b26 100644 --- a/exporters/otlp/metrics/README.md +++ b/exporters/otlp/metrics/README.md @@ -5,4 +5,4 @@ This is the OpenTelemetry exporter, sending metrics data to OpenTelemetry collector via gRPC. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp-metrics.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-metrics \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-metrics diff --git a/exporters/otlp/trace/README.md b/exporters/otlp/trace/README.md index 269684965e..99b1605248 100644 --- a/exporters/otlp/trace/README.md +++ b/exporters/otlp/trace/README.md @@ -5,4 +5,4 @@ This is the OpenTelemetry exporter, sending span data to OpenTelemetry collector via gRPC. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-otlp-trace.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-trace \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-otlp-trace diff --git a/exporters/otlp/trace/src/main/proto/README.md b/exporters/otlp/trace/src/main/proto/README.md index 3e4195a60a..f36259bdd2 100644 --- a/exporters/otlp/trace/src/main/proto/README.md +++ b/exporters/otlp/trace/src/main/proto/README.md @@ -1 +1 @@ -Non-empty folder required for wire proto compiler. \ No newline at end of file +Non-empty folder required for wire proto compiler. diff --git a/exporters/prometheus/README.md b/exporters/prometheus/README.md index a3917a6561..af2e89660e 100644 --- a/exporters/prometheus/README.md +++ b/exporters/prometheus/README.md @@ -5,4 +5,4 @@ This is the OpenTelemetry's Prometheus exporter, allowing Prometheus to query metrics data. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-exporter-prometheus.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-prometheus \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-prometheus diff --git a/exporters/zipkin/README.md b/exporters/zipkin/README.md index 9ff2f21be7..b9912b6b6d 100644 --- a/exporters/zipkin/README.md +++ b/exporters/zipkin/README.md @@ -25,11 +25,11 @@ ZipkinSpanExporter exporter = .build(); ``` -Service name and Endpoint can be also configured via environment variables or system properties. +Service name and Endpoint can be also configured via environment variables or system properties. ```java // Using environment variables -ZipkinSpanExporter exporter = +ZipkinSpanExporter exporter = ZipkinSpanExporter.builder() .readEnvironmentVariables() .build() @@ -37,7 +37,7 @@ ZipkinSpanExporter exporter = ```java // Using system properties -ZipkinSpanExporter exporter = +ZipkinSpanExporter exporter = ZipkinSpanExporter.builder() .readSystemProperties() .build() diff --git a/extensions/kotlin/src/main/kotlin/io/opentelemetry/extension/kotlin/ContextExtensions.kt b/extensions/kotlin/src/main/kotlin/io/opentelemetry/extension/kotlin/ContextExtensions.kt index b5050ff541..78f5a43e3f 100644 --- a/extensions/kotlin/src/main/kotlin/io/opentelemetry/extension/kotlin/ContextExtensions.kt +++ b/extensions/kotlin/src/main/kotlin/io/opentelemetry/extension/kotlin/ContextExtensions.kt @@ -1,3 +1,8 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + package io.opentelemetry.extension.kotlin import io.opentelemetry.context.Context @@ -9,7 +14,7 @@ import kotlin.coroutines.CoroutineContext * and restores the previous [Context] on suspension. */ fun Context.asContextElement(): CoroutineContext { - return KotlinContextElement(this) + return KotlinContextElement(this) } /** @@ -17,16 +22,16 @@ fun Context.asContextElement(): CoroutineContext { * coroutine and restores the previous [Context] on suspension. */ fun ImplicitContextKeyed.asContextElement(): CoroutineContext { - return KotlinContextElement(Context.current().with(this)) + return KotlinContextElement(Context.current().with(this)) } /** * Returns the [Context] in this [CoroutineContext] if present, or the root otherwise. */ fun CoroutineContext.getOpenTelemetryContext(): Context { - val element = get(KotlinContextElement.KEY) - if (element is KotlinContextElement) { - return element.context - } - return Context.root() + val element = get(KotlinContextElement.KEY) + if (element is KotlinContextElement) { + return element.context + } + return Context.root() } diff --git a/extensions/kotlin/src/test/kotlin/io/opentelemetry/extension/kotlin/KotlinCoroutinesTest.kt b/extensions/kotlin/src/test/kotlin/io/opentelemetry/extension/kotlin/KotlinCoroutinesTest.kt index 8c21fcc000..c4cfa85d62 100644 --- a/extensions/kotlin/src/test/kotlin/io/opentelemetry/extension/kotlin/KotlinCoroutinesTest.kt +++ b/extensions/kotlin/src/test/kotlin/io/opentelemetry/extension/kotlin/KotlinCoroutinesTest.kt @@ -1,3 +1,8 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + package io.opentelemetry.extension.kotlin import io.opentelemetry.api.trace.Span @@ -11,86 +16,86 @@ import org.junit.jupiter.api.extension.RegisterExtension class KotlinCoroutinesTest { - companion object { - private val ANIMAL: ContextKey = ContextKey.named("animal") + companion object { + private val ANIMAL: ContextKey = ContextKey.named("animal") - @JvmField - @RegisterExtension - val otelTesting = OpenTelemetryExtension.create() - } + @JvmField + @RegisterExtension + val otelTesting = OpenTelemetryExtension.create() + } - @Test - fun runWithContext() { - val context1 = Context.root().with(ANIMAL, "cat") + @Test + fun runWithContext() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + assertThat(coroutineContext.getOpenTelemetryContext()).isSameAs(Context.current()) + + withContext(context1.with(ANIMAL, "dog").asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") + } + + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + + async(Dispatchers.IO) { + // Child coroutine inherits context automatically. + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + }.await() + + coroutineScope { + // Child coroutine inherits context automatically. + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + } + + CoroutineScope(Dispatchers.IO).async { + // Non-child coroutine does not inherit context automatically. assertThat(Context.current().get(ANIMAL)).isNull() - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - assertThat(coroutineContext.getOpenTelemetryContext()).isSameAs(Context.current()) - - withContext(context1.with(ANIMAL, "dog").asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - } - - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - - async(Dispatchers.IO) { - // Child coroutine inherits context automatically. - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - }.await() - - coroutineScope { - // Child coroutine inherits context automatically. - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - } - - CoroutineScope(Dispatchers.IO).async { - // Non-child coroutine does not inherit context automatically. - assertThat(Context.current().get(ANIMAL)).isNull() - }.await() - } + }.await() } + } - @Test - fun runWithSpan() { - val span = otelTesting.openTelemetry.getTracer("test").spanBuilder("test") - .startSpan() - assertThat(Span.current()).isEqualTo(Span.getInvalid()) - runBlocking(Dispatchers.Default + span.asContextElement()) { - assertThat(Span.current()).isEqualTo(span) - } + @Test + fun runWithSpan() { + val span = otelTesting.openTelemetry.getTracer("test").spanBuilder("test") + .startSpan() + assertThat(Span.current()).isEqualTo(Span.getInvalid()) + runBlocking(Dispatchers.Default + span.asContextElement()) { + assertThat(Span.current()).isEqualTo(span) } + } - @Test - fun getOpenTelemetryContextOutsideOfContext() { - runBlocking(Dispatchers.Default) { - assertThat(Context.root()).isSameAs(coroutineContext.getOpenTelemetryContext()) - } + @Test + fun getOpenTelemetryContextOutsideOfContext() { + runBlocking(Dispatchers.Default) { + assertThat(Context.root()).isSameAs(coroutineContext.getOpenTelemetryContext()) } + } - // Check whether concurrent coroutines leak context - @Test - fun stressTest() { - val context1 = Context.root().with(ANIMAL, "cat") - runBlocking(context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - for (i in 0 until 100) { - GlobalScope.launch { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - withContext(context1.with(ANIMAL, "dog").asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - delay(10) - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - } - } - GlobalScope.launch { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - withContext(context1.with(ANIMAL, "koala").asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("koala") - delay(10) - assertThat(Context.current().get(ANIMAL)).isEqualTo("koala") - } - } - } + // Check whether concurrent coroutines leak context + @Test + fun stressTest() { + val context1 = Context.root().with(ANIMAL, "cat") + runBlocking(context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + for (i in 0 until 100) { + GlobalScope.launch { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + withContext(context1.with(ANIMAL, "dog").asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") + delay(10) + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") + } } + GlobalScope.launch { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + withContext(context1.with(ANIMAL, "koala").asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("koala") + delay(10) + assertThat(Context.current().get(ANIMAL)).isEqualTo("koala") + } + } + } } + } } diff --git a/extensions/kotlin/src/testStrictContext/kotlin/io/opentelemetry/extension/kotlin/StrictContextWithCoroutinesTest.kt b/extensions/kotlin/src/testStrictContext/kotlin/io/opentelemetry/extension/kotlin/StrictContextWithCoroutinesTest.kt index df4ef630bb..9b1c3bf2f3 100644 --- a/extensions/kotlin/src/testStrictContext/kotlin/io/opentelemetry/extension/kotlin/StrictContextWithCoroutinesTest.kt +++ b/extensions/kotlin/src/testStrictContext/kotlin/io/opentelemetry/extension/kotlin/StrictContextWithCoroutinesTest.kt @@ -1,3 +1,8 @@ +/* + * Copyright The OpenTelemetry Authors + * SPDX-License-Identifier: Apache-2.0 + */ + package io.opentelemetry.extension.kotlin import io.opentelemetry.context.Context @@ -12,137 +17,136 @@ import org.junit.jupiter.api.Test class StrictContextWithCoroutinesTest { - companion object { - private val ANIMAL: ContextKey = ContextKey.named("animal") - } + companion object { + private val ANIMAL: ContextKey = ContextKey.named("animal") + } - @Test - fun noMakeCurrentSucceeds() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + @Test + fun noMakeCurrentSucceeds() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + } + } + + @Test + fun noMakeCurrentNestedContextSucceeds() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + withContext(Context.current().with(ANIMAL, "dog").asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") + } + } + } + + @Test + fun makeCurrentInNormalFunctionSucceeds() { + assertThat(Context.current().get(ANIMAL)).isNull() + nonSuspendingContextFunction("dog") + } + + @Test + fun makeCurrentInTopLevelCoroutineFails() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + assertThatThrownBy { + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + Context.current().with(ANIMAL, "dog").makeCurrent().use { + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") } - } + } + }.isInstanceOf(AssertionError::class.java) + } - @Test - fun noMakeCurrentNestedContextSucceeds() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - withContext(Context.current().with(ANIMAL, "dog").asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - } + @Test + fun makeCurrentInNestedCoroutineFails() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + assertThatThrownBy { + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + runBlocking(Dispatchers.Default) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + Context.current().with(ANIMAL, "dog").makeCurrent().use { + assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") + } } - } + } + }.isInstanceOf(AssertionError::class.java) + } - @Test - fun makeCurrentInNormalFunctionSucceeds() { - assertThat(Context.current().get(ANIMAL)).isNull() - nonSuspendingContextFunction("dog") - } + @Test + fun makeCurrentInSuspendingFunctionFails() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + assertThatThrownBy { + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + suspendingFunctionMakeCurrentWithAutoClose("dog") + } + }.isInstanceOf(AssertionError::class.java) + } - @Test - fun makeCurrentInTopLevelCoroutineFails() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - assertThatThrownBy { - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - Context.current().with(ANIMAL, "dog").makeCurrent().use { - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - } - } - }.isInstanceOf(AssertionError::class.java) - } + @Test + fun makeCurrentInSuspendingFunctionWithManualCloseFails() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + assertThatThrownBy { + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + suspendingFunctionMakeCurrentWithManualClose("dog") + } + }.isInstanceOf(AssertionError::class.java) + } - @Test - fun makeCurrentInNestedCoroutineFails() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - assertThatThrownBy { - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - runBlocking(Dispatchers.Default) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - Context.current().with(ANIMAL, "dog").makeCurrent().use { - assertThat(Context.current().get(ANIMAL)).isEqualTo("dog") - } - } - } - }.isInstanceOf(AssertionError::class.java) + @Test + fun noMakeCurrentInSuspendingFunctionSucceeds() { + val context1 = Context.root().with(ANIMAL, "cat") + assertThat(Context.current().get(ANIMAL)).isNull() + runBlocking(Dispatchers.Default + context1.asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") + suspendingFunctionContextElement("dog") } + } - @Test - fun makeCurrentInSuspendingFunctionFails() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - assertThatThrownBy { - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - suspendingFunctionMakeCurrentWithAutoClose("dog") - } - }.isInstanceOf(AssertionError::class.java) + // makeCurrent in non-suspending function is ok, the thread is guaranteed not to switch out from + // under you. + fun nonSuspendingContextFunction(animal: String) { + Context.current().with(ANIMAL, animal).makeCurrent().use { + assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) } + } + suspend fun suspendingFunctionMakeCurrentWithAutoClose(animal: String) { + Context.current().with(ANIMAL, animal).makeCurrent().use { + assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) + delay(10) + // The value of ANIMAL here is undefined - it may still be the original thread with + // the ThreadLocal set correctly, or a completely different one with a different value. + // So there's nothing we can assert here, and is precisely why we forbid makeCurrent in + // suspending functions. + } + } - @Test - fun makeCurrentInSuspendingFunctionWithManualCloseFails() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - assertThatThrownBy { - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - suspendingFunctionMakeCurrentWithManualClose("dog") - } - }.isInstanceOf(AssertionError::class.java) - } + suspend fun suspendingFunctionMakeCurrentWithManualClose(animal: String) { + val scope = Context.current().with(ANIMAL, animal).makeCurrent() + assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) + delay(10) + // The value of ANIMAL here is undefined - it may still be the original thread with + // the ThreadLocal set correctly, or a completely different one with a different value. + // So there's nothing we can assert here, and is precisely why we forbid makeCurrent in + // suspending functions. + scope.close() + } - @Test - fun noMakeCurrentInSuspendingFunctionSucceeds() { - val context1 = Context.root().with(ANIMAL, "cat") - assertThat(Context.current().get(ANIMAL)).isNull() - runBlocking(Dispatchers.Default + context1.asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo("cat") - suspendingFunctionContextElement("dog") - } + suspend fun suspendingFunctionContextElement(animal: String) { + withContext(Context.current().with(ANIMAL, animal).asContextElement()) { + assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) + delay(10) + assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) } - - // makeCurrent in non-suspending function is ok, the thread is guaranteed not to switch out from - // under you. - fun nonSuspendingContextFunction(animal: String) { - Context.current().with(ANIMAL, animal).makeCurrent().use { - assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) - } - } - suspend fun suspendingFunctionMakeCurrentWithAutoClose(animal: String) { - Context.current().with(ANIMAL, animal).makeCurrent().use { - assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) - delay(10) - // The value of ANIMAL here is undefined - it may still be the original thread with - // the ThreadLocal set correctly, or a completely different one with a different value. - // So there's nothing we can assert here, and is precisely why we forbid makeCurrent in - // suspending functions. - } - } - - suspend fun suspendingFunctionMakeCurrentWithManualClose(animal: String) { - val scope = Context.current().with(ANIMAL, animal).makeCurrent() - assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) - delay(10) - // The value of ANIMAL here is undefined - it may still be the original thread with - // the ThreadLocal set correctly, or a completely different one with a different value. - // So there's nothing we can assert here, and is precisely why we forbid makeCurrent in - // suspending functions. - scope.close() - } - - suspend fun suspendingFunctionContextElement(animal: String) { - withContext(Context.current().with(ANIMAL, animal).asContextElement()) { - assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) - delay(10) - assertThat(Context.current().get(ANIMAL)).isEqualTo(animal) - } - } - + } } diff --git a/extensions/trace-propagators/README.md b/extensions/trace-propagators/README.md index b1c6bc7bce..57b33cab7b 100644 --- a/extensions/trace-propagators/README.md +++ b/extensions/trace-propagators/README.md @@ -6,18 +6,18 @@ OpenTelemetry Extension Trace Propagators [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-extension-trace-propagators.svg [javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-extension-trace-propagators -This repository provides several +This repository provides several [trace propagators](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md), -used to propagate context across a distributed trace. +used to propagate context across a distributed trace. -OpenTelemetry Java provides first-party support for +OpenTelemetry Java provides first-party support for [B3 (OpenZipkin)](https://github.com/openzipkin/b3-propagation) and [Jaeger](https://github.com/jaegertracing/jaeger) propagators. Issues with those propagators should be filed against this repo. --- #### Running micro-benchmarks -From the root of the repo run `./gradlew clean :opentelemetry-extension-trace-propagators:jmh` -to run all the benchmarks -or run `./gradlew clean :opentelemetry-extension-trace-propagators:jmh -PjmhIncludeSingleClass=` +From the root of the repo run `./gradlew clean :opentelemetry-extension-trace-propagators:jmh` +to run all the benchmarks +or run `./gradlew clean :opentelemetry-extension-trace-propagators:jmh -PjmhIncludeSingleClass=` to run a specific benchmark class. diff --git a/integration-tests/README.md b/integration-tests/README.md index fab3dc99a0..0632073ccd 100644 --- a/integration-tests/README.md +++ b/integration-tests/README.md @@ -1,4 +1,4 @@ # OpenTelemetry Integration Tests -* Integration Test code lives here \ No newline at end of file +* Integration Test code lives here diff --git a/integration-tests/tracecontext/src/main/resources/simplelogger.properties b/integration-tests/tracecontext/src/main/resources/simplelogger.properties index 7c21e58a5d..a6233fa346 100644 --- a/integration-tests/tracecontext/src/main/resources/simplelogger.properties +++ b/integration-tests/tracecontext/src/main/resources/simplelogger.properties @@ -1,2 +1,2 @@ org.slf4j.simpleLogger.defaultLogLevel=info -org.slf4j.simpleLogger.log.org.eclipse.jetty=warn \ No newline at end of file +org.slf4j.simpleLogger.log.org.eclipse.jetty=warn diff --git a/integration-tests/tracecontext/tracecontext-integration-test.sh b/integration-tests/tracecontext/tracecontext-integration-test.sh index ef86e2d8d6..a462d40035 100755 --- a/integration-tests/tracecontext/tracecontext-integration-test.sh +++ b/integration-tests/tracecontext/tracecontext-integration-test.sh @@ -25,4 +25,4 @@ onshutdown() trap onshutdown EXIT export STRICT_LEVEL=1 cd ./target/trace-context/test -python3 test.py http://127.0.0.1:5000/verify-tracecontext \ No newline at end of file +python3 test.py http://127.0.0.1:5000/verify-tracecontext diff --git a/opentracing-shim/README.md b/opentracing-shim/README.md index c3d4c10eb0..5afab79367 100644 --- a/opentracing-shim/README.md +++ b/opentracing-shim/README.md @@ -7,8 +7,8 @@ It takes OpenTelemetry Tracer and exposes it as an implementation of an OpenTrac ## Usage -There are 2 ways to expose an OpenTracing tracer: -1. From the global OpenTelemetry configuration: +There are 2 ways to expose an OpenTracing tracer: +1. From the global OpenTelemetry configuration: ```java Tracer tracer = OpenTracingShim.createTracerShim(); ``` diff --git a/proto/README.md b/proto/README.md index 2d8c543425..67170fa073 100644 --- a/proto/README.md +++ b/proto/README.md @@ -3,4 +3,4 @@ [![Javadocs][javadoc-image]][javadoc-url] [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-proto.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-proto \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-proto diff --git a/sdk-extensions/async-processor/README.md b/sdk-extensions/async-processor/README.md index 53ada9a6ce..993bbf2132 100644 --- a/sdk-extensions/async-processor/README.md +++ b/sdk-extensions/async-processor/README.md @@ -7,4 +7,4 @@ An implementation of the trace `SpanProcessors` that uses async. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-sdk-extension-async-processor.svg -[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-async-processor \ No newline at end of file +[javadoc-url]: https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-extension-async-processor diff --git a/sdk-extensions/aws/README.md b/sdk-extensions/aws/README.md index 547c8884a8..459cd3419b 100644 --- a/sdk-extensions/aws/README.md +++ b/sdk-extensions/aws/README.md @@ -4,8 +4,8 @@ --- #### Running micro-benchmarks -From the root of the repo run `./gradlew clean :opentelemetry-sdk-extension-aws:jmh` to run all the benchmarks -or run `./gradlew clean :opentelemetry-sdk-extension-aws:jmh -PjmhIncludeSingleClass=` +From the root of the repo run `./gradlew clean :opentelemetry-sdk-extension-aws:jmh` to run all the benchmarks +or run `./gradlew clean :opentelemetry-sdk-extension-aws:jmh -PjmhIncludeSingleClass=` to run a specific benchmark class. [javadoc-image]: https://www.javadoc.io/badge/io.opentelemetry/opentelemetry-sdk-extension-aws.svg diff --git a/sdk-extensions/zpages/README.md b/sdk-extensions/zpages/README.md index 0f4a69c8b0..5153cf5ed7 100644 --- a/sdk-extensions/zpages/README.md +++ b/sdk-extensions/zpages/README.md @@ -56,7 +56,7 @@ details. For example, here are the details of the `ChildSpan` latency sample (ro #### View and update the tracing configuration on the `/traceconfigz` zPage -The /traceconfigz zPage displays information about the currently active tracing configuration and +The /traceconfigz zPage displays information about the currently active tracing configuration and provides an interface for users to modify relevant parameters. Here is what the web page looks like: ![traceconfigz](img/traceconfigz.png) diff --git a/sdk/all/README.md b/sdk/all/README.md index 15b5c94925..9ee9006a4b 100644 --- a/sdk/all/README.md +++ b/sdk/all/README.md @@ -8,7 +8,6 @@ OpenTelemetry SDK --- #### Running micro-benchmarks -From the root of the repo run `./gradlew clean :opentelemetry-sdk:jmh` to run all the benchmarks -or run `./gradlew clean :opentelemetry-sdk:jmh -PjmhIncludeSingleClass=` +From the root of the repo run `./gradlew clean :opentelemetry-sdk:jmh` to run all the benchmarks +or run `./gradlew clean :opentelemetry-sdk:jmh -PjmhIncludeSingleClass=` to run a specific benchmark class. - diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/export/README.md b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/export/README.md index 429be48d20..632611d9b7 100644 --- a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/export/README.md +++ b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/export/README.md @@ -21,7 +21,7 @@ import io.opentelemetry.sdk.metrics.export.MetricProducer; /** * Simple implementation of the MetricExporter that pushes data to the backend. */ -public final class PushMetricExporter implements MetricExporter { +public final class PushMetricExporter implements MetricExporter { @Override ResultCode export(Collection metrics) { // A "push based" library calls to export metrics @@ -44,12 +44,12 @@ public final class PushExporter { IntervalMetricReader.builder() .readEnvironment() // Read configuration from environment variables .readSystemProperties() // Read configuration from system properties - .setExportIntervalMillis(100_000) + .setExportIntervalMillis(100_000) .setMetricExporter(metricExporter) .setMetricProducers(Collections.singletonList(producers)) .build(); } - + // Can be accessed by any "push based" library to export metrics. public MetricExporter getMetricExporter() { return metricExporter; @@ -79,7 +79,7 @@ public final class PullMetricExporter implements MetricExporter, MetricProducer metricsBuffer.addAll(metrics); return ResultCode.SUCCESS; } - + synchronized Collection getAllMetrics() { List ret = metricsBuffer; metricsBuffer = new ArrayList<>();