› › ›

基于提示注解的自动发现

此功能处于 Beta 阶段，可能随时更改。其设计和代码不如正式 GA 功能成熟，按“原样”提供，不附带任何担保。Beta 功能不受正式 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.16
  command: ['bash']
  args:
    - -c
    - >-
      mkdir -p /usr/share/elastic-agent/state/inputs.d &&
      curl -sL https://github.com/elastic/elastic-agent/archive/8.16.tar.gz | tar xz -C /usr/share/elastic-agent/state/inputs.d --strip=5 "elastic-agent-8.16/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 日志收集的提示自动发现

编辑

Kubernetes 自动发现 Pod 的日志收集可以通过使用 container_logs.yml 模板来支持。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 清单示例中，我们将另外提供特定的 stream 注解，以便将 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 配置监控 »