[[configuration]]
== Configuration

To adapt the Elastic APM Go agent to your needs, you can configure it using
one of the following three methods, in descending order of precedence:

 1. {apm-app-ref}/agent-configuration.html[APM Agent Configuration via Kibana]
 (supported options are marked with <<dynamic-configuration, image:./images/dynamic-config.svg[] >>)
 2. In code, using the <<tracer-config-api, Tracer Config API>>
 3. Environment variables

Configuration defined via Kibana will take precedence over the same
configuration defined in code, which takes precedence over environment
variables. If configuration is defined via Kibana, and then that is
later removed, the agent will revert to configuration defined locally
via either the Tracer Config API or environment variables.

// tag::setup-config[]
To simplify development and testing,
the agent defaults to sending data to the Elastic APM Server at `http://localhost:8200`.
To send data to an alternative location, you must configure
<<config-server-url, ELASTIC_APM_SERVER_URL>>. Depending on the configuration
of your server, you may also need to set <<config-api-key, ELASTIC_APM_API_KEY>>,
<<config-secret-token, ELASTIC_APM_SECRET_TOKEN>>, and
<<config-verify-server-cert, ELASTIC_APM_VERIFY_SERVER_CERT>>. All other variables
have usable defaults.
// end::setup-config[]

[float]
[[dynamic-configuration]]
=== Dynamic configuration

Configuration options marked with the image:./images/dynamic-config.svg[] badge can be changed at runtime
when set from a supported source.

The Go Agent supports {apm-app-ref}/agent-configuration.html[Central configuration],
which allows you to fine-tune certain configurations via the APM app.
This feature is enabled in the Agent by default, with <<config-central-config>>.

[float]
=== Configuration formats

Some options require a unit, either duration or size. These need to be provided
in a specific format.

[float]
==== Duration format

The _duration_ format is used for options like timeouts. The unit is provided as
a suffix directly after the number, without any whitespace.

*Example:* `5ms`

*Supported units:*

- `ms` (milliseconds)
- `s` (seconds)
- `m` (minutes)

[float]
==== Size format

The _size_ format is used for options such as maximum buffer sizes. The unit is
provided as a suffix directly after the number, without any whitespace.

*Example:* `10KB`

*Supported units:*

- B (bytes)
- KB (kilobytes)
- MB (megabytes)
- GB (gigabytes)

NOTE: We use the power-of-two sizing convention, e.g. 1KB = 1024B.

[float]
[[config-server-url]]
=== `ELASTIC_APM_SERVER_URL`

[options="header"]
|============
| Environment              | Default                 | Example
| `ELASTIC_APM_SERVER_URL` | `http://localhost:8200` | `http://localhost:8200`
|============

The URL for your Elastic APM server. The server supports both HTTP and HTTPS.
If you use HTTPS, then you may need to configure your client machines so
that the server certificate can be verified. You can also disable certificate
verification with <<config-verify-server-cert>>.

[float]
[[config-server-timeout]]
=== `ELASTIC_APM_SERVER_TIMEOUT`

[options="header"]
|============
| Environment                  | Default | Example
| `ELASTIC_APM_SERVER_TIMEOUT` | `30s`   | `30s`
|============

The timeout for requests made to your Elastic APM server. When set to zero
or a negative value, timeouts will be disabled.

[float]
[[config-secret-token]]
=== `ELASTIC_APM_SECRET_TOKEN`

[options="header"]
|============
| Environment                | Default | Example
| `ELASTIC_APM_SECRET_TOKEN` |         | "A random string"
|============

This string is used to ensure that only your agents can send data to your APM server.
Both the agents and the APM server have to be configured with the same secret token.

WARNING: the secret token is sent as plain-text in every request to the server, so you
should also secure your communications using HTTPS. Unless you do so, your secret token
could be observed by an attacker.

[float]
[[config-api-key]]
==== `ELASTIC_APM_API_KEY`

[options="header"]
|============
| Environment           | Default | Example
| `ELASTIC_APM_API_KEY` |         | "A base64-encoded string"
|============

This base64-encoded string is used to ensure that only your agents can send data to your APM server.
You must have created the API key using the APM server command line tool. Please see the APM server
documentation for details on how to do that.

NOTE: This feature is fully supported in the APM Server versions >= 7.6.

WARNING: the API Key is sent as plain-text in every request to the server, so you should also secure
your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker.

[float]
[[config-service-name]]
=== `ELASTIC_APM_SERVICE_NAME`

[options="header"]
|============
| Environment                | Default         | Example
| `ELASTIC_APM_SERVICE_NAME` | Executable name | `my-app`
|============

