feat: add apm.setGlobalLabel()

[afharo]

In Kibana, we'd like to be able to update some of the global labels based on some dynamic information. The existing apm.addLabels or apm.setLabel only apply to the current transaction, but we need these specific labels to be applied to all the transactions.

Related to elastic/kibana#157093

Checklist

• Implement code
• Add tests
• Update TypeScript typings
• Update documentation
• Add CHANGELOG.asciidoc entry
• Commit message follows commit guidelines

[trentm]

Thanks! This looks great and works for me. I used this example script to try it out: https://gist.github.com/trentm/bc7a6ae0cb849bccf3b87857963185b0

A couple suggested changes:

1. What do you think about not having this return true? I don't see the value. The existing setLabel only has that to handle there not being a current transaction. If so, then this patch would remove that:

diff --git a/index.d.ts b/index.d.ts
index e2ecc452..b3614ca4 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -116,7 +116,7 @@ declare namespace apm {
     currentSpan: Span | null;

     // Context
-    setGlobalLabel (name: string, value: LabelValue): boolean;
+    setGlobalLabel (name: string, value: LabelValue): void;
     setLabel (name: string, value: LabelValue, stringify?: boolean): boolean;
     addLabels (labels: Labels, stringify?: boolean): boolean;
     setUserContext (user: UserObject): void;
diff --git a/lib/agent.js b/lib/agent.js
index 1c378353..d11320be 100644
--- a/lib/agent.js
+++ b/lib/agent.js
@@ -368,7 +368,6 @@ Agent.prototype.setGlobalLabel = function (key, value) {
       return acc
     }, {})
   })
-  return true
 }

 Agent.prototype.setLabel = function (key, value, stringify) {

2. Here is an update to the agent.test.js that will have the agent send an actual transaction (and updated metadata) to a mock APM server. This allows the test to verify that the this._transport.config(...) call in the implementation did the necessary work.

patch: https://gist.github.com/trentm/c74e0e5ae5f626e67ad84116349eb6a3

my full test/agent.test.js if that is easier for you to apply: https://gist.github.com/trentm/5f571ecf1d55aa91d2b8b24823f99ff2

[afharo]

Thank you, @trentm! 🧡

Your suggestions make perfect sense to me! I applied them in a8dab78 (#3337). Thank you for showing me The way!

[david-luna]

Thank you @afharo for your contribution. Just a small comment but not blocking

[david-luna]

is this a linter problem or our editor did some autoformatting?

[afharo]

Oops! Not sure what happened here... probably my IDE behaving. I removed those extra spaces in my last commit 😇