doc: add performance tuning doc

Author: Stephen Belanger

docs/performance.asciidoc

@@ -0,0 +1,75 @@
+[[performance]]
+
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/performance.html[elastic.co]
+endif::[]
+
+== Performance Tuning
+
+There are four major categories to consider when tuning agent performance: cpu time, memory, storage, and bandwidth. Each setting will impact one or many of these categories.
+
+[float]
+[[performance-sampling]]
+=== Sampling
+
+The first knob to reach for when tuning the performance of the agent is `transactionSampleRate`.
+Adjusting the sampling rate controls what percent of requests are traced.
+By default, the sample rate is set at `1.0`, meaning _all_ requests are traced.
+
+The sample rate will impact all four performance categories, so simply turning down the sample rate is an easy way to improve performance.
+
+[source,js]
+----
+var apm = require('elastic-apm-node').start({
+  transactionSampleRate: 0.2
+})
+----
+
+[float]
+[[performance-stack-traces]]
+=== Stack Traces
+
+Stack traces can be a significant contributor to memory usage, so there are several settings to adjust how they are used.
+
+==== Span Stack Traces
+
+In a complex application, a request may produce many spans, so capturing a stack trace for every span can result in significant memory usage.
+To disable capturing stack traces for spans, set `captureSpanStackTraces` to `false`.
+
+This will mainly impact memory usage, but may also have a noticeable impact on speed too.
+The cpu time required to capture and convert a stack frame to something JavaScript can understand is not insignificant.
+
+==== Stack Frame Limit
+
+The `stackTraceLimit` controls how many stack frames should be captured when producing an `Error` instance of any kind.
+
+This will mainly impact memory usage, but may also have a noticeable impact on speed too.
+The cpu time required to capture and convert a stack frame to something JavaScript can understand is not insignificant.
+
+==== Error Log Stack Traces
+
+Most stack traces recorded by the agent will point to where the error was instantiated, not where it was identified and reported to the agent with <<apm-capture-error,`captureError`>>.
+For this reason, the agent also has a feature to enable capturing an additional stack trace pointing to the place an error was reported to the agent.
+By default, it will only capture the stack trace to the reporting point when <<apm-capture-error,`captureError`>> is called with a string message.
+
+==== Unhandled Exceptions
+
+By default, the agent will record any unhandled exceptions that occur within the application. 
+
+[float]
+[[performance-source-lines]]
+=== Source Lines
+
+The most important settings to look at are the source line settings.
+When a stack trace is captured, the agent will also capture several lines of source code around each stack frame location in the stack trace.
+The are four different settings to control this behaviour: `sourceLinesErrorAppFrames`, `sourceLinesErrorLibraryFrames`, `sourceLinesSpanAppFrames`, and `sourceLinesSpanLibraryFrames`.
+
+Source line settings are divided into app frames representing your app code and library frames representing the code of your dependencies.
+App and library categories are both split into error and span groups.
+Spans, by default, do not capture source lines.
+Errors will, by default, capture five lines of code around each stack frame.
+
+Source lines are cached in-process.
+If your app produces many errors from many different places the source line cache may be larger than desired, in memory-constrained environments.
+You can try turning down the number of error source lines, if your memory usage is higher than you think it should be.