comment

Author: trask

api/all/src/main/java/io/opentelemetry/api/logs/LogRecordBuilder.java

@@ -203,6 +203,10 @@ default LogRecordBuilder setAttribute(String key, int value) {
    * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
    * pre-allocate your keys, if possible.
    *
+   * <p>Instrumentations should assume that backends do not index individual properties of complex
+   * attributes, that querying or aggregating on such properties is inefficient and complicated,
+   * and that reporting complex attributes carries higher performance overhead.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @return this.

api/all/src/main/java/io/opentelemetry/api/trace/Span.java

@@ -156,6 +156,10 @@ default Span setAttribute(String key, boolean value) {
    * <p>Note: It is strongly recommended to use {@link #setAttribute(AttributeKey, Object)}, and
    * pre-allocate your keys, if possible.
    *
+   * <p>Instrumentations should assume that backends do not index individual properties of complex
+   * attributes, that querying or aggregating on such properties is inefficient and complicated,
+   * and that reporting complex attributes carries higher performance overhead.
+   *
    * @param key the key for this attribute.
    * @param value the value for this attribute.
    * @return this.