Update the docs for the 0.9.1 release (#1777)

* Update the docs for the 0.9.1 release * correct a bad method name * Update CHANGELOG.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Christian Neumüller <christian+github@neumueller.me>
open-telemetry · Oct 12, 2020 · 0b6ae18 · 0b6ae18
1 parent 72e17bb
commit 0b6ae18
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 37 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,56 @@
 
 ## Unreleased
 
-- Extensions:
-    - BREAKING CHANGE: Made Propagators to expose only a singleton instance
+## 0.9.1 - 2020-10-07
+
+- API
+    - BREAKING CHANGE: SpanId, TraceId and TraceFlags are no longer used as instances, but only contain helper methods for managing conversion between Strings, bytes and other formats. SpanId and TraceId are now natively String-typed, and the TraceFlags is a single byte.
+    - BREAKING CHANGE: Propagators now only expose a singleton instance.
+    - BREAKING CHANGE: The LabelConsumer and AttributeConsumer are now first-class interfaces, and the underlying consumer interface has had the key made additionally generic. Please prefer using the specific interfaces, rather than the underlying `ReadableKeyValuePairs.KeyValueConsumer`.
+    - BREAKING CHANGE: Minimum JDK version has been updated to 8, with Android API level 24.
+    - BREAKING CHANGE: Metric Instrument names are now case-insensitive.
+    - BREAKING CHANGE: The type-safety on Attributes has been moved to a new AttributeKey, and the AttributeValue wrappers have been removed. This impacts all the semantic attribute definitions, and the various APIs that use Attributes.
+    - BREAKING CHANGE: The obsolete HTTP_STATUS_TEXT semantic attribute has been removed.
+    - BREAKING CHANGE: The type of the REDIS_DATABASE_INDEX semantic attribute has been changed to be numeric.
+    - BREAKING CHANGE: Constant Labels have been removed from metric Instrument definitions.
+    - BREAKING CHANGE: The number of available Span Status options has been greatly reduced (from 16 to 3).
+    - BREAKING CHANGE: Constant labels have been removed from metric Instrument definitions.
+    - BREAKING CHANGE: The only way to specify span parenting is via a parent Context
+    - BREAKING CHANGE: The default TextMapPropagator is now a no-op in the API
+    - BREAKING CHANGE: CorrelationContext has been renamed to Baggage
+    - BREAKING CHANGE: Null-valued span attribute behavior has been changed to being "unspecified".
+    - BREAKING CHANGE: Link and Event interfaces have been removed from the API
+    - BREAKING CHANGE: The Status object has been removed from the API, in favor of StatusCanonicalCode
+    - BUGFIX: the `noParent` option on a Span was being ignored if it was set after setting an explicit parent.
+    - BUGFIX: Attributes and Labels now preserve the latest added entry when an existing key has been used.
+    - BUGFIX: Updated some of the W3C traceparent validation logic to better match the spec.
+    - FaaS semantic attributes have been added
+    - Semantic attribute for "exception.escaped" added
+
+- SDK
+    - BREAKING CHANGE: The names of the Sampler.Decision enum values, returned by the Sampler interface, have changed.
+    - `OpenTelemetrySdk.forceFlush()` now returns a CompletableResultCode
+    - BREAKING CHANGE: The `ProbabilitySampler` has been renamed to `TraceIdRatioBased`
+    - BREAKING CHANGE: The environment variables/system properties for specifying exporter and span processor configuration have been updated to match the specification.
+    - BREAKING CHANGE: Exported zipkin attributes have been changed to match the specification.
+    - 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. 
+    - 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.
+
+- Extensions
+    - BREAKING CHANGE: Propagators now only expose a singleton instance.
+    - The auto-config extension has been moved to the instrumentation project.
+    - 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.
+
+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 
 
 ## 0.8.0 - 2020-09-01
 
@@ -100,4 +148,4 @@ TODO: fill this out
 ## 0.3.0 - 2020-03-27
 - Initial Java API and SDK for context, trace, metrics, resource.
 - Initial implementation of the Jaeger exporter.
-- Initial implementation of the OTLP exporters for trace and metrics.
+- Initial implementation of the OTLP exporters for trace and metrics.
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -55,8 +55,7 @@ try (Scope scope = tracer.withSpan(span)) {
 	// your use case
 	...
 } catch (Throwable t) {
-    Status status = Status.ERROR.withDescription("Change it to your error message");
-    span.setStatus(status);
+    span.setStatus(StatusCanonicalCode.ERROR, "Change it to your error message");
 } finally {
     span.end(); // closing the scope does not end the span, this has to be done manually
 }
@@ -88,19 +87,22 @@ The OpenTelemetry API offers also an automated way to propagate the `parentSpan`
 ```java
 void a() {
   Span parentSpan = tracer.spanBuilder("a").startSpan();
-  try(Scope scope = tracer.withSpan(parentSpan)){
+  try(Scope scope = tracer.withSpan(parentSpan)) {
     b();
   } finally {
     parentSpan.end();
   }
 }
 void b() {
   Span childSpan = tracer.spanBuilder("b")
-     // NOTE: setParent(parentSpan) is not required anymore, 
-     // `tracer.getCurrentSpan()` is automatically added as parent
+    // NOTE: setParent(parentSpan) is not required; 
+    // `tracer.getCurrentSpan()` is automatically added as parent
     .startSpan();
-  // do stuff
-  childSpan.end();
+  try(Scope scope = tracer.withSpan(childSpan)) {
+    // do stuff
+  } finally {
+    childSpan.end();
+  }
 }
 ``` 
 
@@ -124,7 +126,7 @@ span.setAttribute("http.url", url.toString());
 
 Some of these operations represent calls that use well-known protocols like HTTP or database calls. 
 For these, OpenTelemetry requires specific attributes to be set. The full attribute list is
-available in the [Semantic Conventions] in the cross-language specification.
+available in the [Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/README.md) in the cross-language specification.
 
 ### Create Spans with events
 
@@ -140,8 +142,8 @@ span.addEvent("End");
 
 ```java
 Attributes eventAttributes = Attributes.of(
-    "key", AttributeValue.stringAttributeValue("value"),
-    "result", AttributeValue.longAttributeValue(0L));
+    AttributeKey.stringKey("key"), "value",
+    AttributeKey.longKey("result"), 0L);
 
 span.addEvent("End Computation", eventAttributes);
 ```
@@ -152,11 +154,9 @@ represent batched operations where a Span was initiated by multiple initiating S
 representing a single incoming item being processed in the batch.
 
 ```java
-Link link1 = SpanData.Link.create(parentSpan1.getContext());
-Link link2 = SpanData.Link.create(parentSpan2.getContext());
 Span child = tracer.spanBuilder("childWithLink")
-        .addLink(link1)
-        .addLink(link2)
+        .addLink(parentSpan1.getContext())
+        .addLink(parentSpan2.getContext())
         .addLink(parentSpan3.getContext())
         .addLink(remoteContext)
     .startSpan();
@@ -312,10 +312,10 @@ traces to a logging stream.
 
 ```java
 // Get the tracer
-TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();
+TracerSdkManagement tracerSdkManagement = OpenTelemetrySdk.getTracerManagement();
 
 // Set to export the traces to a logging stream
-tracerProvider.addSpanProcessor(
+tracerSdkManagement.addSpanProcessor(
     SimpleSpanProcessor.newBuilder(
         new LoggingSpanExporter()
     ).build());
@@ -359,13 +359,13 @@ in bulk. Multiple Span processors can be configured to be active at the same tim
 `MultiSpanProcessor`.
 
 ```java
-tracerProvider.addSpanProcessor(
+tracerSdkManagement.addSpanProcessor(
     SimpleSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
 );
-tracerProvider.addSpanProcessor(
+tracerSdkManagement.addSpanProcessor(
     BatchSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
 );
-tracerProvider.addSpanProcessor(MultiSpanProcessor.create(Arrays.asList(
+tracerSdkManagement.addSpanProcessor(MultiSpanProcessor.create(Arrays.asList(
             SimpleSpanProcessor.newBuilder(new LoggingSpanExporter()).build(),
             BatchSpanProcessor.newBuilder(new LoggingSpanExporter()).build()
 )));
@@ -406,7 +406,7 @@ environment variables and builder `set*` methods.
 
 ```java
 // Get TraceConfig associated with TracerSdk 
-TracerConfig traceConfig = OpenTelemetrySdk.getTracerSdkManagement().getActiveTraceConfig();
+TracerConfig traceConfig = OpenTelemetrySdk.getTracerManagement().getActiveTraceConfig();
 
 // Get TraceConfig Builder
 Builder builder = traceConfig.toBuilder();
@@ -421,7 +421,7 @@ builder.readEnvironmentVariables()
 builder.setMaxNumberOfLinks(10);
 
 // Update the resulting TraceConfig instance
-OpenTelemetrySdk.getTracerSdkManagement().updateActiveTraceConfig(builder.build());
+OpenTelemetrySdk.getTracerManagement().updateActiveTraceConfig(builder.build());
 ```
 
 Supported system properties and environment variables:

diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ Published releases are available on maven central.
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-api</artifactId>
-      <version>0.8.0</version>
+      <version>0.9.1</version>
     </dependency>
   </dependencies>
 ```
@@ -62,7 +62,7 @@ Published releases are available on maven central.
 
 ```groovy
 dependencies {
-	implementation('io.opentelemetry:opentelemetry-api:0.8.0')
+	implementation('io.opentelemetry:opentelemetry-api:0.9.1')
 }
 ```
 
@@ -84,7 +84,7 @@ Snapshots based out the `master` branch are available for `opentelemetry-api`, `
     <dependency>
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-api</artifactId>
-      <version>0.9.0-SNAPSHOT</version>
+      <version>0.10.0-SNAPSHOT</version>
     </dependency>
   </dependencies>
 ```
@@ -116,16 +116,16 @@ This is a **current** feature status list:
 
 | Component                   | Version |
 | --------------------------- | ------- |
-| Tracing API                 | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Tracing SDK                 | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Metrics API                 | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Metrics SDK                 | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| OTLP Exporter               | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Jaeger Trace Exporter       | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Zipkin Trace Exporter       | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Prometheus Metrics Exporter | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| Context Propagation         | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
-| OpenTracing Bridge          | v<!--VERSION_STABLE-->0.8.0<!--/VERSION_STABLE-->  |
+| Tracing API                 | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Tracing SDK                 | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Metrics API                 | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Metrics SDK                 | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| OTLP Exporter               | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Jaeger Trace Exporter       | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Zipkin Trace Exporter       | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Prometheus Metrics Exporter | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| Context Propagation         | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
+| OpenTracing Bridge          | v<!--VERSION_STABLE-->0.9.1<!--/VERSION_STABLE-->  |
 | OpenCensus Bridge           | N/A     |
 
 See the project [milestones](https://github.com/open-telemetry/opentelemetry-java/milestones)