Skip to content

Commit 8ff0ef3

Browse files
jsumners-nrjsumners-nr
authored
chore: Document emitted events (#2561)
1 parent d534ba6 commit 8ff0ef3

18 files changed

+438
-34
lines changed

‎lib/agent.js

Lines changed: 117 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,94 @@ const MAX_ERROR_TRACES_DEFAULT = 20
5757
const INITIAL_HARVEST_DELAY_MS = 1000
5858
const DEFAULT_HARVEST_INTERVAL_MS = 60000
5959

60+
/**
61+
* Indicates that the agent has finished connecting. It is preceded by
62+
* {@link Agent#event:connecting}.
63+
*
64+
* @event Agent#connected
65+
*/
66+
67+
/**
68+
* Indicates that the agent is in the connecting state. That is, it is
69+
* communicating with the New Relic data collector and performing requisite
70+
* operations before the agent is ready to collect and send data.
71+
*
72+
* @event Agent#connecting
73+
*/
74+
75+
/**
76+
* Indicates that the agent has terminated, or lost, its connection to the
77+
* New Relic data collector.
78+
*
79+
* @event Agent#disconnected
80+
*/
81+
82+
/**
83+
* Indicates that the agent has encountered, or generated, some error that
84+
* prevents it from operating correctly. The agent state will be set to
85+
* "errored."
86+
*
87+
* @event Agent#errored
88+
*/
89+
90+
/**
91+
* Indicates that the synchronous harvest cycle has completed. This will be
92+
* prefaced by the {@link Agent#event:harvestStarted} event. It is only fired
93+
* in a serverless context.
94+
*
95+
* @event Agent#harvestFinished
96+
*/
97+
98+
/**
99+
* Indicates that a synchronous harvest cycle (collecting data from the various
100+
* aggregators and sending said data to the New Relic data collector) has
101+
* started. This is only fired in a serverless context.
102+
*
103+
* @event Agent#harvestStarted
104+
*/
105+
106+
/**
107+
* Indicates that the agent state has entered the "started" state. That is,
108+
* the agent has finished bootstrapping and is collecting and sending data.
109+
*
110+
* @event Agent#started
111+
*/
112+
113+
/**
114+
* Indicates that the agent is starting. This is typically the first event
115+
* emitted by the agent.
116+
*
117+
* @event Agent#starting
118+
*/
119+
120+
/**
121+
* Indicates that the agent state has changed to the "stopped" state. That is,
122+
* the agent is no longer collecting or sending data.
123+
*
124+
* @event Agent#stopped
125+
*/
126+
127+
/**
128+
* Indicates that the agent is entering its shutdown process.
129+
*
130+
* @event Agent#stopping
131+
*/
132+
133+
/**
134+
* Indicates that the transaction has begun recording data.
135+
*
136+
* @event Agent#transactionStarted
137+
* @param {Transaction} currentTransaction
138+
*/
139+
140+
/**
141+
* Indicates that the transaction has stopped recording data and has been
142+
* closed.
143+
*
144+
* @event Agent#transactionFinished
145+
* @param {Transaction} currentTransaction
146+
*/
147+
60148
/**
61149
* There's a lot of stuff in this constructor, due to Agent acting as the
62150
* orchestrator for New Relic within instrumented applications.
@@ -101,7 +189,7 @@ function Agent(config) {
101189
this.harvester
102190
)
103191

104-
this.metrics.on('starting metric_data data send.', this._beforeMetricDataSend.bind(this))
192+
this.metrics.on('starting_data_send-metric_data', this._beforeMetricDataSend.bind(this))
105193

106194
this.spanEventAggregator = createSpanEventAggregator(config, this)
107195

@@ -226,6 +314,12 @@ util.inherits(Agent, EventEmitter)
226314
*
227315
* @param {Function} callback Continuation and error handler.
228316
* @returns {void}
317+
*
318+
* @fires Agent#errored When configuration is not sufficient for operations or
319+
* cannot establish a connection to the data collector.
320+
* @fires Agent#starting
321+
* @fires Agent#stopped When configuration indicates that the agent should be
322+
* disabled.
229323
*/
230324
Agent.prototype.start = function start(callback) {
231325
if (!callback) {
@@ -306,6 +400,8 @@ Agent.prototype.startStreaming = function startStreaming() {
306400
*
307401
* @param {boolean} shouldImmediatelyHarvest Whether we should immediately schedule a harvest, or wait a cycle
308402
* @param {Function} callback callback function that executes after harvest completes (now if immediate, otherwise later)
403+
*
404+
* @fires Agent#started
309405
*/
310406
Agent.prototype.onConnect = function onConnect(shouldImmediatelyHarvest, callback) {
311407
this.harvester.update(this.config)
@@ -368,6 +464,11 @@ Agent.prototype._serverlessModeStart = function _serverlessModeStart(callback) {
368464
* current instrumentation and patch to the module loader.
369465
*
370466
* @param {Function} callback callback function to invoke after agent stop
467+
*
468+
* @fires Agent#errored When disconnecting from the data collector has resulted
469+
* in some error.
470+
* @fires Agent#stopped
471+
* @fires Agent#stopping
371472
*/
372473
Agent.prototype.stop = function stop(callback) {
373474
if (!callback) {
@@ -432,9 +533,13 @@ Agent.prototype._resetCustomEvents = function resetCustomEvents() {
432533
}
433534

434535
/**
435-
* This method invokes a harvest synchronously.
536+
* This method invokes a harvest synchronously, i.e. sends all data to the
537+
* New Relic collector in a blocking fashion.
538+
*
539+
* NOTE: this doesn't currently work outside serverless mode.
436540
*
437-
* NOTE: this doesn't currently work outside of serverless mode.
541+
* @fires Agent#harvestStarted
542+
* @fires Agent#harvestFinished
438543
*/
439544
Agent.prototype.harvestSync = function harvestSync() {
440545
logger.trace('Peparing to harvest.')
@@ -518,6 +623,15 @@ Agent.prototype.reconfigure = function reconfigure(configuration) {
518623
* creation of Transactions.
519624
*
520625
* @param {string} newState The new state of the agent.
626+
*
627+
* @fires Agent#connected
628+
* @fires Agent#connecting
629+
* @fires Agent#disconnected
630+
* @fires Agent#errored
631+
* @fires Agent#started
632+
* @fires Agent#starting
633+
* @fires Agent#stopped
634+
* @fires Agent#stopping
521635
*/
522636
Agent.prototype.setState = function setState(newState) {
523637
if (!STATES.hasOwnProperty(newState)) {

‎lib/aggregators/base-aggregator.js

Lines changed: 182 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,152 @@
88
const EventEmitter = require('events').EventEmitter
99
const logger = require('../logger').child({ component: 'base_aggregator' })
1010

11+
/**
12+
* Triggered when the aggregator has finished sending data to the
13+
* `analytic_event_data` collector endpoint.
14+
*
15+
* @event Aggregator#finished_data_send-analytic_event_data
16+
*/
17+
18+
/**
19+
* Triggered when an aggregator is sending data to the `analytic_event_data`
20+
* collector endpoint.
21+
*
22+
* @event Aggregator#starting_data_send-analytic_event_data
23+
*/
24+
25+
/**
26+
* Triggered when the aggregator has finished sending data to the
27+
* `custom_event_data` collector endpoint.
28+
*
29+
* @event Aggregator#finished_data_send-custom_event_data
30+
*/
31+
32+
/**
33+
* Triggered when an aggregator is sending data to the `custom_event_data`
34+
* collector endpoint.
35+
*
36+
* @event Aggregator#starting_data_send-custom_event_data
37+
*/
38+
39+
/**
40+
* Triggered when the aggregator has finished sending data to the
41+
* `error_data` collector endpoint.
42+
*
43+
* @event Aggregator#finished_data_send-error_data
44+
*/
45+
46+
/**
47+
* Triggered when an aggregator is sending data to the `error_data`
48+
* collector endpoint.
49+
*
50+
* @event Aggregator#starting_data_send-error_data
51+
*/
52+
53+
/**
54+
* Triggered when the aggregator has finished sending data to the
55+
* `error_event_data` collector endpoint.
56+
*
57+
* @event Aggregator#finished_data_send-error_event_data
58+
*/
59+
60+
/**
61+
* Triggered when an aggregator is sending data to the `error_event_data`
62+
* collector endpoint.
63+
*
64+
* @event Aggregator#starting_data_send-error_event_data
65+
*/
66+
67+
/**
68+
* Triggered when the aggregator has finished sending data to the
69+
* `log_event_data` collector endpoint.
70+
*
71+
* @event Aggregator#finished_data_send-log_event_data
72+
*/
73+
74+
/**
75+
* Triggered when an aggregator is sending data to the `log_event_data`
76+
* collector endpoint.
77+
*
78+
* @event Aggregator#starting_data_send-log_event_data
79+
*/
80+
81+
/**
82+
* Triggered when the aggregator has finished sending data to the
83+
* `metric_data` collector endpoint.
84+
*
85+
* @event Aggregator#finished_data_send-metric_data
86+
*/
87+
88+
/**
89+
* Triggered when an aggregator is sending data to the `metric_data`
90+
* collector endpoint.
91+
*
92+
* @event Aggregator#starting_data_send-metric_data
93+
*/
94+
95+
/**
96+
* Triggered when the aggregator has finished sending data to the
97+
* `span_event_data` collector endpoint.
98+
*
99+
* @event Aggregator#finished_data_send-span_event_data
100+
*/
101+
102+
/**
103+
* Triggered when an aggregator is sending data to the `span_event_data`
104+
* collector endpoint.
105+
*
106+
* @event Aggregator#starting_data_send-span_event_data
107+
*/
108+
109+
/**
110+
* Triggered when the aggregator has finished sending data to the
111+
* `sql_trace_data` collector endpoint.
112+
*
113+
* @event Aggregator#finished_data_send-sql_trace_data
114+
*/
115+
116+
/**
117+
* Triggered when an aggregator is sending data to the `sql_trace_data`
118+
* collector endpoint.
119+
*
120+
* @event Aggregator#starting_data_send-sql_trace_data
121+
*/
122+
123+
/**
124+
* Triggered when the aggregator has finished sending data to the
125+
* `transaction_sample_data` collector endpoint.
126+
*
127+
* @event Aggregator#finished_data_send-transaction_sample_data
128+
*/
129+
130+
/**
131+
* Triggered when an aggregator is sending data to the `transaction_sample_data`
132+
* collector endpoint.
133+
*
134+
* @event Aggregator#starting_data_send-transaction_sample_data
135+
*/
136+
137+
/**
138+
* Baseline data aggregator that is used to ship data to the New Relic
139+
* data collector. Specific data aggregators, e.g. an errors aggregator,
140+
* extend this base object.
141+
*
142+
* Aggregators fire of several events. The events are named according to the
143+
* pattern `<finished|starting>_data_send-<endpoint_name>`. As an example,
144+
* if the aggregator is collecting data to send to the `error_event_data`
145+
* endpoint, there will be two events:
146+
*
147+
* + `starting_data_send-error_event_data`
148+
* + `finished_data_send-error_event_data`
149+
*
150+
* For a list of possible endpoints, see
151+
* {@link https://source.datanerd.us/agents/agent-specs/tree/main/endpoints/protocol-version-17}.
152+
*
153+
* Note: effort has been made to document the events for every endpoint this
154+
* agent interacts with, but due to the dynamic nature of the event names we
155+
* may have missed some.
156+
*/
11157
class Aggregator extends EventEmitter {
12158
constructor(opts, collector, harvester) {
13159
super()
@@ -23,6 +169,16 @@ class Aggregator extends EventEmitter {
23169
return true
24170
}
25171
this.enabled = this.isEnabled(opts.config)
172+
173+
/**
174+
* The name of the collector endpoint that the
175+
* aggregator will communicate with.
176+
*
177+
* @see https://source.datanerd.us/agents/agent-specs/tree/main/endpoints/protocol-version-17
178+
*
179+
* @type {string}
180+
* @memberof Aggregator
181+
*/
26182
this.method = opts.method
27183
this.collector = collector
28184
this.sendTimer = null
@@ -90,7 +246,7 @@ class Aggregator extends EventEmitter {
90246
_runSend(data, payload) {
91247
if (!payload) {
92248
this._afterSend(false)
93-
this.emit(`finished ${this.method} data send.`)
249+
this.emit(`finished_data_send-${this.method}`)
94250
return
95251
}
96252

@@ -102,13 +258,36 @@ class Aggregator extends EventEmitter {
102258

103259
// TODO: Log?
104260
this._afterSend(true)
105-
this.emit(`finished ${this.method} data send.`)
261+
this.emit(`finished_data_send-${this.method}`)
106262
})
107263
}
108264

265+
/**
266+
* Serialize all collected data and ship it off to the New Relic data
267+
* collector. The target endpoint is defined by {@link Aggregator#method}.
268+
*
269+
* @fires Aggregator#finished_data_send-analytic_event_data
270+
* @fires Aggregator#starting_data_send-analytic_event_data
271+
* @fires Aggregator#finished_data_send-custom_event_data
272+
* @fires Aggregator#starting_data_send-custom_event_data
273+
* @fires Aggregator#finished_data_send-error_data
274+
* @fires Aggregator#starting_data_send-error_data
275+
* @fires Aggregator#finished_data_send-error_event_data
276+
* @fires Aggregator#starting_data_send-error_event_data
277+
* @fires Aggregator#finished_data_send-log_event_data
278+
* @fires Aggregator#starting_data_send-log_event_data
279+
* @fires Aggregator#finished_data_send-metric_data
280+
* @fires Aggregator#starting_data_send-metric_data
281+
* @fires Aggregator#finished_data_send-span_event_data
282+
* @fires Aggregator#starting_data_send-span_event_data
283+
* @fires Aggregator#finished_data_send-sql_trace_data
284+
* @fires Aggregator#starting_data_send-sql_trace_data
285+
* @fires Aggregator#finished_data_send-transaction_sample_data
286+
* @fires Aggregator#starting_data_send-transaction_sample_data
287+
*/
109288
send() {
110289
logger.debug(`${this.method} Aggregator data send.`)
111-
this.emit(`starting ${this.method} data send.`)
290+
this.emit(`starting_data_send-${this.method}`)
112291

113292
const data = this._getMergeData()
114293
if (this.isAsync) {

0 commit comments

Comments
 (0)