The name of your service/application.  This is used to keep all the errors and
transactions of your service together and is the primary filter in the Elastic APM
user interface.

If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the
executable name. e.g. if your executable is called "my-app.exe", then your
service will be identified as "my-app".

NOTE: The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`.
In other words: your service name must only contain characters from the ASCII
alphabet, numbers, dashes, underscores and spaces.

[float]
[[config-service-version]]
=== `ELASTIC_APM_SERVICE_VERSION`

[options="header"]
|============
| Environment                    | Default | Example
| `ELASTIC_APM_SERVICE_VERSION`  |         | A string indicating the version of the deployed service
|============

A version string for the currently deployed version of the service.
If you don't version your deployments, the recommended value for this field is the commit identifier
of the deployed revision, e.g. the output of `git rev-parse HEAD`.

[float]
[[config-service-node-name]]
=== `ELASTIC_APM_SERVICE_NODE_NAME`

[options="header"]
|============
| Environment                     | Default | Example
| `ELASTIC_APM_SERVICE_NODE_NAME` |         | `my-node-name`
|============

Optional name used to differentiate between nodes in a service.
Must be unique, otherwise data from multiple nodes will be aggregated together.

If you do not specify `ELASTIC_APM_SERVICE_NODE_NAME`, service nodes will be identified using the container ID if available,
otherwise the host name.

NOTE: This feature is fully supported in the APM Server versions >= 7.5.

[float]
[[config-environment]]
=== `ELASTIC_APM_ENVIRONMENT`

[options="header"]
|============
| Environment               | Default | Example
| `ELASTIC_APM_ENVIRONMENT` |         | `"production"`
|============

The name of the environment this service is deployed in, e.g. "production" or "staging".

Environments allow you to easily filter data on a global level in the APM app.
It's important to be consistent when naming environments across agents.
See {apm-app-ref}/filters.html#environment-selector[environment selector] in the APM app for more information.

NOTE: This feature is fully supported in the APM app in Kibana versions >= 7.2.
You must use the query bar to filter for a specific environment in versions prior to 7.2.

[float]
[[config-active]]
=== `ELASTIC_APM_ACTIVE`

[options="header"]
|============
| Environment          | Default | Example
| `ELASTIC_APM_ACTIVE` | true    | `false`
|============

Enable or disable the agent. If set to false, then the Go agent does not send
any data to the Elastic APM server, and instrumentation overhead is minimized.

[float]
[[config-recording]]
=== `ELASTIC_APM_RECORDING`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment             | Default | Example
| `ELASTIC_APM_RECORDING` | true    | `false`
|============

Enable or disable recording of events. If set to false, then the Go agent does
send any events to the Elastic APM server, and instrumentation overhead is
minimized, but the agent will continue to poll the server for configuration changes.

[float]
[[config-global-labels]]
=== `ELASTIC_APM_GLOBAL_LABELS`

[options="header"]
|============
| Environment                 | Default | Example
| `ELASTIC_APM_GLOBAL_LABELS` |         | `dept=engineering,rack=number8`
|============

Labels added to all events, with the format key=value[,key=value[,...]].
Any labels set by application via the API will override global labels with the same keys.

This option requires APM Server 7.2 or greater, and will have no effect when using older
server versions.

[float]
[[config-ignore-urls]]
=== `ELASTIC_APM_TRANSACTION_IGNORE_URLS`

[options="header"]
|============
| Environment                           | Default | Example
| `ELASTIC_APM_TRANSACTION_IGNORE_URLS` |         | `/heartbeat*, *.jpg`
|============

A list of patterns to match HTTP requests to ignore. An incoming HTTP request
whose request line matches any of the patterns will not be reported as a transaction.

This option supports the wildcard `*`, which matches zero or more characters.
Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default.
Prefixing a pattern with `(?-i)` makes the matching case sensitive.

NOTE: this configuration was previously known as `ELASTIC_APM_IGNORE_URLS`, which has been deprecated and will be removed in a future major
version of the agent.

[float]
[[config-sanitize-field-names]]
=== `ELASTIC_APM_SANITIZE_FIELD_NAMES`

[options="header"]
|============
| Environment                        | Default                                                                                                | Example
| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `password, passwd, pwd, secret, *key, *token*, *session*, *credit*, *card*, authorization, set-cookie` | `sekrits`
|============

A list of patterns to match the names of HTTP headers, cookies, and POST form fields to redact.

This option supports the wildcard `*`, which matches zero or more characters.
Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default.
Prefixing a pattern with `(?-i)` makes the matching case sensitive.

[float]
[[config-capture-headers]]
=== `ELASTIC_APM_CAPTURE_HEADERS`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                   | Default
| `ELASTIC_APM_CAPTURE_HEADERS` | `true`
|============

For transactions that are HTTP requests, the Go agent can optionally capture request and response headers.

Possible values: `true`, `false`.

Captured headers are subject to sanitization, per <<config-sanitize-field-names>>.

[float]
[[config-capture-body]]
=== `ELASTIC_APM_CAPTURE_BODY`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                | Default
| `ELASTIC_APM_CAPTURE_BODY` | `off`
|============

For transactions that are HTTP requests, the Go agent can optionally capture the request body.

Possible values: `errors`, `transactions`, `all`, `off`.

WARNING: request bodies often contain sensitive values like passwords, credit card numbers, etc.
If your service handles data like this, enable this feature with care.

[float]
[[config-hostname]]
=== `ELASTIC_APM_HOSTNAME`

[options="header"]
[options="header"]
|============
| Environment                | Default         | Example
| `ELASTIC_APM_HOSTNAME`     | `os.Hostname()` | `app-server01`
|============

The host name to use when sending error and transaction data to the APM server.

[float]
[[config-api-request-time]]
=== `ELASTIC_APM_API_REQUEST_TIME`

[options="header"]
|============
| Environment                    | Default
| `ELASTIC_APM_API_REQUEST_TIME` | `10s`
|============

Amount of time to wait before ending a request to the Elastic APM server.
When you report transactions, spans and errors, the agent will initiate a
request and send them to the server when there is enough data to send; the
request will remain open until this time has been exceeded, or until the
<<config-api-request-size, maximum request size>> has been reached.

[float]
[[config-api-request-size]]
=== `ELASTIC_APM_API_REQUEST_SIZE`

[options="header"]
|============
| Environment                    | Default | Minimum | Maximum
| `ELASTIC_APM_API_REQUEST_SIZE` | `750KB` | `1KB`   | `5MB`
|============

The maximum size of request bodies to send to the Elastic APM server.
The agent will maintain an in-memory buffer of compressed data for streaming
to the APM server.

[float]
[[config-api-buffer-size]]
=== `ELASTIC_APM_API_BUFFER_SIZE`

[options="header"]
|============
| Environment                   | Default | Minimum | Maximum
| `ELASTIC_APM_API_BUFFER_SIZE` | `1MB`   | `10KB`  | `100MB`
|============

The maximum number of bytes of uncompressed, encoded events to store in memory
while the agent is busy. When the agent is able to, it will transfer buffered
data to the request buffer, and start streaming it to the server. If the buffer
fills up, new events will start replacing older ones.

[float]
[[config-transaction-max-spans]]
=== `ELASTIC_APM_TRANSACTION_MAX_SPANS`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                         | Default
| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `500`
|============

Limits the amount of spans that are recorded per transaction.

This is helpful in cases where a transaction creates a large number
of spans (e.g. thousands of SQL queries). Setting an upper limit will
prevent overloading the agent and the APM server with too much work
for such edge cases.

[float]
[[config-span-frames-min-duration-ms]]
=== `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                            | Default
| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `5ms`
|============

