docs: add api docs for apiRequestTime and apiRequestSize (elastic#499)

Author: watson

docs/agent-api.asciidoc

@@ -539,41 +539,46 @@ Specify the maximum number of spans to capture within a request transaction
 before dropping further spans.
 Setting to `-1` means that spans will never be dropped.
 
-[[flush-interval]]
-===== `flushInterval`
+[[api-request-time]]
+===== `apiRequestTime`
 
 * *Type:* Number
 * *Default:* `10`
-* *Env:* `ELASTIC_APM_FLUSH_INTERVAL`
+* *Env:* `ELASTIC_APM_API_REQUEST_TIME`
 
-The agent maintains an in-memory queue to which recorded transactions are added when they end.
-Unless empty,
-this queue is flushed and sent to the APM Server for processing approximately every 10 seconds.
+The agent maintains an open HTTP request to the APM Server that is used to transmit the collected transactions,
+spans,
+and errors to the server.
 
-Use this option to change that interval.
+To avoid issues with intermittent proxies and load balancers,
+the HTTP request is ended and a new one created at regular intervals controlled by this config option.
 The value is expected to be in seconds.
 
-Lowering this interval can reduce memory usage on Node.js applications with a high number of transactions.
-
 [NOTE]
 ====
-The queue is flushed approximately 5 seconds after the first transaction has ended on a newly started Node process.
-
-This ensures that you don't have to wait for the entire `flushInterval` to pass for the first data to be sent to the APM Server.
-From there on the `flushInterval` option is used.
+The HTTP request is ended before the time threshold is reached if enough bytes are sent over it.
+Use the <<api-request-size,`apiRequestSize`>> config option to control the byte threshold.
 ====
 
-[NOTE]
-====
-After each flush of the queue,
-the next flush isn't scheduled until a transaction have ended.
+[[api-request-size]]
+===== `apiRequestSize`
 
-This is done to introduce variance and also ensures that empty queues are not scheduled for flushing.
+* *Type:* Number
+* *Default:* `1048576` (1 MiB)
+* *Env:* `ELASTIC_APM_API_REQUEST_SIZE`
+
+The agent maintains an open HTTP request to the APM Server that is used to transmit the collected transactions,
+spans,
+and errors to the server.
 
-On top of that,
-the actual interval is adjusted by +/- 5% between each flush.
+To avoid issues with intermittent proxies and load balancers,
+the HTTP request is ended and a new one created if its body becomes too large.
+That limit is controlled by this config option.
+The value is expected to be in bytes.
 
-This all helps to ensure that multiple servers started at the same time will not establish connections to the APM Server simultaneously.
+[NOTE]
+====
+The HTTP request is otherwise ended at regular intervals controlled by the <<api-request-time,`apiRequestTime`>> config option.
 ====
 
 [[server-timeout]]
@@ -583,22 +588,11 @@ This all helps to ensure that multiple servers started at the same time will not
 * *Default:* `30`
 * *Env:* `ELASTIC_APM_SERVER_TIMEOUT`
 
-Specify the timeout in seconds when reporting transactions to APM Server.
-
-[[max-queue-size]]
-===== `maxQueueSize`
-
-* *Type:* Number
-* *Default:* `100`
-* *Env:* `ELASTIC_APM_MAX_QUEUE_SIZE`
-
-The agent maintains an in-memory queue to which recorded transactions are added when they end.
-The queue is flushed with regular intervals controlled by the <<flush-interval,`flushInterval`>> config option.
-
-Use the `maxQueueSize` option to force a flush of the queue when it reaches a certain size (number of ended transactions) - even if the `flushInterval` time isn't reached yet.
+Specify the response timeout in seconds when reporting transactions to APM Server.
 
-Set to `-1` to disable,
-in which case only `flushInterval` counts.
+The timeout is applied once the agent have sent the entire request body to the APM Server.
+If the response from the server takes longer than allowed by this timeout,
+the HTTP request is terminated and the TCP socket closed.
 
 [[filter-http-headers]]
 ===== `filterHttpHeaders`
@@ -1156,11 +1150,12 @@ apm.flush(function (err) {
 })
 ----
 
-Manually flush the in-memory transaction queue and send all the transactions to the APM Server.
-The queue is otherwise flushed automatically,
-controlled by the <<flush-interval,`flushInterval`>> and/or <<max-queue-size,`maxQueueSize`>> config options.
+Manually end the active outgoing HTTP request to the APM Server.
+The HTTP request is otherwise ended automatically at regular intervals,
+controlled by the <<api-request-time,`apiRequestTime`>> and <<api-request-size,`apiRequestSize`>> config options.
 
-The callback is called *after* the event has been sent to the APM Server with a possible error argument.
+The callback is called *after* the active HTTP request have ended.
+The callback is called even if no HTTP request is currently active.
 
 [[apm-lambda]]
 ==== `apm.lambda([type, ] handler)`

docs/performance-tuning.asciidoc

@@ -36,42 +36,58 @@ require('elastic-apm-node').start({
 ----
 
 [float]
-[[performance-transaction-queue]]
-=== Transaction Queue
+[[performance-apm-server-communication]]
+=== APM Server communication
 
-The agent buffers the collected data using an in-memory queue before sending it to the APM Server.
-The queue is flushed either after a specific <<performance-flush-interval,amount of time>> or when it reaches <<performance-max-queue-size,a certain size>> -
-whichever comes first.
-Lowering these defaults can reduce memory usage,
-but will increase the number of requests to the APM Server.
+The agent uses a persistent outgoing HTTP request to stream data to the APM Server.
+To avoid issues with intermittent proxies and load balancers,
+the HTTP request is ended and a new one created at regular intervals or when the size of the request becomes too big.
+
+There's an overhead involved in each HTTP request:
+Besides sending new HTTP headers,
+the agent needs to re-send certain metadata to the APM Server each time a new HTTP request is made.
+However,
+if allowed by the network,
+the TCP socket is reused between each HTTP request.
 
 [float]
-[[performance-flush-interval]]
-==== Flush Interval
+[[performance-api-request-time]]
+==== Max HTTP request duration
 
-To prevent items from staying in the queue for a long time during low activity,
-the <<flush-interval,`flushInterval`>> setting is used to ensure the queue empties if anything in it is too old.
+By default an HTTP request to the APM Server is ended after a maximum of 10 seconds.
+Using the <<api-request-time,`apiRequestTime`>> config option,
+this time limit can be modified.
 
-Lowering the flush interval will ensure transactions are sent to the APM Server faster,
-but may also result in increased HTTP traffic and CPU usage.
+Lowering the time limit might be necessary if dealing with very agressive proxies,
+but increasing the time limit means that the combined overhead of these HTTP requests is reduced,
+as headers and metadata doesn't need to be re-sent that often.
 
 [float]
-[[performance-max-queue-size]]
-==== Max Queue Size
+[[performance-api-request-size]]
+==== Max HTTP request size
 
-The <<max-queue-size,`maxQueueSize`>> controls the maximum number of transactions that may remain in the queue before they must be sent.
+By default an HTTP request to the APM Server is ended after approximately 1 MiB of gzip compressed data have been written to the body.
+Using the <<api-request-size,`apiRequestSize`>> config option,
+this time limit can be modified.
 
-Lowering this will reduce memory consumption,
-however it will increase the number of requests made to the APM Server.
+Lowering the size limit might be necessary if dealing with very agressive proxies,
+but increasing the size limit means that the combined overhead of these HTTP requests is reduced,
+as headers and metadata doesn't need to be re-sent that often.
 
 [float]
 [[performance-server-timeout]]
-=== APM Server Timeout
+==== APM Server Timeout
+
+In the event that the APM Server or the connection to the APM Server is slow or unstable,
+the <<server-timeout,`serverTimeout`>> setting can be set to ensure the agent doesn't wait too long for a response.
+
+The agent only allows for a single TCP socket to be opened to the APM Server at any given time.
+This is to avoid the overhead of opening too many sockets.
+If the agent is stuck waiting for a response from the previous HTTP request,
+it might start dropping new data in order to keep its memory footprint low.
 
-In the event that the connection to the APM Server is slow or unstable,
-the <<server-timeout,`serverTimeout`>> setting can be set to ensure connections don't stay open too long.
-If the server timeout is too high,
-it may result in too many socket descriptors being held open.
+Keeping this timeout low,
+helps alleviate that problem.
 
 [float]
 [[performance-stack-traces]]

lib/config.js

@@ -51,10 +51,8 @@ var DEFAULTS = {
   sourceLinesSpanAppFrames: 0,
   sourceLinesSpanLibraryFrames: 0,
   errorMessageMaxLength: 2048,
-  flushInterval: 10, // TODO: Deprecate
   transactionMaxSpans: 500,
   transactionSampleRate: 1.0,
-  maxQueueSize: 100, // TODO: Deprecate
   serverTimeout: 30,
   disableInstrumentations: []
 }
@@ -81,8 +79,6 @@ var ENV_TABLE = {
   errorOnAbortedRequests: 'ELASTIC_APM_ERROR_ON_ABORTED_REQUESTS',
   abortedErrorThreshold: 'ELASTIC_APM_ABORTED_ERROR_THRESHOLD',
   instrument: 'ELASTIC_APM_INSTRUMENT',
-  flushInterval: 'ELASTIC_APM_FLUSH_INTERVAL',
-  maxQueueSize: 'ELASTIC_APM_MAX_QUEUE_SIZE',
   asyncHooks: 'ELASTIC_APM_ASYNC_HOOKS',
   sourceLinesErrorAppFrames: 'ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES',
   sourceLinesErrorLibraryFrames: 'ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES',
@@ -111,8 +107,6 @@ var NUM_OPTS = [
   'apiRequestTime',
   'stackTraceLimit',
   'abortedErrorThreshold',
-  'flushInterval',
-  'maxQueueSize',
   'sourceLinesErrorAppFrames',
   'sourceLinesErrorLibraryFrames',
   'sourceLinesSpanAppFrames',
@@ -124,7 +118,6 @@ var NUM_OPTS = [
 ]
 
 var MINUS_ONE_EQUAL_INFINITY = [
-  'maxQueueSize',
   'transactionMaxSpans'
 ]
 

test/config.js

@@ -41,8 +41,6 @@ var optionFixtures = [
   ['errorOnAbortedRequests', 'ERROR_ON_ABORTED_REQUESTS', false],
   ['abortedErrorThreshold', 'ABORTED_ERROR_THRESHOLD', 25000],
   ['instrument', 'INSTRUMENT', true],
-  ['flushInterval', 'FLUSH_INTERVAL', 10],
-  ['maxQueueSize', 'MAX_QUEUE_SIZE', 100],
   ['asyncHooks', 'ASYNC_HOOKS', true],
   ['sourceLinesErrorAppFrames', 'SOURCE_LINES_ERROR_APP_FRAMES', 5],
   ['sourceLinesErrorLibraryFrames', 'SOURCE_LINES_ERROR_LIBRARY_FRAMES', 5],
@@ -160,7 +158,6 @@ truthyValues.forEach(function (val) {
 })
 
 var MINUS_ONE_EQUAL_INFINITY = [
-  'maxQueueSize',
   'transactionMaxSpans'
 ]
 

test/instrumentation/modules/http2.js

@@ -2,8 +2,7 @@
 
 var agent = require('../../..').start({
   serviceName: 'test',
-  captureExceptions: false,
-  maxQueueSize: 0
+  captureExceptions: false
 })
 var ins = agent._instrumentation