honeycombio/honeycomb-kubernetes-agent

Honeycomb Kubernetes 可见性镜像文档

镜像概述和主要用途

Honeycomb Kubernetes 可见性镜像（以下简称"Honeycomb镜像"）是Honeycomb提供的官方Docker镜像，专为在Kubernetes环境中实现应用程序可见性设计。该镜像通过收集、处理和发送应用程序及Kubernetes集群的遥测数据（日志、指标、分布式追踪）到Honeycomb可观测性平台，帮助用户实时监控应用性能、诊断问题、理解系统行为，从而提升Kubernetes环境中应用的可靠性和可维护性。

核心功能和特性

• 全面遥测数据收集：支持收集Kubernetes集群中应用程序的日志、指标和分布式追踪数据，提供多维度可观测性
• 深度Kubernetes集成：与Kubernetes生态深度集成，自动发现集群资源（Pod、Service、Namespace），并关联遥测数据与Kubernetes元数据（标签、注解）
• 高效数据转发：优化的数据传输机制，确保遥测数据安全可靠地发送至Honeycomb平台，支持批量发送和压缩，减少网络开销
• 灵活配置选项：通过环境变量、配置文件或Kubernetes ConfigMap/Secret实现灵活配置，支持自定义采样率、数据过滤、字段重命名等高级功能
• 轻量级设计：最小化镜像体积，低资源占用（CPU/内存），适合在资源受限的Kubernetes环境中部署

使用场景和适用范围

• 微服务监控：适用于Kubernetes集群中运行的微服务架构应用，需跨服务追踪请求流、识别性能瓶颈
• 分布式系统调试：定位分布式应用中的异常行为、错误和延迟问题，缩短故障排查时间
• 生产环境可观测性：为生产环境中的Kubernetes部署提供实时监控，确保应用健康运行，及时发现并响应问题
• 开发/测试环境验证：在开发或测试阶段收集应用行为数据，验证新功能性能和正确性
• 多集群管理：支持跨多个Kubernetes集群的应用部署，统一收集和分析遥测数据

使用方法和配置说明

前提条件

• 拥有Honeycomb账户和API密钥（可在Honeycomb控制台获取）
• Kubernetes集群（v1.16+），支持DaemonSet、Deployment等资源类型
• 集群网络可访问Honeycomb API端点（默认：[***]

部署方式

在Kubernetes中部署（推荐）

通常通过DaemonSet在每个节点上部署，或通过Sidecar容器注入到应用Pod中。以下是基本的DaemonSet配置示例：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: honeycomb-agent
  namespace: honeycomb
spec:
  selector:
    matchLabels:
      app: honeycomb-agent
  template:
    metadata:
      labels:
        app: honeycomb-agent
    spec:
      containers:
      - name: honeycomb-agent
        image: docker.xuanyuan.run/honeycombio/honeycomb-kubernetes-agent:latest
        env:
        - name: HONEYCOMB_API_KEY
          valueFrom:
            secretKeyRef:
              name: honeycomb-secrets
              key: api-key
        - name: HONEYCOMB_DATASET
          value: "k8s-cluster-metrics"
        - name: SERVICE_NAME
          value: "honeycomb-agent"
        - name: SAMPLERATE
          value: "1"  # 1:1采样，生产环境可根据数据量调整
        volumeMounts:
        - name: var-log
          mountPath: /var/log
        - name: var-lib-kubelet
          mountPath: /var/lib/kubelet
      volumes:
      - name: var-log
        hostPath:
          path: /var/log
      - name: var-lib-kubelet
        hostPath:
          path: /var/lib/kubelet

Docker run示例（单机测试）

bash
docker run -d \
  --name honeycomb-agent \
  -e HONEYCOMB_API_KEY="your-api-key" \
  -e HONEYCOMB_DATASET="test-dataset" \
  -e SERVICE_NAME="local-test" \
  -v /var/log:/var/log \
  docker.xuanyuan.run/honeycombio/honeycomb-kubernetes-agent:latest

核心配置参数

环境变量

配置文件

除环境变量外，还可通过挂载配置文件（如/etc/honeycomb/config.yaml）进行更复杂的配置，例如：

yaml
dataset: "k8s-cluster-metrics"
api_key: "${HONEYCOMB_API_KEY}"  # 可引用环境变量
sampling:
  rate: 100
  rules:
    - service: "payment-service"
      rate: 50  # 为特定服务设置不同采样率
processors:
  - type: "filter"
    exclude:
      fields: ["sensitive_field"]  # 排除敏感字段

验证部署

1. 检查Pod状态：kubectl get pods -n honeycomb，确保honeycomb-agent Pod运行正常
2. 查看Pod日志：kubectl logs -n honeycomb <pod-name>，确认无错误日志，数据发送成功
3. 登录Honeycomb控制台，在指定数据集中查看是否接收到遥测数据