The APM agent will collect a stack trace for every recorded span whose duration
exceeds this configured value. While this is very helpful to find the exact
place in your code that causes the span, collecting this stack trace does have
some processing and storage overhead.

[float]
[[config-stack-trace-limit]]
=== `ELASTIC_APM_STACK_TRACE_LIMIT`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                     | Default
| `ELASTIC_APM_STACK_TRACE_LIMIT` | `50`
|============

Limits the number of frames captured for each stack trace.

Setting the limit to 0 will disable stack trace collection, while any positive
integer value will be used as the maximum number of frames to collect. Setting
a negative value, such as -1, means that all frames will be collected.

[float]
[[config-transaction-sample-rate]]
=== `ELASTIC_APM_TRANSACTION_SAMPLE_RATE`

<<dynamic-configuration, image:./images/dynamic-config.svg[] >>

[options="header"]
|============
| Environment                           | Default
| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `1.0`
|============

By default, the agent will sample every transaction (e.g. request to your service).
To reduce overhead and storage requirements, you can set the sample rate to a value
between `0.0` and `1.0`. We still record overall time and the result for unsampled
transactions, but no context information, tags, or spans.

[float]
[[config-metrics-interval]]
=== `ELASTIC_APM_METRICS_INTERVAL`

[options="header"]
|============
| Environment                     | Default
| `ELASTIC_APM_METRICS_INTERVAL`  | 30s
|============

The interval at which APM agent gathers and reports metrics. Set to `0s` to disable.

