Configurationedit

To adapt the Elastic APM Go agent to your needs, you can configure it using environment variables.

By default, the agent will attempt to send data to the Elastic APM Server at http://localhost:8200, to simplify development and testing. To send data to an alternative location, you must configure ELASTIC_APM_SERVER_URL. Depending on the configuration of your server, you may also need to set ELASTIC_APM_SECRET_TOKEN and ELASTIC_APM_VERIFY_SERVER_CERT. All other variables have usable defaults.

Configuration formatsedit

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

Duration formatedit

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)

Size formatedit

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.

ELASTIC_APM_SERVER_URLedit

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 ELASTIC_APM_VERIFY_SERVER_CERTedit.

ELASTIC_APM_SERVER_TIMEOUTedit

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.

ELASTIC_APM_SECRET_TOKENedit

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.

ELASTIC_APM_SERVICE_NAMEedit

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.

ELASTIC_APM_SERVICE_VERSIONedit

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.

ELASTIC_APM_ENVIRONMENTedit

Environment Default Example

ELASTIC_APM_ENVIRONMENT

"production"

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

Warning

the APM UI does not currently group services by environment, so metrics for all environments will be combined. Consider changing the service name if you want to see the metrics separated by environment. Alternatively, you can use the search bar introduced with the 6.4 release.

ELASTIC_APM_ACTIVEedit

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.

ELASTIC_APM_IGNORE_URLSedit

Environment Default Example

ELASTIC_APM_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.

ELASTIC_APM_SANITIZE_FIELD_NAMESedit

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.

ELASTIC_APM_CAPTURE_HEADERSedit

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 ELASTIC_APM_SANITIZE_FIELD_NAMESedit.

ELASTIC_APM_CAPTURE_BODYedit

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.

ELASTIC_APM_HOSTNAMEedit

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.

ELASTIC_APM_API_REQUEST_TIMEedit

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 maximum request size has been reached.

ELASTIC_APM_API_REQUEST_SIZEedit

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.

ELASTIC_APM_API_BUFFER_SIZEedit

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.

ELASTIC_APM_TRANSACTION_MAX_SPANSedit

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.

ELASTIC_APM_SPAN_FRAMES_MIN_DURATIONedit

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.

ELASTIC_APM_TRANSACTION_SAMPLE_RATEedit

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.

ELASTIC_APM_METRICS_INTERVALedit

Environment Default

ELASTIC_APM_METRICS_INTERVAL

30s

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

ELASTIC_APM_SERVER_CERTedit

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.

ELASTIC_APM_VERIFY_SERVER_CERTedit

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.

ELASTIC_APM_LOG_FILEedit

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.

ELASTIC_APM_LOG_LEVELedit

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.