diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index bcf08c757b..203744e27d 100644 --- a/docs/agent-api.asciidoc +++ b/docs/agent-api.asciidoc @@ -535,41 +535,46 @@ Specify the maximum number of spans to capture within a request transaction before dropping further spans. Setting to `Infinity` 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 <> 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 ajusted 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 <> config option. ==== [[server-timeout]] @@ -579,22 +584,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 <> 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` @@ -1150,11 +1144,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 <> and/or <> 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 <> and <> 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)` diff --git a/docs/performance-tuning.asciidoc b/docs/performance-tuning.asciidoc index 7556e72776..4d6a05f487 100644 --- a/docs/performance-tuning.asciidoc +++ b/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 <> or when it reaches <> - -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 <> 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 <> 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 <> 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 <> 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 <> 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 <> 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]] diff --git a/lib/config.js b/lib/config.js index 7b9d91a414..3765ee4407 100644 --- a/lib/config.js +++ b/lib/config.js @@ -44,10 +44,8 @@ var DEFAULTS = { sourceLinesSpanAppFrames: 0, sourceLinesSpanLibraryFrames: 0, errorMessageMaxLength: 2048, - flushInterval: 10, // TODO: Deprecate transactionMaxSpans: Infinity, transactionSampleRate: 1.0, - maxQueueSize: 100, // TODO: Deprecate serverTimeout: 30, disableInstrumentations: [] } @@ -74,8 +72,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', diff --git a/test/instrumentation/modules/http2.js b/test/instrumentation/modules/http2.js index 420d5f47c9..2f7592548b 100644 --- a/test/instrumentation/modules/http2.js +++ b/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