› › ›

基于提示注释的自动发现

基于提示注释的自动发现编辑

此功能处于测试阶段，可能会发生变化。设计和代码不如正式的 GA 功能成熟，并且按原样提供，不提供任何保证。测试版功能不属于正式 GA 功能的支持 SLA 的范围。

确保您使用的是 Elastic Agent 8.5+。

提示自动发现仅适用于独立 Elastic Agent。

独立 Elastic Agent 支持基于提供程序的提示进行自动发现。提示机制会在 Kubernetes Pod 注释中查找以 co.elastic.hints 为前缀的提示。容器启动后，Elastic Agent 会立即检查其中的提示，并为容器启动正确的配置。提示会告诉 Elastic Agent 如何使用正确的集成来监控容器。以下是受支持提示的完整列表

必需的提示：编辑

`co.elastic.hints/package`编辑

用于监控的软件包。

可用的可选提示：编辑

`co.elastic.hints/host`编辑

用于检索指标的主机。如果未定义，则主机将设置为默认主机：<pod-ip>:<container-port>。

`co.elastic.hints/data_stream`编辑

要启用的数据流列表。如果未指定，则使用集成的默认数据流。要查找默认值，请参阅 Elastic 集成文档。

如果指定了数据流，则可以为每个数据流定义其他提示。例如，如果为 Redis 模块指定的数据流为 info，则为 co.elastic.hints/info.period: 5m。

apiVersion: v1
kind: Pod
metadata:
  name: redis
  annotations:
    co.elastic.hints/package: redis
    co.elastic.hints/data_streams: info
    co.elastic.hints/info.period: 5m

如果未指定数据流提示，则将在其配置中使用顶级提示。

`co.elastic.hints/metrics_path`编辑

从中检索指标的路径。

`co.elastic.hints/period`编辑

指标检索的时间间隔，例如 10 秒。

`co.elastic.hints/timeout`编辑

指标检索超时，例如 3 秒。

`co.elastic.hints/username`编辑

用于身份验证的用户名。

`co.elastic.hints/password`编辑

用于身份验证的密码。建议从 ENV 变量中检索此敏感信息，并避免以明文形式放置密码。

`co.elastic.hints/stream`编辑

用于日志收集的流，例如 stdout/stderr。

如果指定的软件包不支持日志，则将使用通用容器的日志输入作为回退。请参阅下面的 用于 Kubernetes 日志收集的提示自动发现 示例。

`co.elastic.hints/processors`编辑

定义要添加到输入配置的处理器。有关受支持处理器的列表，请参阅 定义处理器。

如果处理器配置使用列表数据结构，则必须枚举对象字段。例如，以下重命名处理器配置的提示

processors:
  - rename:
      fields:
        - from: "a.g"
          to: "e.d"
      fail_on_error: true

将如下所示

co.elastic.hints/processors.rename.fields.0.from: "a.g"
co.elastic.hints/processors.rename.fields.1.to: "e.d"
co.elastic.hints/processors.rename.fail_on_error: 'true'

如果处理器配置使用映射数据结构，则不需要枚举。例如，等效于以下 add_fields 配置

processors:
  - add_fields:
      target: project
      fields:
        name: myproject

是

co.elastic.hints/processors.1.add_fields.target: "project"
co.elastic.hints/processors.1.add_fields.fields.name: "myproject"

为了提供处理器定义的顺序，可以提供数字。如果没有，提示构建器将进行任意排序

co.elastic.hints/processors.1.dissect.tokenizer: "%{key1} %{key2}"
co.elastic.hints/processors.dissect.tokenizer: "%{key2} %{key1}"

在上面的示例中，标记为 1 的处理器定义将首先执行。

数据流级别不支持处理器配置，因此 co.elastic.hints/<datastream>.processors 等注释将被忽略。

多个容器编辑

当一个 Pod 有多个容器时，除非您将容器名称放在提示中，否则设置将共享。例如，这些提示为 Pod 中的所有容器配置 processors.decode_json_fields，但为名为 sidecar 的容器设置了特定的 stream 提示。

annotations:
  co.elastic.hints/processors.decode_json_fields.fields: "message"
	co.elastic.hints/processors.decode_json_fields.add_error_key: true
	co.elastic.hints/processors.decode_json_fields.overwrite_keys: true
	co.elastic.hints/processors.decode_json_fields.target: "team"
	co.elastic.hints.sidecar/stream: "stderr"

支持提示自动发现的可用软件包编辑

可以通过提示支持的可用软件包可以在此处找到。

配置提示自动发现编辑

要启用提示自动发现，您必须在提供程序的配置中添加 hints.enabled: true

providers:
  kubernetes:
    hints.enabled: true

然后，通过取消注释 Elastic Agent 清单中的相应部分，确保指定了正确的卷和 volumeMounts

volumeMounts:
- name: external-inputs
  mountPath: /etc/elastic-agent/inputs.d
...
volumes:
- name: external-inputs
  emptyDir: {}
...

还需要一个 init 容器来下载提示模板。init 容器已定义，因此请取消注释相应的部分

initContainers:
- name: k8s-templates-downloader
  image: busybox:1.28
  command: ['sh']
  args:
    - -c
    - >-
      mkdir -p /etc/elastic-agent/inputs.d &&
      wget -O - https://github.com/elastic/elastic-agent/archive/8.14.tar.gz | tar xz -C /etc/elastic-agent/inputs.d --strip=5 "elastic-agent-8.14/deploy/kubernetes/elastic-agent-standalone/templates.d"
  volumeMounts:
    - name: external-inputs
      mountPath: /etc/elastic-agent/inputs.d

Elastic Agent 可以从 {path.config}/inputs.d 加载多个配置文件，并最终生成一个统一的配置文件（请参阅 配置独立 Elastic Agent）。用户可以手动将自己的模板挂载到 /etc/elastic-agent/inputs.d 下 （如果他们想跳过启用 initContainers 部分）。

示例：编辑

用于 Redis 的提示自动发现编辑

启用提示允许在集群上部署 Pod 的用户在 Pod 部署时自动启用 Elastic 监控。例如，要在集群上部署 Redis Pod 并自动启用 Elastic 监控，请将正确的提示作为注释添加到 Pod 清单文件中

...
apiVersion: v1
kind: Pod
metadata:
  name: redis
  annotations:
    co.elastic.hints/package: redis
    co.elastic.hints/data_streams: info
    co.elastic.hints/host: '${kubernetes.pod.ip}:6379'
    co.elastic.hints/info.period: 5s
  labels:
    k8s-app: redis
    app: redis
...

部署此 Pod 后，数据将自动开始流入。您可以在 metrics-redis.info-default 索引中找到它。

与 Redis 集成相关的所有资产（仪表板、摄取管道等）均未安装。您需要明确地通过 Kibana 安装它们。

用于 Kubernetes 日志收集的提示自动发现编辑

可以使用 container_logs.yml 模板支持 Kubernetes 自动发现 Pod 的日志收集。Elastic Agent 需要发出 container_logs 映射，以便开始收集所有已发现容器的日志 （即使容器中不存在注释）。

按照上述步骤启用提示自动发现
确保相关的 container_logs.yml 模板将挂载到 Elastic Agent 的 /etc/elastic-agent/inputs.d/ 文件夹下
部署 Elastic Agent 清单
Elastic Agent 应该能够发现 Kubernetes 集群内的所有容器并收集可用的日志。

可以使用 hints.default_container_logs: false 禁用以前的默认行为。因此，这将禁用从所有已发现 Pod 中自动收集日志。用户需要使用以下注释专门注释他们的 Pod

annotations:
  co.elastic.hints/package: "container_logs"

providers.kubernetes:
  node: ${NODE_NAME}
  scope: node
  hints:
    enabled: true
    default_container_logs: false
...

在以下 nginx 清单示例中，我们将另外提供特定的流注释，以便将 filestream 输入配置为仅读取 stderr 流

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: nginx
  name: nginx
  namespace: default
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:
        co.elastic.hints/package: "container_logs"
        co.elastic.hints/stream: "stderr"
    spec:
      containers:
      - image: nginx
        name: nginx
...

用户可以监控最终呈现的 Elastic Agent 配置

kubectl exec -ti -n kube-system elastic-agent-7fkzm -- bash


/usr/share/elastic-agent# /elastic-agent inspect -v --variables --variables-wait 2s

inputs:
- data_stream.namespace: default
  id: hints-container-logs-3f69573a1af05c475857c1d0f98fc55aa01b5650f146d61e9653a966cd50bd9c-kubernetes-1780aca0-3741-4c8c-aced-b9776ba3fa81.nginx
  name: filestream-generic
  original_id: hints-container-logs-3f69573a1af05c475857c1d0f98fc55aa01b5650f146d61e9653a966cd50bd9c
  [output truncated ....]
  streams:
  - data_stream:
      dataset: kubernetes.container_logs
      type: logs
    exclude_files: []
    exclude_lines: []
    parsers:
    - container:
        format: auto
        stream: stderr
    paths:
    - /var/log/containers/*3f69573a1af05c475857c1d0f98fc55aa01b5650f146d61e9653a966cd50bd9c.log
    prospector:
      scanner:
        symlinks: true
    tags: []
  type: filestream
  use_output: default
outputs:
  default:
    hosts:
    - https://elasticsearch:9200
    password: changeme
    type: elasticsearch
    username: elastic
providers:
  kubernetes:
    hints:
      default_container_logs: false
      enabled: true
    node: control-plane
    scope: node

用于 Kubernetes 日志的提示自动发现（带 JSON 解码）编辑

根据前面的示例，用户可能希望对特定日志执行额外的处理，例如解码包含 JSON 字符串的特定字段。建议使用 decode_json_fields，如下所示

您需要启用提示自动发现，如前面的 用于 Kubernetes 日志收集的提示自动发现 示例中所述。

需要使用以下内容对将生成 JSON 日志的 Pod 进行注释

 annotations:
        co.elastic.hints/package: "container_logs"
        co.elastic.hints/processors.decode_json_fields.fields: "message"
        co.elastic.hints/processors.decode_json_fields.add_error_key: 'true'
        co.elastic.hints/processors.decode_json_fields.overwrite_keys: 'true'
        co.elastic.hints/processors.decode_json_fields.target: "team"

decode_json_fields 处理器的这些参数只是一个示例。

以下日志条目

{"myteam": "ole"}

将生成两个字段：原始 message 字段和目标字段 team。

"team": {
      "myteam": "ole"
    },

"message": "{\"myteam\": \"ole\"}",

故障排除编辑

当事情没有按预期工作时，您可能需要对设置进行故障排除。在这里，我们提供了一些方向来加快您的调查速度

在代理的 Pod 中执行并运行 inspect 命令以验证如何动态构建输入
```
./elastic-agent inspect --variables --variables-wait 1s -c /etc/elastic-agent/agent.yml
```
具体来说，检查输入是如何填充的。
查看 Elastic Agent 日志
```
tail -f /etc/elastic-agent/data/logs/elastic-agent-*.ndjson
```
验证配置文件中是否启用了提示功能，并查找与提示相关的日志，例如：“生成的提示映射为...”。在这些日志中，您可以找到从注释中提取的映射，并确定这些值是否可以填充特定的输入。

查看 Metricbeat 日志

tail -f /etc/elastic-agent/data/logs/default/metricbeat-*.ndjson

查看 Filebeat 日志

tail -f /etc/elastic-agent/data/logs/default/filebeat-*.ndjson

查看目标输入模板。以 Redis 为例

cat f /etc/elastic-agent/inputs.d/redis.yml

« 基于条件的自动发现为独立 Elastic Agent 配置监控 »

基于提示注释的自动发现