[float]
[[config-disable-metrics]]
=== `ELASTIC_APM_DISABLE_METRICS`

[options="header"]
|============
| Environment                   | Default | Example
| `ELASTIC_APM_DISABLE_METRICS` |         | `system.*, *cpu*`
|============

Disables the collection of certain metrics. If the name of a metric matches any of
the wildcard expressions, it will not be collected.

This option supports the wildcard `*`, which matches zero or more characters.
Examples: `/foo/*/bar/*/baz*`, `*foo*`. Matching is case insensitive by default.
Prefixing a pattern with `(?-i)` makes the matching case sensitive.

[float]
[[config-breakdown-metrics]]
=== `ELASTIC_APM_BREAKDOWN_METRICS`

[options="header"]
|============
| Environment                     | Default
| `ELASTIC_APM_BREAKDOWN_METRICS` | `true`
|============

Capture breakdown metrics. Set to `false` to disable.

[float]
[[config-server-cert]]
=== `ELASTIC_APM_SERVER_CERT`

[options="header"]
|============
| Environment                | Default
| `ELASTIC_APM_SERVER_CERT`  |
|============

If you have configured your APM Server with a self signed TLS certificate, or you
just wish to pin the server certificate, you can specify the path to the PEM-encoded
certificate via the `ELASTIC_APM_SERVER_CERT` configuration.

[float]
[[config-verify-server-cert]]
=== `ELASTIC_APM_VERIFY_SERVER_CERT`

[options="header"]
|============
| Environment                       | Default
| `ELASTIC_APM_VERIFY_SERVER_CERT`  | `true`
|============

By default, the agent verifies the server's certificate if you use an
HTTPS connection to the APM server. Verification can be disabled by
changing this setting to `false`. This setting is ignored when
`ELASTIC_APM_SERVER_CERT` is set.

[float]
[[config-log-file]]
=== `ELASTIC_APM_LOG_FILE`

[options="header"]
|============
| Environment            | Default
| `ELASTIC_APM_LOG_FILE` |
|============

`ELASTIC_APM_LOG_FILE` specifies the output file for the agent's default, internal
logger. The file will be created, or truncated if it exists, when the process starts.
By default, logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable
it. This environment variable will be ignored if a logger is configured programatically.

There are two special file names that the agent recognizes: `stdout` and `stderr`.
These will configure the logger to write to standard output and standard error
respectively.

[float]
[[config-log-level]]
=== `ELASTIC_APM_LOG_LEVEL`

[options="header"]
|============
| Environment             | Default
| `ELASTIC_APM_LOG_LEVEL` | `"error"`
|============

`ELASTIC_APM_LOG_LEVEL` specifies the log level for the agent's default, internal
logger. The only two levels used by the logger are "error" and "debug". By default,
logging is disabled. You must specify `ELASTIC_APM_LOG_FILE` to enable it.

This environment variable will be ignored if a logger is configured programatically.

[float]
[[config-central-config]]
==== `ELASTIC_APM_CENTRAL_CONFIG`

[options="header"]
|============
| Environment                  | Default
| `ELASTIC_APM_CENTRAL_CONFIG` | `true`
|============

Activate APM Agent Configuration via Kibana. By default the agent will poll the server
for agent configuration changes. This can be disabled by changing the setting to `false`.

NOTE: This feature requires APM Server v7.3 or later and that the APM Server is configured with `kibana.enabled: true`.

[float]
[[config-use-elastic-traceparent-header]]
==== `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER`
|============
| Environment                                  | Default
| `ELASTIC_APM_USE_ELASTIC_TRACEPARENT_HEADER` | `true`
|============

To enable {apm-overview-ref-v}/distributed-tracing.html[distributed tracing], the agent
adds trace context headers to outgoing HTTP requests made with <<builtin-modules-apmhttp>>.
These headers (`traceparent` and `tracestate`) are defined in the
https://www.w3.org/TR/trace-context-1/[W3C Trace Context] specification.

When this setting is `true`, the agent will also add the header `elastic-apm-traceparent`
for backwards compatibility with older versions of Elastic APM agents.

[float]
[[config-cloud-provider]]
==== `ELASTIC_APM_CLOUD_PROVIDER`

[options="header"]
|============
| Environment                  | Default  | Example
| `ELASTIC_APM_CLOUD_PROVIDER` | `"none"` | `"aws"`
|============

This config value allows you to specify which cloud provider should be assumed
for metadata collection. By default, the agent will use trial and error to
automatically collect the cloud metadata.

Valid options are `"none"`, `"auto"`, `"aws"`, `"gcp"`, and `"azure"`
If this config value is set to `"none"`, then no cloud metadata will be collected.
