From a85cdda9a895c625706daf6a78c2beb043e907bc Mon Sep 17 00:00:00 2001 From: Felix Barnsteiner Date: Wed, 24 Apr 2019 08:04:26 +0200 Subject: [PATCH 1/4] Add note that number and boolean labels requere APM Server 6.7+ --- .../main/java/co/elastic/apm/api/Span.java | 99 +++++++++++-------- docs/public-api.asciidoc | 24 +++-- 2 files changed, 74 insertions(+), 49 deletions(-) diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java index 43912acc1e..62eaf2a4f5 100644 --- a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java +++ b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java @@ -61,21 +61,6 @@ public interface Span { Span setType(String type); /** - * A flat mapping of user-defined labels with string values. - *

- * Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch. - * As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs). - *

- *

- * Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable. - * By all means, - * you should avoid that user specified data, - * like URL parameters, - * is used as a label key as it can lead to mapping explosions. - *

- * - * @param key The label key. - * @param value The label value. * @deprecated use {@link #addLabel(String, String)} instead */ @Nonnull @@ -83,17 +68,25 @@ public interface Span { Span addTag(String key, String value); /** - * A flat mapping of user-defined labels with string values. *

- * Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch. - * As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs). + * Labels are used to add indexed information to transactions, spans, and errors. + * Indexed means the data is searchable and aggregatable in Elasticsearch. + * Multiple labels can be defined with different key-value pairs. *

+ * *

- * Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable. - * By all means, - * you should avoid that user specified data, - * like URL parameters, - * is used as a label key as it can lead to mapping explosions. + * Label values can be a string, boolean, or number. + * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} + *

+ *

+ * Important: Avoid defining too many user-specified labels. + * Defining too many unique fields in an index is a condition that can lead to a + * mapping explosion. *

* * @param key The label key. @@ -104,43 +97,67 @@ public interface Span { Span addLabel(String key, String value); /** - * A flat mapping of user-defined labels with number values. *

- * Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch. - * As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs). + * Labels are used to add indexed information to transactions, spans, and errors. + * Indexed means the data is searchable and aggregatable in Elasticsearch. + * Multiple labels can be defined with different key-value pairs. *

+ * *

- * Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable. - * By all means, - * you should avoid that user specified data, - * like URL parameters, - * is used as a label key as it can lead to mapping explosions. + * Label values can be a string, boolean, or number. + * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} + *

+ *

+ * Note: Number and boolean labels were only introduced in APM Server 6.7+. + * Using this API in combination with an older APM Server versions leads to validation errors. + *

+ *

+ * Important: Avoid defining too many user-specified labels. + * Defining too many unique fields in an index is a condition that can lead to a + * mapping explosion. *

* * @param key The label key. * @param value The label value. - * @since 1.5.0 + * @since 1.5.0, APM Server 6.7 */ @Nonnull Span addLabel(String key, Number value); /** - * A flat mapping of user-defined labels with boolean values. *

- * Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch. - * As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs). + * Labels are used to add indexed information to transactions, spans, and errors. + * Indexed means the data is searchable and aggregatable in Elasticsearch. + * Multiple labels can be defined with different key-value pairs. *

+ * *

- * Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable. - * By all means, - * you should avoid that user specified data, - * like URL parameters, - * is used as a label key as it can lead to mapping explosions. + * Label values can be a string, boolean, or number. + * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} + *

+ *

+ * Note: Number and boolean labels were only introduced in APM Server 6.7+. + * Using this API in combination with an older APM Server versions leads to validation errors. + *

+ *

+ * Important: Avoid defining too many user-specified labels. + * Defining too many unique fields in an index is a condition that can lead to a + * mapping explosion. *

* * @param key The label key. * @param value The label value. - * @since 1.5.0 + * @since 1.5.0, APM Server 6.7 */ @Nonnull Span addLabel(String key, boolean value); diff --git a/docs/public-api.asciidoc b/docs/public-api.asciidoc index ae80320c22..7c8d71b47f 100644 --- a/docs/public-api.asciidoc +++ b/docs/public-api.asciidoc @@ -287,16 +287,24 @@ transaction.setType(Transaction.TYPE_REQUEST); [float] [[api-transaction-add-tag]] ==== `Transaction addLabel(String key, value)` added[1.5.0] -A flat mapping of user-defined labels with string, number or boolean values. +Labels are used to add *indexed* information to transactions, spans, and errors. +Indexed means the data is searchable and aggregatable in Elasticsearch. +Multiple labels can be defined with different key-value pairs. -NOTE: In version 6.x, labels are stored under `context.tags` in Elasticsearch. -As of version 7.x, they are stored as `labels` to comply with the https://github.com/elastic/ecs[Elastic Common Schema (ECS)]. +* Indexed: Yes +* Elasticsearch type: {ref}/object.html[object] +* Elasticsearch field: `labels` (previously `context.tags` in Date: Wed, 24 Apr 2019 09:25:12 +0200 Subject: [PATCH 2/4] Update apm-agent-api/src/main/java/co/elastic/apm/api/Span.java Co-Authored-By: felixbarny --- apm-agent-api/src/main/java/co/elastic/apm/api/Span.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java index 62eaf2a4f5..38ff351fbe 100644 --- a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java +++ b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java @@ -80,7 +80,7 @@ public interface Span { * *

* Label values can be a string, boolean, or number. - * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} *

*

From 575dffe0a5e46ab22b271f7d6d5778a2cc06a264 Mon Sep 17 00:00:00 2001 From: Felix Barnsteiner Date: Wed, 24 Apr 2019 09:28:30 +0200 Subject: [PATCH 3/4] Apply suggestion to all places --- apm-agent-api/src/main/java/co/elastic/apm/api/Span.java | 4 ++-- docs/public-api.asciidoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java index 38ff351fbe..21bf1ba6dd 100644 --- a/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java +++ b/apm-agent-api/src/main/java/co/elastic/apm/api/Span.java @@ -109,7 +109,7 @@ public interface Span { * *

* Label values can be a string, boolean, or number. - * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} *

*

@@ -142,7 +142,7 @@ public interface Span { * *

* Label values can be a string, boolean, or number. - * Because labels are stored in the same place in Elasticsearch, each value must have the same data type. + * Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. * Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}} *

*

diff --git a/docs/public-api.asciidoc b/docs/public-api.asciidoc index 7c8d71b47f..cf8222361c 100644 --- a/docs/public-api.asciidoc +++ b/docs/public-api.asciidoc @@ -296,7 +296,7 @@ Multiple labels can be defined with different key-value pairs. * Elasticsearch field: `labels` (previously `context.tags` in Date: Wed, 24 Apr 2019 15:54:20 +0200 Subject: [PATCH 4/4] Update docs/public-api.asciidoc --- docs/public-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-api.asciidoc b/docs/public-api.asciidoc index cf8222361c..e05a4547b6 100644 --- a/docs/public-api.asciidoc +++ b/docs/public-api.asciidoc @@ -286,7 +286,7 @@ transaction.setType(Transaction.TYPE_REQUEST); [float] [[api-transaction-add-tag]] -==== `Transaction addLabel(String key, value)` added[1.5.0] +==== `Transaction addLabel(String key, value)` added[1.5.0,Number and boolean labels require APM Server 6.7] Labels are used to add *indexed* information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs.