› › ›

基于提示注解的自动发现

此功能为测试版，可能会发生更改。设计和代码不如正式 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 清单中的相应部分来确保指定了初始化容器。需要一个初始化容器来下载提示模板。

initContainers:
- name: k8s-templates-downloader
  image: docker.elastic.co/elastic-agent/elastic-agent:8.17
  command: ['bash']
  args:
    - -c
    - >-
      mkdir -p /usr/share/elastic-agent/state/inputs.d &&
      curl -sL https://github.com/elastic/elastic-agent/archive/8.17.tar.gz | tar xz -C /usr/share/elastic-agent/state/inputs.d --strip=5 "elastic-agent-8.17/deploy/kubernetes/elastic-agent-standalone/templates.d"
  securityContext:
    runAsUser: 0
  volumeMounts:
    - name: elastic-agent-state
      mountPath: /usr/share/elastic-agent/state

Elastic Agent 可以从 {path.config}/inputs.d 加载多个配置文件，并最终生成一个统一的配置文件（请参阅配置独立的 Elastic Agent）。用户可以将自己的模板手动挂载到 /usr/share/elastic-agent/state/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 的 /usr/share/elastic-agent/state/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

使用 JSON 解码进行 Kubernetes 日志的提示自动发现

编辑

根据之前的示例，用户可能希望对特定日志执行额外的处理，例如解码包含 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\"}",

故障排除

编辑

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

在 Agent 的 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 /usr/share/elastic-agent/state/inputs.d/redis.yml

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