From 0a08cb8e36b703e7e48f54a6eb17718751512d22 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 24 Apr 2019 10:32:35 -0700 Subject: [PATCH] docs: add links to labels --- docs/agent-api.asciidoc | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index 12cb9afd46..964e72c19e 100644 --- a/docs/agent-api.asciidoc +++ b/docs/agent-api.asciidoc @@ -194,6 +194,9 @@ If an error is captured, the context from the active transaction is used as context for the captured error, and any custom context given as the 2nd argument to <> takes precedence and is shallow merged on top. +TIP: Before using custom context, ensure you understand the different types of +{apm-overview-ref-v}/metadata.html[metadata] that are available. + [[apm-set-tag]] ==== `apm.setTag(name, value)` @@ -235,7 +238,14 @@ You can set multiple labels on the same transaction. If an error happens during the current transaction, it will also get tagged with the same label. -Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). +TIP: Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable +(as opposed to data set via <>). +Before using custom labels, ensure you understand the different types of +{apm-overview-ref-v}/metadata.html[metadata] that are available. + +WARNING: Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +{ref}/mapping.html#mapping-limit-settings[mapping explosion]. [[apm-add-tags]] ==== `apm.addTags({ [name]: value })` @@ -280,7 +290,14 @@ You can add labels multiple times. If an error happens during the current transaction, it will also get tagged with the same labels. -Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via <>). +TIP: Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable +(as opposed to data set via <>). +Before using custom labels, ensure you understand the different types of +{apm-overview-ref-v}/metadata.html[metadata] that are available. + +WARNING: Avoid defining too many user-specified labels. +Defining too many unique fields in an index is a condition that can lead to a +{ref}/mapping.html#mapping-limit-settings[mapping explosion]. [[apm-capture-error]] ==== `apm.captureError(error[, options][, callback])`