feat: apm.getServiceVersion(), apm.getServiceEnvironment(), apm.getSe…

…rviceNodeName() (elastic#3679)

For use by ecs-logging-nodejs packages for log correlation.

Refs: elastic/ecs-logging-nodejs#121
Refs: elastic#3195

CHANGELOG.asciidoc

@@ -47,6 +47,12 @@ See the <<upgrade-to-v4>> guide.
 [float]
 ===== Features
 
+* Add <<apm-get-service-version>>, <<apm-get-service-environment>>, and
+  <<apm-get-service-node-name>>. These are intended for use by
+  {ecs-logging-nodejs-ref}/intro.html[ecs-logging-nodejs formatting packages].
+  See <https://github.com/elastic/ecs-logging-nodejs/pull/152>.
+  ({issues}3195[#3195])
+
 [float]
 ===== Bug fixes
 

docs/agent-api.asciidoc

@@ -40,6 +40,7 @@ Use `isStarted()` to check if the agent has already started.
 Returns `true` if the agent has started,
 otherwise returns `false`.
 
+
 [[apm-get-service-name]]
 ==== `apm.getServiceName()`
 
@@ -50,6 +51,35 @@ explicitly configured, this value may have been automatically determined.
 The service name is not determined until `agent.start()`, so will be `undefined`
 until then. A misconfigured agent can have a `null` service name.
 
+
+[[apm-get-service-version]]
+==== `apm.getServiceVersion()`
+
+[small]#Added in: REPLACEME#
+
+Get the configured <<service-version>>. If a service version was not explicitly
+configured, this value may have been automatically determined.  The service
+version is not determined until `agent.start()`, so will be `undefined` until
+then.
+
+
+[[apm-get-service-environment]]
+==== `apm.getServiceEnvironment()`
+
+[small]#Added in: REPLACEME#
+
+Get the configured <<environment>>.
+
+
+[[apm-get-service-node-name]]
+==== `apm.getServiceNodeName()`
+
+[small]#Added in: REPLACEME#
+
+Get the configured <<service-node-name>>. If the APM agent is not configured
+with an explicit value, this will return `undefined`.
+
+
 [[apm-set-framework]]
 ==== `apm.setFramework(options)`
 

index.d.ts

@@ -21,6 +21,9 @@ declare namespace apm {
     start (options?: AgentConfigOptions): Agent;
     isStarted (): boolean;
     getServiceName (): string | undefined;
+    getServiceVersion (): string | undefined;
+    getServiceEnvironment (): string;
+    getServiceNodeName (): string | undefined;
     setFramework (options: {
       name?: string;
       version?: string;

lib/agent.js

@@ -396,6 +396,18 @@ Agent.prototype.getServiceName = function () {
   return this._conf ? this._conf.serviceName : undefined;
 };
 
+Agent.prototype.getServiceVersion = function () {
+  return this._conf ? this._conf.serviceVersion : undefined;
+};
+
+Agent.prototype.getServiceEnvironment = function () {
+  return this._conf ? this._conf.environment : undefined;
+};
+
+Agent.prototype.getServiceNodeName = function () {
+  return this._conf ? this._conf.serviceNodeName : undefined;
+};
+
 Agent.prototype.setFramework = function ({ name, version, overwrite = true }) {
   if (!this._apmClient || !this._conf) {
     return;

test/agent.test.js

@@ -156,6 +156,47 @@ test('#getServiceName()', function (t) {
   t.end();
 });
 
+test('#getServiceVersion()', function (t) {
+  const agent = new Agent();
+
+  // Before agent.start() the agent hasn't configured yet.
+  t.ok(!agent.isStarted(), 'agent should not have been started yet');
+  t.strictEqual(agent.getServiceVersion(), undefined);
+
+  agent.start(
+    Object.assign({}, agentOptsNoopTransport, { serviceVersion: '1.2.3' }),
+  );
+  t.strictEqual(agent.getServiceVersion(), '1.2.3');
+  t.strictEqual(agent.getServiceVersion(), agent._conf.serviceVersion);
+
+  agent.destroy();
+  t.end();
+});
+
+test('#getServiceEnvironment()', function (t) {
+  const agent = new Agent();
+  agent.start(
+    Object.assign({}, agentOptsNoopTransport, { environment: 'dev' }),
+  );
+  t.strictEqual(agent.getServiceEnvironment(), 'dev');
+  t.strictEqual(agent.getServiceEnvironment(), agent._conf.environment);
+  agent.destroy();
+  t.end();
+});
+
+test('#getServiceNodeName()', function (t) {
+  const agent = new Agent();
+  agent.start(
+    Object.assign({}, agentOptsNoopTransport, {
+      serviceNodeName: 'myNodeName',
+    }),
+  );
+  t.strictEqual(agent.getServiceNodeName(), 'myNodeName');
+  t.strictEqual(agent.getServiceNodeName(), agent._conf.serviceNodeName);
+  agent.destroy();
+  t.end();
+});
+
 test('#setFramework()', function (t) {
   // Use `agentOpts` instead of `agentOptsNoopTransport` because this test is
   // reaching into `agent._apmClient` internals.