Skip to content

Commit 42e951b

Browse files
felixbarnyfelixbarny
authored
Add note that number and boolean labels require APM Server 6.7+ (#608)
1 parent 4ab2b6f commit 42e951b

File tree

2 files changed

+75
-50
lines changed

2 files changed

+75
-50
lines changed

‎apm-agent-api/src/main/java/co/elastic/apm/api/Span.java‎

Lines changed: 58 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -61,39 +61,32 @@ public interface Span {
6161
Span setType(String type);
6262

6363
/**
64-
* A flat mapping of user-defined labels with string values.
65-
* <p>
66-
* Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch.
67-
* As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs).
68-
* </p>
69-
* <p>
70-
* Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable.
71-
* By all means,
72-
* you should avoid that user specified data,
73-
* like URL parameters,
74-
* is used as a label key as it can lead to mapping explosions.
75-
* </p>
76-
*
77-
* @param key The label key.
78-
* @param value The label value.
7964
* @deprecated use {@link #addLabel(String, String)} instead
8065
*/
8166
@Nonnull
8267
@Deprecated
8368
Span addTag(String key, String value);
8469

8570
/**
86-
* A flat mapping of user-defined labels with string values.
8771
* <p>
88-
* Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch.
89-
* As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs).
72+
* Labels are used to add indexed information to transactions, spans, and errors.
73+
* Indexed means the data is searchable and aggregatable in Elasticsearch.
74+
* Multiple labels can be defined with different key-value pairs.
9075
* </p>
76+
* <ul>
77+
* <li>Indexed: Yes</li>
78+
* <li>Elasticsearch type: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html">object</a></li>
79+
* <li>Elasticsearch field: {@code labels} (previously {@code context.tags} in stack version {@code < 7.0})</li>
80+
* </ul>
9181
* <p>
92-
* Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable.
93-
* By all means,
94-
* you should avoid that user specified data,
95-
* like URL parameters,
96-
* is used as a label key as it can lead to mapping explosions.
82+
* Label values can be a string, boolean, or number.
83+
* 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.
84+
* Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}}
85+
* </p>
86+
* <p>
87+
* Important: Avoid defining too many user-specified labels.
88+
* Defining too many unique fields in an index is a condition that can lead to a
89+
* <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping-limit-settings">mapping explosion</a>.
9790
* </p>
9891
*
9992
* @param key The label key.
@@ -104,43 +97,67 @@ public interface Span {
10497
Span addLabel(String key, String value);
10598

10699
/**
107-
* A flat mapping of user-defined labels with number values.
108100
* <p>
109-
* Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch.
110-
* As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs).
101+
* Labels are used to add indexed information to transactions, spans, and errors.
102+
* Indexed means the data is searchable and aggregatable in Elasticsearch.
103+
* Multiple labels can be defined with different key-value pairs.
111104
* </p>
105+
* <ul>
106+
* <li>Indexed: Yes</li>
107+
* <li>Elasticsearch type: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html">object</a></li>
108+
* <li>Elasticsearch field: {@code labels} (previously {@code context.tags} in stack version {@code < 7.0})</li>
109+
* </ul>
112110
* <p>
113-
* Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable.
114-
* By all means,
115-
* you should avoid that user specified data,
116-
* like URL parameters,
117-
* is used as a label key as it can lead to mapping explosions.
111+
* Label values can be a string, boolean, or number.
112+
* 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.
113+
* Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}}
114+
* </p>
115+
* <p>
116+
* Note: Number and boolean labels were only introduced in APM Server 6.7+.
117+
* Using this API in combination with an older APM Server versions leads to validation errors.
118+
* </p>
119+
* <p>
120+
* Important: Avoid defining too many user-specified labels.
121+
* Defining too many unique fields in an index is a condition that can lead to a
122+
* <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping-limit-settings">mapping explosion</a>.
118123
* </p>
119124
*
120125
* @param key The label key.
121126
* @param value The label value.
122-
* @since 1.5.0
127+
* @since 1.5.0, APM Server 6.7
123128
*/
124129
@Nonnull
125130
Span addLabel(String key, Number value);
126131

127132
/**
128-
* A flat mapping of user-defined labels with boolean values.
129133
* <p>
130-
* Note: in version 6.x, labels are stored under {@code context.tags} in Elasticsearch.
131-
* As of version 7.x, they are stored as {@code labels} to comply with ECS (https://github.com/elastic/ecs).
134+
* Labels are used to add indexed information to transactions, spans, and errors.
135+
* Indexed means the data is searchable and aggregatable in Elasticsearch.
136+
* Multiple labels can be defined with different key-value pairs.
132137
* </p>
138+
* <ul>
139+
* <li>Indexed: Yes</li>
140+
* <li>Elasticsearch type: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html">object</a></li>
141+
* <li>Elasticsearch field: {@code labels} (previously {@code context.tags} in stack version {@code < 7.0})</li>
142+
* </ul>
133143
* <p>
134-
* Note: the labels are indexed in Elasticsearch so that they are searchable and aggregatable.
135-
* By all means,
136-
* you should avoid that user specified data,
137-
* like URL parameters,
138-
* is used as a label key as it can lead to mapping explosions.
144+
* Label values can be a string, boolean, or number.
145+
* 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.
146+
* Multiple data types per key will throw an exception, e.g. {@code {foo: bar}} and {@code {foo: 42}}
147+
* </p>
148+
* <p>
149+
* Note: Number and boolean labels were only introduced in APM Server 6.7+.
150+
* Using this API in combination with an older APM Server versions leads to validation errors.
151+
* </p>
152+
* <p>
153+
* Important: Avoid defining too many user-specified labels.
154+
* Defining too many unique fields in an index is a condition that can lead to a
155+
* <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping-limit-settings">mapping explosion</a>.
139156
* </p>
140157
*
141158
* @param key The label key.
142159
* @param value The label value.
143-
* @since 1.5.0
160+
* @since 1.5.0, APM Server 6.7
144161
*/
145162
@Nonnull
146163
Span addLabel(String key, boolean value);

‎docs/public-api.asciidoc‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -286,17 +286,25 @@ transaction.setType(Transaction.TYPE_REQUEST);
286286
287287
[float]
288288
[[api-transaction-add-tag]]
289-
==== `Transaction addLabel(String key, value)` added[1.5.0]
290-
A flat mapping of user-defined labels with string, number or boolean values.
289+
==== `Transaction addLabel(String key, value)` added[1.5.0,Number and boolean labels require APM Server 6.7]
290+
Labels are used to add *indexed* information to transactions, spans, and errors.
291+
Indexed means the data is searchable and aggregatable in Elasticsearch.
292+
Multiple labels can be defined with different key-value pairs.
291293
292-
NOTE: In version 6.x, labels are stored under `context.tags` in Elasticsearch.
293-
As of version 7.x, they are stored as `labels` to comply with the https://github.com/elastic/ecs[Elastic Common Schema (ECS)].
294+
* Indexed: Yes
295+
* Elasticsearch type: {ref}/object.html[object]
296+
* Elasticsearch field: `labels` (previously `context.tags` in <v.7.0)
294297
295-
NOTE: The labels are indexed in Elasticsearch so that they are searchable and aggregatable.
296-
By all means,
297-
you should avoid that user specified data,
298-
like URL parameters,
299-
is used as a tag key as it can lead to mapping explosions.
298+
Label values can be a string, boolean, or number.
299+
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.
300+
Multiple data types per key will throw an exception, e.g. `{foo: bar}` and `{foo: 42}`
301+
302+
NOTE: Number and boolean labels were only introduced in APM Server 6.7+.
303+
Using this API in combination with an older APM Server versions leads to validation errors.
304+
305+
IMPORTANT: Avoid defining too many user-specified labels.
306+
Defining too many unique fields in an index is a condition that can lead to a
307+
{ref}/mapping.html#mapping-limit-settings[mapping explosion].
300308
301309
[source,java]
302310
----

0 commit comments

Comments
 (0)