Add javadoc notes to encourage using the lower-overhead attribute opt…

…ions.
open-telemetry · Sep 14, 2020 · 35c1b9b · 35c1b9b
1 parent 5cb599a
commit 35c1b9b
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 0 deletions.
diff --git a/api/src/main/java/io/opentelemetry/common/Attributes.java b/api/src/main/java/io/opentelemetry/common/Attributes.java
@@ -227,6 +227,9 @@ public <T> Builder setAttribute(AttributeKey<T> key, T value) {
     /**
      * Sets a String attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, String value) {
@@ -236,6 +239,9 @@ public Builder setAttribute(String key, String value) {
     /**
      * Sets a long attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, long value) {
@@ -245,6 +251,9 @@ public Builder setAttribute(String key, long value) {
     /**
      * Sets a double attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, double value) {
@@ -254,6 +263,9 @@ public Builder setAttribute(String key, double value) {
     /**
      * Sets a boolean attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, boolean value) {
@@ -263,6 +275,9 @@ public Builder setAttribute(String key, boolean value) {
     /**
      * Sets a String array attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, String... value) {
@@ -272,6 +287,9 @@ public Builder setAttribute(String key, String... value) {
     /**
      * Sets a Long array attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, Long... value) {
@@ -281,6 +299,9 @@ public Builder setAttribute(String key, Long... value) {
     /**
      * Sets a Double array attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, Double... value) {
@@ -290,6 +311,9 @@ public Builder setAttribute(String key, Double... value) {
     /**
      * Sets a Boolean array attribute into this.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @return this Builder
      */
     public Builder setAttribute(String key, Boolean... value) {

diff --git a/api/src/main/java/io/opentelemetry/trace/Span.java b/api/src/main/java/io/opentelemetry/trace/Span.java
@@ -88,6 +88,9 @@ enum Kind {
    * <p>If a null or empty String {@code value} is passed in, the attribute will be silently
    * dropped. Note: this behavior could change in the future.
    *
+   * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @since 0.1.0
@@ -98,6 +101,9 @@ enum Kind {
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
    * the key, the old value is replaced by the specified value.
    *
+   * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @since 0.1.0
@@ -108,6 +114,9 @@ enum Kind {
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
    * the key, the old value is replaced by the specified value.
    *
+   * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @since 0.1.0
@@ -118,6 +127,9 @@ enum Kind {
    * Sets an attribute to the {@code Span}. If the {@code Span} previously contained a mapping for
    * the key, the old value is replaced by the specified value.
    *
+   * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+   * pre-allocate your keys, if possible.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @since 0.1.0
@@ -501,6 +513,9 @@ interface Builder {
      * <p>If a null or empty String {@code value} is passed in, the attribute will be silently
      * dropped. Note: this behavior could change in the future.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @param key the key for this attribute.
      * @param value the value for this attribute.
      * @return this.
@@ -513,6 +528,9 @@ interface Builder {
      * Sets an attribute to the newly created {@code Span}. If {@code Span.Builder} previously
      * contained a mapping for the key, the old value is replaced by the specified value.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @param key the key for this attribute.
      * @param value the value for this attribute.
      * @return this.
@@ -525,6 +543,9 @@ interface Builder {
      * Sets an attribute to the newly created {@code Span}. If {@code Span.Builder} previously
      * contained a mapping for the key, the old value is replaced by the specified value.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @param key the key for this attribute.
      * @param value the value for this attribute.
      * @return this.
@@ -537,6 +558,9 @@ interface Builder {
      * Sets an attribute to the newly created {@code Span}. If {@code Span.Builder} previously
      * contained a mapping for the key, the old value is replaced by the specified value.
      *
+     * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
+     * pre-allocate your keys, if possible.
+     *
      * @param key the key for this attribute.
      * @param value the value for this attribute.
      * @return this.