From 6fa9ecef032ec5518f7ddf237e8d6ae5f689e78b Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 4 Nov 2024 10:01:09 -0500 Subject: [PATCH] Update docs version of reference.yml and improve header section (#1416) * Update docs version of reference.yml and improve header section * Update docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.asciidoc (cherry picked from commit f5344bfa233f86a2b395e1ceba5a6c6d91c4c6ea) --- .../elastic-agent-reference-yaml.asciidoc | 5 +- .../yaml/elastic-agent-reference-yaml.yml | 151 ++++++++++++++++-- 2 files changed, 141 insertions(+), 15 deletions(-) diff --git a/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.asciidoc index 77e468a77..0b08d36dd 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.asciidoc @@ -4,7 +4,10 @@ The {agent} installation includes an `elastic-agent.reference.yml` file that describes all the settings available in a standalone configuration. -This file is included here for your convenience. +To ensure that you're accessing the latest version, refer to the original link:https://github.com/elastic/elastic-agent/blob/main/elastic-agent.reference.yml[`elastic-agent.reference.yml` file] in the `elastic/elastic-agent` repository. +A copy is included here for your convenience. + +Each section of the file and available settings are also described in <>. [source,yaml] ---- diff --git a/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.yml b/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.yml index 646a10d19..392146289 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.yml +++ b/docs/en/ingest-management/elastic-agent/configuration/yaml/elastic-agent-reference-yaml.yml @@ -11,30 +11,51 @@ outputs: default: type: elasticsearch hosts: [127.0.0.1:9200] - api-key: "example-key" + api_key: "example-key" # username: "elastic" # password: "changeme" -inputs: - # Each input in a policy must have a unique value for the id key. - - id: unique-system-metrics-id - type: system/metrics + # Performance preset for elasticsearch outputs. One of "balanced", "throughput", + # "scale", "latency" and "custom". + # The default if unspecified is "custom". + preset: balanced +inputs: + - type: system/metrics + # Each input must have a unique ID. + id: unique-system-metrics-input # Namespace name must conform to the naming conventions for Elasticsearch indices, cannot contain dashes (-), and cannot exceed 100 bytes # For index naming restrictions, see https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html#indices-create-api-path-params data_stream.namespace: default use_output: default streams: - - metricset: cpu + - metricsets: + - cpu # Dataset name must conform to the naming conventions for Elasticsearch indices, cannot contain dashes (-), and cannot exceed 100 bytes data_stream.dataset: system.cpu - - metricset: memory + - metricsets: + - memory data_stream.dataset: system.memory - - metricset: network + - metricsets: + - network data_stream.dataset: system.network - - metricset: filesystem + - metricsets: + - filesystem data_stream.dataset: system.filesystem +# # Collecting log files +# - type: filestream +# # Input ID allowing Elastic Agent to track the state of this input. Must be unique. +# id: your-input-id +# streams: +# # Stream ID for this data stream allowing Filebeat to track the state of the ingested files. Must be unique. +# # Each filestream data stream creates a separate instance of the Filebeat filestream input. +# - id: your-filestream-stream-id +# data_stream: +# dataset: generic +# paths: +# - /var/log/*.log + # management: # # Mode of management, the Elastic Agent support two modes of operation: # # @@ -72,12 +93,12 @@ inputs: # target_directory: "${path.data}/downloads" # # timeout for downloading package # timeout: 120s -# # file path to a public key used for verifying downloaded artifacts -# # if not file is present agent will try to load public key from elastic.co website. -# pgpfile: "${path.data}/elastic.pgp" # # install_path describes the location of installed packages/programs. It is also used # # for reading program specifications. # install_path: "${path.data}/install" +# # retry_sleep_init_duration is the duration to sleep for before the first retry attempt. This +# # duration will increase for subsequent retry attempts in a randomized exponential backoff manner. +# retry_sleep_init_duration: 30s # agent.process: # # timeout for creating new processes. when process is not successfully created by this timeout @@ -92,6 +113,9 @@ inputs: # address: localhost # # port for the GRPC server that spawned processes connect back to. # port: 6789 +# # max_message_size limits the message size in agent internal communication +# # default is 100MB +# max_message_size: 104857600 # agent.retry: # # Enabled determines whether retry is possible. Default is false. @@ -108,6 +132,12 @@ inputs: # # Default is false # exponential: false +# agent.limits: +# # limits the number of operating system threads that can execute user-level Go code simultaneously. +# # Translates into the GOMAXPROCS runtime parameter for each Go process started by the agent and the agent itself. +# # By default is set to `0` which means using all available CPUs. +# go_max_procs: 0 + # agent.monitoring: # # enabled turns on monitoring of running processes # enabled: false @@ -115,10 +145,27 @@ inputs: # logs: false # # enables metrics monitoring # metrics: false +# # metrics_period defines how frequent we should sample monitoring metrics. Default is 60 seconds. +# metrics_period: 60s # # exposes /debug/pprof/ endpoints # # recommended that these endpoints are only enabled if the monitoring endpoint is set to localhost # pprof.enabled: false -# # exposes agent metrics using http, by default sockets and named pipes are used +# # The name of the output to use for monitoring data. +# use_output: monitoring +# # Exposes agent metrics using http, by default sockets and named pipes are used. +# # +# # `http` Also exposes a /liveness endpoint that will return an HTTP code depending on agent status: +# # 200: Agent is healthy +# # 500: A component or unit is in a failed state +# # 503: The agent coordinator is unresponsive +# # +# # You can pass a `failon` parameter to the /liveness endpoint to determine what component state will result in a 500. +# # For example: `curl 'localhost:6792/liveness?failon=degraded'` will return 500 if a component is in a degraded state. +# # The possible values for `failon` are: +# # `degraded`: return an error if a component is in a degraded state or failed state, or if the agent coordinator is unresponsive. +# # `failed`: return an error if a unit is in a failed state, or if the agent coordinator is unresponsive. +# # `heartbeat`: return an error only if the agent coordinator is unresponsive. +# # If no `failon` parameter is provided, the default behavior is `failon=heartbeat` # http: # # enables http endpoint # enabled: false @@ -129,6 +176,22 @@ inputs: # port: 6791 # # Metrics buffer endpoint # buffer.enabled: false +# # Configuration for the diagnostics action handler +# diagnostics: +# # Rate limit for the action handler. Does not affect diagnostics collected through the CLI. +# limit: +# # Rate limit interval. +# interval: 1m +# # Rate limit burst. +# burst: 1 +# # Configuration for the file-upload client. Client may retry failed requests with an exponential backoff. +# uploader: +# # Max retries allowed when uploading a chunk. +# max_retries: 10 +# # Initial duration of the backoff. +# init_dur: 1s +# # Max duration of the backoff. +# max_dur: 1m # # Allow fleet to reload its configuration locally on disk. # # Notes: Only specific process configuration and external input configurations will be reloaded. @@ -141,6 +204,13 @@ inputs: # # period define how frequent we should look for changes in the configuration. # period: 10s +# Feature Flags + +# This section enables or disables feature flags supported by Agent and its components. +#agent.features: +# fqdn: +# enabled: false + # Logging # There are four options for the log output: file, stderr, syslog, eventlog @@ -187,7 +257,7 @@ agent.logging.to_stderr: true # Configure log file size limit. If limit is reached, log file will be # automatically rotated - #rotateeverybytes: 10485760 # = 10MB + #rotateeverybytes: 20971520 # = 20MB # Number of rotated log files to keep. Oldest files will be deleted first. #keepfiles: 7 @@ -210,12 +280,65 @@ 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 # and conditionals. Each provider's keys are automatically prefixed with the name # of the provider. +# All registered providers are enabled by default. + +# Disable all providers by default and only enable explicitly configured providers. +# agent.providers.initial_default: false + #providers: # Agent provides information about the running agent.