felixbarny
commented
4 years ago 2.Expose the config metadata of each agent via .yaml file
Agents should generate or hard-code a JSON definition of which options are supported.
The schema would be like this:
[
{
"key": "the configuration key, without the elastic_apm prefix. For example `active`.",
"type": "String|URL|Boolean|Double|Integer|List|Enum|TimeDuration|ByteValue",
"enum": ["a list of values allowed for this option, for example", "TRACE", "DEBUG", "INFO", "WARN", "ERROR"],
"category": "A string describing which category this option belongs to, allows the UI to group options. For example Core, Reporter, Stacktrace, Logging, HTTP, Messaging",
"default": "The default value of this option as a string",
"tags": ["An optional array of tags for this option. For example:", "performance", "security"],
"since": "The version of the agent when this option was introduced. For example 1.2.3",
"description": "A text describing the semantics of this option",
"validation": {
"min": "the min value for options such as transaction_sampling_rate or profiling_sampling_interval (inclusive). May be numerical or a string, for example for time durations like. Examples: `0`, `\"1ms\"`"
"max": "the max value (inclusive)"
"negativeMatch": false, // when set to true, the option must not be within the range (optional, default false)
"regex": "a regex pattern the option has to validate against"
}
},
...
]When the agents send up this information on startup the UI can be rendered generically, based on the options each agent supports. As the UI doesn't hard-code the options, it can display new ones without having to update Kibana.
Open questions
- Should we encode which type lists are in? For example
List<URL>,URL[], orList<WildcarMatcher>? Due to type erasure, that would currently be quite tricky in the Java agent. If there are no type arguments, the UI could fall back toList<String>so we could add it later as well. - Do we need the default value? Might be useful for documentation purposes.
- Should we also send non-dynamic parameters so that Kibana is a one-stop-shop for configuration documentation?
Generated options from the Java agent
Click to expand
``` [ { "key": "active", "type": "Boolean", "category": "Core", "default": "true", "since": "1.0.0", "description": "A boolean specifying if the agent should be active or not.\nWhen active, the agent instruments incoming HTTP requests, tracks errors and collects and sends metrics.\nWhen inactive, the agent works as a noop, not collecting data and not communicating with the APM sever.\nAs this is a reversible switch, agent threads are not being killed when inactivated, but they will be \nmostly idle in this state, so the overhead should be negligible.\n\nYou can use this setting to dynamically disable Elastic APM at runtime." }, { "key": "transaction_sample_rate", "type": "Double", "category": "Core", "default": "1.0", "tags": ["performance"], "since": "1.0.0", "validation": { "min": 0, "max": 1, "negativeMatch": false }, "description": "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, labels, or spans." }, { "key": "transaction_max_spans", "type": "Integer", "category": "Core", "default": "500", "tags": ["performance"], "since": "1.0.0", "description": "Limits the amount of spans that are recorded per transaction.\n\nThis is helpful in cases where a transaction creates a very high amount of spans (e.g. thousands of SQL queries).\n\nSetting an upper limit will prevent overloading the agent and the APM server with too much work for such edge cases.\n\nA message will be logged when the max number of spans has been exceeded but only at a rate of once every 5 minutes to ensure performance is not impacted." }, { "key": "sanitize_field_names", "type": "List", "category": "Core", "default": "password,passwd,pwd,secret,*key,*token*,*session*,*credit*,*card*,authorization,set-cookie", "tags": ["security"], "since": "1.0.0", "description": "Sometimes it is necessary to sanitize the data sent to Elastic APM,\ne.g. remove sensitive data.\n\nConfigure a list of wildcard patterns of field names which should be sanitized.\nThese apply for example to HTTP headers and `application/x-www-form-urlencoded` data.\n\nThis option supports the wildcard `*`, which matches zero or more characters.\nExamples: `/foo/*/bar/*/baz*`, `*foo*`.\nMatching is case insensitive by default.\nPrepending an element with `(?-i)` makes the matching case sensitive.\n\nNOTE: Data in the query string is considered non-sensitive,\nas sensitive information should not be sent in the query string.\nSee https://www.owasp.org/index.php/Information_exposure_through_query_strings_in_url for more information\n\nNOTE: Review the data captured by Elastic APM carefully to make sure it does not capture sensitive information.\nIf you do find sensitive data in the Elasticsearch index,\nyou should add an additional entry to this list (make sure to also include the default entries)." }, { "key": "unnest_exceptions", "type": "List", "category": "Core", "default": "(?-i)*Nested*Exception", "since": "1.0.0", "description": "When reporting exceptions,\nun-nests the exceptions matching the wildcard pattern.\nThis can come in handy for Spring's `org.springframework.web.util.NestedServletException`,\nfor example.\n\nThis option supports the wildcard `*`, which matches zero or more characters.\nExamples: `/foo/*/bar/*/baz*`, `*foo*`.\nMatching is case insensitive by default.\nPrepending an element with `(?-i)` makes the matching case sensitive." }, { "key": "ignore_exceptions", "type": "List", "category": "Core", "default": "", "tags": [], "since": "1.11.0", "description": "A list of exceptions that should be ignored and not reported as errors.\nThis allows to ignore exceptions thrown in regular control flow that are not actual errors\n\nThis option supports the wildcard `*`, which matches zero or more characters.\nExamples: `/foo/*/bar/*/baz*`, `*foo*`.\nMatching is case insensitive by default.\nPrepending an element with `(?-i)` makes the matching case sensitive.\n\nExamples:\n\n - `com.mycompany.ExceptionToIgnore`: using fully qualified name\n - `*ExceptionToIgnore`: using wildcard to avoid package name\n - `*exceptiontoignore`: case-insensitive by default\n\nNOTE: Exception inheritance is not supported, thus you have to explicitly list all the thrown exception types" }, { "key": "capture_body", "type": "Enum", "category": "Core", "default": "OFF", "tags": ["performance"], "enum": ["OFF", "ERRORS", "TRANSACTIONS", "ALL"], "since": "1.0.0", "description": "For transactions that are HTTP requests, the Java agent can optionally capture the request body (e.g. POST \nvariables). For transactions that are initiated by receiving a JMS text message, the agent can capture the \ntextual message body.\n\nIf the HTTP request or the JMS message has a body and this setting is disabled, the body will be shown as [REDACTED].\n\nThis option is case-insensitive.\n\nNOTE: Currently, only UTF-8 encoded plain text HTTP content types are supported.\nThe option <@elastic/apm-agent-devs WDYT? Anything missing from here? @dgieselaar is this a definition of config options something you can work with? I guess all options would be indexed as individual documents and extended with the usual metadata (like ephemeral id and agent name).
To get a list of applicable options, you can do this:
- terms aggregation on ephemeral IDs of currently active agents (for example, query for metric documents within the last hour)
- terms aggregation on
key - not quite sure about the logic of which description to use
beniwohli
jalvz
hmdhk
graphaelli
dgieselaar
sorenlouv
mikker
estolfo
SergeyKleyman
formgeist
basepi
axw
Description of the issue
Till version 7.6 , we have exposed 3 agents config options, CAPTURE_BODY, IGNORE_URLS & TRANSACTION_MAX_SPANS see here. From UI Impl perspective, those options were static in the UI and adding each new config requires UI dev.
We would like to move for the next phase and expose most of the config options from APM UI. here is the list of configuration options which we plan to support ( a unified cross agent list).
################################ there are few phases to this issue : 1.Align config options in agents - we still have few gaps between the agent as can be seen here. 2.Expose the config metadata of each agent via .yaml file 3.Send the the file to an end point 4.Consume & build the UI based on the file.