From 3f421c8c1ea2e7865bc2daeb630e6654a59e4d33 Mon Sep 17 00:00:00 2001 From: Tiago Queiroz Date: Thu, 6 Jun 2024 15:03:33 -0400 Subject: [PATCH] Update documentation --- _meta/config/common.reference.p2.yml.tmpl | 48 +++++++++++++++++++++++ docs/elastic-agent-logging.md | 10 +++++ elastic-agent.reference.yml | 48 +++++++++++++++++++++++ 3 files changed, 106 insertions(+) diff --git a/_meta/config/common.reference.p2.yml.tmpl b/_meta/config/common.reference.p2.yml.tmpl index 4c729a57e81..317c1126375 100644 --- a/_meta/config/common.reference.p2.yml.tmpl +++ b/_meta/config/common.reference.p2.yml.tmpl @@ -272,4 +272,52 @@ agent.logging.to_stderr: true # Set to true to log messages in JSON format. #agent.logging.json: false +#=============================== Events Logging =============================== +# Some outputs will log raw events on errors like indexing errors in the +# Elasticsearch output, to prevent logging raw events (that may contain +# sensitive information) together with other log messages, a different +# log file, only for log entries containing raw events, is used. It will +# use the same level, selectors and all other configurations from the +# default logger, but it will have it's own file configuration. +# +# Having a different log file for raw events also prevents event data +# from drowning out the regular log files. +# +# IMPORTANT: No matter the default logger output configuration, raw events +# will **always** be logged to a file configured by `agent.logging.event_data.files`. + +# agent.logging.event_data: +# Logging to rotating files. Set agent.logging.to_files to false to disable logging to +# files. +#agent.logging.event_data.to_files: true +#agent.logging.event_data: + # Configure the path where the logs are written. The default is the logs directory + # under the home path (the binary location). + #path: /var/log/filebeat + + # The name of the files where the logs are written to. + #name: filebeat-event-data + + # Configure log file size limit. If the limit is reached, log file will be + # automatically rotated. + #rotateeverybytes: 5242880 # = 5MB + + # Number of rotated log files to keep. The oldest files will be deleted first. + #keepfiles: 2 + + # The permissions mask to apply when rotating log files. The default value is 0600. + # Must be a valid Unix-style file permissions mask expressed in octal notation. + #permissions: 0600 + + # Enable log file rotation on time intervals in addition to the size-based rotation. + # Intervals must be at least 1s. Values of 1m, 1h, 24h, 7*24h, 30*24h, and 365*24h + # are boundary-aligned with minutes, hours, days, weeks, months, and years as + # reported by the local system clock. All other intervals are calculated from the + # Unix epoch. Defaults to disabled. + #interval: 0 + + # Rotate existing logs on startup rather than appending them to the existing + # file. Defaults to false. + # rotateonstartup: false + {{template "providers.yml.tmpl" .}} diff --git a/docs/elastic-agent-logging.md b/docs/elastic-agent-logging.md index 443c1f8fe84..7cd252cae38 100644 --- a/docs/elastic-agent-logging.md +++ b/docs/elastic-agent-logging.md @@ -44,6 +44,16 @@ configuration is: - ECS/JSON encoded - UTC timestamps +There is also a second file output for events that is configured via +`agent.logging.event_data`. It shares the same log level as the main +logger and can only be configured for standalone agents. For +Fleet-Managed agents it will always use the default values: + - 5Mb per log file + - Maximum of 2 log files + - Do not rotate on startup + - ECS/JSON encoded + - UTC timestamps + ## Default logging The default logger is the easiest to discover because it's user configurable, logs to the Agent's root directory and can output to diff --git a/elastic-agent.reference.yml b/elastic-agent.reference.yml index 66e8bbb0951..7565fe2f76a 100644 --- a/elastic-agent.reference.yml +++ b/elastic-agent.reference.yml @@ -278,6 +278,54 @@ agent.logging.to_stderr: true # Set to true to log messages in JSON format. #agent.logging.json: false +#=============================== Events Logging =============================== +# Some outputs will log raw events on errors like indexing errors in the +# Elasticsearch output, to prevent logging raw events (that may contain +# sensitive information) together with other log messages, a different +# log file, only for log entries containing raw events, is used. It will +# use the same level, selectors and all other configurations from the +# default logger, but it will have it's own file configuration. +# +# Having a different log file for raw events also prevents event data +# from drowning out the regular log files. +# +# IMPORTANT: No matter the default logger output configuration, raw events +# will **always** be logged to a file configured by `agent.logging.event_data.files`. + +# agent.logging.event_data: +# Logging to rotating files. Set agent.logging.to_files to false to disable logging to +# files. +#agent.logging.event_data.to_files: true +#agent.logging.event_data: + # Configure the path where the logs are written. The default is the logs directory + # under the home path (the binary location). + #path: /var/log/filebeat + + # The name of the files where the logs are written to. + #name: filebeat-event-data + + # Configure log file size limit. If the limit is reached, log file will be + # automatically rotated. + #rotateeverybytes: 5242880 # = 5MB + + # Number of rotated log files to keep. The oldest files will be deleted first. + #keepfiles: 2 + + # The permissions mask to apply when rotating log files. The default value is 0600. + # Must be a valid Unix-style file permissions mask expressed in octal notation. + #permissions: 0600 + + # Enable log file rotation on time intervals in addition to the size-based rotation. + # Intervals must be at least 1s. Values of 1m, 1h, 24h, 7*24h, 30*24h, and 365*24h + # are boundary-aligned with minutes, hours, days, weeks, months, and years as + # reported by the local system clock. All other intervals are calculated from the + # Unix epoch. Defaults to disabled. + #interval: 0 + + # Rotate existing logs on startup rather than appending them to the existing + # file. Defaults to false. + # rotateonstartup: false + # Providers # Providers supply the key/values pairs that are used for variable substitution